From 98889815d4a85188d214e27e67cb663c1263be5e Mon Sep 17 00:00:00 2001 From: Amplifier <240397093+microsoft-amplifier@users.noreply.github.com> Date: Sun, 6 Sep 2026 01:53:29 -0700 Subject: [PATCH] =?UTF-8?q?converge:=20post-lock=20cycle=202026-09-06=20?= =?UTF-8?q?=E2=80=94=20operator-surface.v2-candidate=20(6=20review-found?= =?UTF-8?q?=20wording=20fixes,=20awaiting=20owner's=20word);=20lvn=20ledge?= =?UTF-8?q?r=20prose=20true-up=20(OSV1-024/025=20+=20probe=20docstring);?= =?UTF-8?q?=20docs/workflow=20PLAN=20+=20return=20log?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- contracts/operator-surface.v2-candidate.md | 513 +++++++++++++++++++++ docs/workflow/OWNER-RETURN-LOG.md | 23 + docs/workflow/PLAN.md | 29 ++ ledger/checks/test_operator_rows.py | 6 +- ledger/rows.yaml | 20 +- 5 files changed, 583 insertions(+), 8 deletions(-) create mode 100644 contracts/operator-surface.v2-candidate.md create mode 100644 docs/workflow/OWNER-RETURN-LOG.md create mode 100644 docs/workflow/PLAN.md diff --git a/contracts/operator-surface.v2-candidate.md b/contracts/operator-surface.v2-candidate.md new file mode 100644 index 0000000..ed2c33b --- /dev/null +++ b/contracts/operator-surface.v2-candidate.md @@ -0,0 +1,513 @@ +# Proposal — operator-surface v1, six post-lock text corrections + +``` +target: contracts/operator-surface.v1.md +``` + +**Date:** 2026-09-06 +**Author:** agent:converge-manager via proposal-drafter +**Status:** PROPOSED — awaiting the owner's word +**Against:** `contracts/operator-surface.v1.md`, Status FROZEN, `main` @ `279a6ef` +**Evidence source:** `.amplifier/converge/operator-surface-freeze9-review.md` — the Freeze 9 +external review (independent reviewer, not the author): pass-1 findings 4, 6, 7, 8 and 9, and +pass-2 note 1. + +--- + +## What this proposal is + +Six sentence-level corrections to the locked text. Every one of them is a defect an +**independent review of the locked text** found and named — not a preference. None narrows a +promise, none widens a check, and none moves a single line of `src/` or of any kit. Five of the +six make the contract say what the machinery already does; the sixth repairs two triggers that +cannot fire. + +Each change below carries: the target line quoted verbatim from the locked file as it reads +today, the exact before/after pair, the evidence, and what does not change. + +**Line numbers below were re-measured against `279a6ef` on 2026-09-06.** They drifted after +true-up #2, so the review's own `:NN` pointers no longer land; the quoted bytes are what bind. + +--- + +## Change 1 — Core 1: route the "leads" judgment to a cadence instead of leaving it unchecked + +**Target line (`contracts/operator-surface.v1.md`, Core 1 clause body, line 19):** + +> The L0 hero region carries throughput over a stated window, presented together with the counts an operator acts on: in flight (held), blocked, needs attention, and open/ready. Observability leads the page; no other figure displaces the hero. + +The clause's second sentence is a "leads" judgment. Core 12 declares exactly that class of +judgment undecidable by any check. The Core 1 machine check reaches presence only. So the clause +promises more than anything asserts it, and says nothing about that gap. + +**Recommended: route it, do not drop it.** The sentence is the owner's ratified intent +("Focus is on observability", Changelog 2026-09-04). Deleting it would lose the intent to close +a bookkeeping hole. Naming how it is carried keeps the intent and makes the contract honest. + +Current text (lines 21–23): + +``` +**Machine check:** `hero.velocity_and_counts` — the rendered L0 hero region contains a velocity figure with its window stated, and each of the four named counts. + +**Tier:** A +``` + +Replacement: + +``` +**Machine check:** `hero.velocity_and_counts` — the rendered L0 hero region contains a velocity figure with its window stated, and each of the four named counts. The check reaches presence only; "leads" is not decided by it. + +**Tier:** A + +**Reviewed at cadence:** the "leads" sentence is the judgment Core 12 names NOT-ASSERTABLE; it is carried by the same owner review of L0/L1/L2, at each `ledger/reconcile-report.md` re-check. +``` + +**Evidence — a failure caught by review.** Freeze 9, pass 1, finding 4: + +> **Core 1 (`:19`)** — "Observability leads the page; no other figure displaces the hero" is +> precisely the "leads" judgment Core 12 (`:153`) declares undecidable by any check. The check +> (`:21`) covers only *presence* of a figure with its window plus four counts. Either drop the +> sentence or route it to Core 12's cadence. + +Verified against the locked text: Core 12's machine check reads "none — \"leads\" is a judgment +about what a human reads first, which no static or rendered assertion can decide" +(`contracts/operator-surface.v1.md:153`), and Core 1's check names only a velocity figure and +four counts (`:21`). The two clauses contradict each other as locked. + +**What does NOT change.** The clause body (line 19) is untouched, including the "leads" sentence +itself. `hero.velocity_and_counts` is not modified — the added half-sentence describes the check +that already exists. Tier stays A. OSV1-001 quotes line 19 only, so its quote still verifies. + +--- + +## Change 2 — Core 4: put the "growth is not convergent" rule in the clause + +**Target line (`contracts/operator-surface.v1.md`, Core 4 clause body, line 55 — final sentence):** + +> The register lives in `ledger/`, not in this contract, so that shrinking it is a convergent change requiring no amendment. + +The clause states the rule for shrinking and is silent on growth. The rule for growth exists and +is enforced — but only in `ledger/rows.yaml`, OSV1-006's notes. This is the same defect class the +reviewer used to block RC-1 before the lock: *"A ledger note does not travel with a locked +clause."* + +Current text (final sentence of line 55): + +``` +The register lives in `ledger/`, not in this contract, so that shrinking it is a convergent change requiring no amendment. +``` + +Replacement: + +``` +The register lives in `ledger/`, not in this contract, so that shrinking it is a convergent change requiring no amendment. Growth is not convergent: a new inline computed-geometry site absent from the register fails the check loudly, and adding it to the register is a deliberate, recorded act, never a silent one. +``` + +**Evidence — a failure caught by review.** Freeze 9, pass 1, finding 7: + +> **Core 4 (`:55`)** says shrinking the exemption register needs no amendment and is silent on +> *growth*. The "an INCREASE fails the probe loudly" rule lives only in OSV1-006's notes. One +> clause sentence closes it. + +The rule the reviewer points to, verbatim from `ledger/rows.yaml`, OSV1-006 notes: + +> A DECREASE is convergent (shrink the register, let the ledger confirm). An INCREASE — a new +> inline computed site not listed here — fails the probe loudly. + +Measured on `279a6ef` by the ledger's own census (`_support.inline_style_sites()`): 55 inline +`style=` sites — 47 token-referencing, 8 computed-geometry, **0 literal**; +`_support.style_block_literal_sites()` returns 0. The register is exactly the 8. + +**What does NOT change.** `visual.single_source` is not modified — the added sentence states the +behaviour the probe already has. The register stays in `ledger/`, out of the contract, and no +ceiling constant enters Core (Phase-1 ruling Need 2 is untouched). Shrinking stays convergent. +Backlogged 2's trigger — the register reaching zero — is unaffected. OSV1-005 and OSV1-006 quote +earlier sentences of line 55, so both quotes still verify against the appended paragraph. + +--- + +## Change 3 — Core 5: name the predicate inline, and name the audit's bound (RC-1 residual) + +**Target line (`contracts/operator-surface.v1.md`, Core 5 machine check, line 69):** + +> **Machine check:** `reads.never_write` — a route audit over every registered handler, asserting the clause's first sentence against each read-only one. + +Two problems in one line. First, "the clause's first sentence" has two halves — +*no `GET` handler reaches a mutating adapter call*, and *writes happen only through `POST`* — and +the audit asserts only the first. Second, now that the word "reaches" sits in the clause, the +audit's bound is load-bearing and is stated nowhere in the contract. + +Current text: + +``` +**Machine check:** `reads.never_write` — a route audit over every registered handler, asserting the clause's first sentence against each read-only one. +``` + +Replacement: + +``` +**Machine check:** `reads.never_write` — a route audit over every registered handler, asserting of each read-only (`GET`/`HEAD`) one that it reaches no mutating adapter call. The audit is static, module-local, name-matched against the adapter's write verbs, and bounded at depth 4 (`ledger/checks/_support.py:746-800`); it does not reach the clause's second promise, that writes happen only through `POST`. +``` + +**Evidence — a failure caught by review.** Freeze 9, pass 2, note 1 (the RC-1 residual, recorded +at the moment RC-1 landed): + +> **Residual (proposal):** `:69` now says "asserting the clause's first sentence", whose second +> half (writes only via `POST`) the audit never asserts — true on this tree (8 POST-only writers, +> verified) and partly guarded by the 30/22 pin, but under-tested, and less legible than naming +> the predicate inline. That line should also carry the audit's bound (pass-1 finding 6: static, +> module-local, depth-4), now that "reaches" sits in the *clause*. + +And pass 1, finding 6: + +> **Core 5's audit is narrower than "reaches"** — static, module-local, depth-4, name-matched +> (`ledger/checks/_support.py:746-799`). OSV1-007 names the limit; the contract does not. + +Verified in source. `route_audit()` spans `ledger/checks/_support.py:746-800` (the reviewer's +`:799` is one line short of the closing `return audited` at `:800`). It parses each route module +with `ast.parse` (**static**), resolves helpers only from that module's own `funcs` table +(**module-local**), walks `for _ in range(4)` (**depth 4**), and tests `name in MUTATING_VERBS` +(**name-matched**). Its own docstring says so: + +> Static and module-local, bounded at depth 4 -- the honest limit is recorded in ledger row +> OSV1-007's notes rather than hidden here. + +Re-run on `279a6ef`: 30 routes, 22 read-only, **0** reaching a mutating adapter call. + +**What does NOT change.** `route_audit()` and `test_row_osv1_007` are not touched — this line is +brought into agreement with the check that already exists, exactly as RC-1 brought the clause +into agreement with it. The clause body (line 67) is untouched, including the `GET /auth/logout` +exception, so OSV1-007's quote still verifies. The 30/22/0 numbers do not move. Tier stays A. + +--- + +## Change 4 — Core 12 and Core 13: define "ENCODE gate" once, at first use + +**Target lines (`contracts/operator-surface.v1.md`, lines 157 and 171):** + +> **Reviewed at cadence:** owner review of L0/L1/L2 at each ENCODE gate and before any Freeze stamp, and at each `ledger/reconcile-report.md` re-check. + +> **Reviewed at cadence:** owner review at each ENCODE gate and at each `ledger/reconcile-report.md` re-check; promoted by Backlogged 6. + +"ENCODE gate" appears four times in the contract (`:157`, `:171`, `:385`, `:386`) and is defined +at none of them. A non-engineer reading the two clauses no machine check carries cannot locate +the event those clauses depend on. + +**Recommended: define it, do not replace it.** RC-3 already added the in-repo standing trigger +(`ledger/reconcile-report.md` re-check), so neither cadence is stranded. What is left is a term a +reader cannot resolve. The definition below is phrased from the Changelog's own two uses of it — +`:385` "**ENCODE gate:** owner reviewed the DRAFT text and ratified it", and `:386` "First draft, +authored at the ENCODE gate from Phase-0 evidence". + +**Change 4a — Core 12, line 157.** Current text: + +``` +**Reviewed at cadence:** owner review of L0/L1/L2 at each ENCODE gate and before any Freeze stamp, and at each `ledger/reconcile-report.md` re-check. +``` + +Replacement: + +``` +**Reviewed at cadence:** owner review of L0/L1/L2 at each ENCODE gate — the authoring checkpoint at which the owner reads and ratifies drafted contract text, the event this contract's 2026-09-04 Changelog entries record — and before any Freeze stamp, and at each `ledger/reconcile-report.md` re-check. +``` + +**Change 4b — Core 13, line 171.** Current text: + +``` +**Reviewed at cadence:** owner review at each ENCODE gate and at each `ledger/reconcile-report.md` re-check; promoted by Backlogged 6. +``` + +Replacement: + +``` +**Reviewed at cadence:** owner review at each ENCODE gate (defined in Core 12) and at each `ledger/reconcile-report.md` re-check; promoted by Backlogged 6. +``` + +**Evidence — a failure caught by review.** Freeze 9, pass 1, RC-3: + +> "ENCODE gate" is also never defined anywhere in the contract, which fails "a non-engineer could +> understand it." + +Re-affirmed in pass 2, note 3, after RC-3 landed: + +> **"ENCODE gate" is still undefined** (`:157`, `:171`, `:385-386`). Acceptable post-lock: each +> cadence now has one trigger a reader can locate in-repo, so neither clause is carried by an +> expired event. Proposal, not blocker. + +Verified: `grep -n 'ENCODE' contracts/operator-surface.v1.md` returns exactly those four lines, +and none is a definition. + +**What does NOT change.** Both machine-check lines (`:153`, `:167`) are untouched, so OSV1-018's +and OSV1-019's quotes still verify. Both clauses stay NOT-ASSERTABLE; no check is invented for +either. RC-3's standing trigger survives verbatim in both cadences. Backlogged 6's promotion +route from Core 13 is unchanged. The Changelog's own uses of the term (`:385`, `:386`) are not +edited — they are the source the definition is drawn from. + +--- + +## Change 5 — Core 2: re-anchor two drifted evidence pointers + +**Target line (`contracts/operator-surface.v1.md`, Core 2 evidence line, line 37):** + +> *(Brief A §2, webtheme.py:169-188, webtheme.py:1338; Brief B §5, DESIGN-SYSTEM.md:63-64, DESIGN-SYSTEM.md:66-68)* + +Current text: + +``` +*(Brief A §2, webtheme.py:169-188, webtheme.py:1338; Brief B §5, DESIGN-SYSTEM.md:63-64, DESIGN-SYSTEM.md:66-68)* +``` + +Replacement: + +``` +*(Brief A §2, webtheme.py:211-230, webtheme.py:1430; Brief B §5, DESIGN-SYSTEM.md:63-64, DESIGN-SYSTEM.md:66-68)* +``` + +**Evidence — a failure caught by review.** Freeze 9, pass 1, finding 9: + +> **Line citations have drifted.** Core 2 cites `webtheme.py:169-188` for the three status hues; +> those lines are now an `--ink-tertiary`/`--ink-quiet` comment. Freeze 7 verifies *quotes*, not +> `file:line` pointers, so this passes the bar honestly — but it misleads a reader who follows +> the evidence. + +**This is a readability defect, not a Freeze 7 break.** Freeze 7 binds quotations, not pointers, +so the contract does not currently lie by its own bar. It does mislead every reader who follows +the citation. + +Re-measured on `279a6ef`, and the drift is exactly +42 lines, verified at both ends against the +contract's seed commit `4aaee50`: + +| pointer | at `4aaee50` (when written) | at `279a6ef` (today) | +|---|---|---| +| `webtheme.py:169` | ` --alarm:#f59e0b;` | line 211, same bytes | +| `webtheme.py:188` | ` --watch-ink-on-surface:#d6def2;` | line 230, same bytes | +| `webtheme.py:1338` | ` marker + bold weight, never a bespoke third hue. */` | line 1430, same bytes | + +Today `webtheme.py:169-188` lands mid-way through the `--ink-tertiary` and `--ink-quiet` +comments, exactly as the reviewer reported. The three status hues now sit at `--alarm:211`, +`--blocked:214`, `--watch:228`, inside the `RESERVED STATUS` block at `:210-231`. + +**Measured by this drafter, not named by the reviewer:** the second pointer on the same line, +`webtheme.py:1338`, has drifted the same +42 to `:1430`. It is included because leaving one +correct and one wrong pointer on a single evidence line is worse than either state. + +**What does NOT change.** No clause text, no machine check, no tier. The `DESIGN-SYSTEM.md` +pointers are untouched (that file is out-of-repo; nothing in this repo can verify or re-measure +them, and this proposal does not pretend otherwise). `webtheme.py` is not edited — a drifted +pointer is fixed at the pointer, never by moving the code under it. OSV1-002 and OSV1-003 quote +Core 2's clause body, not this line, so both quotes still verify. + +--- + +## Change 6 — Backlogged 2, 4 and 6: figures that drifted, and two triggers that cannot fire + +**Target lines (`contracts/operator-surface.v1.md`, lines 193, 209, 225):** + +> **Trigger:** the exemption register named in Core 4 reaches zero. *(Brief A §2, "137 `style=` occurrences, 134 of them outside `webtheme.py`")* + +> **Trigger:** the first reclaim the owner missed on screen. *(Brief A §3, `__init__.py:711`)* + +> **Trigger:** the first alarm-to-acknowledgement measurement exists. *(Brief B §6, wt-v2-poa.md:242-244)* + +A Backlogged clause is held behind a trigger; a trigger that cannot be observed holds its clause +forever. Two of these cannot fire, and one cites a figure that is three orders of magnitude off. + +**Change 6a — Backlogged 2, line 193.** Current text: + +``` +**Trigger:** the exemption register named in Core 4 reaches zero. *(Brief A §2, "137 `style=` occurrences, 134 of them outside `webtheme.py`")* +``` + +Replacement: + +``` +**Trigger:** the exemption register named in Core 4 reaches zero. *(Brief A §2, at Phase 0: "137 `style=` occurrences, 134 of them outside `webtheme.py`"; measured 2026-09-06 on this tree: 0 literal, 8 computed-geometry sites on the register)* +``` + +**Change 6b — Backlogged 4, line 209.** Current text: + +``` +**Trigger:** the first reclaim the owner missed on screen. *(Brief A §3, `__init__.py:711`)* +``` + +Replacement: + +``` +**Trigger:** the owner reports a reclaim they did not see on the web surface. *(Brief A §3, `__init__.py:711`)* +``` + +**Change 6c — Backlogged 6, line 225.** Current text: + +``` +**Trigger:** the first alarm-to-acknowledgement measurement exists. *(Brief B §6, wt-v2-poa.md:242-244)* +``` + +Replacement: + +``` +**Trigger:** an alarm-to-acknowledgement interval is recorded by any means — instrumentation, a log, or the owner timing one by hand. *(Brief B §6, wt-v2-poa.md:242-244)* +``` + +**Evidence — a failure caught by review.** Freeze 9, pass 1, finding 8: + +> **Backlogged triggers 4 and 6 are not observable.** B4 fires on "the first reclaim the owner +> missed on screen" — by construction, a missed thing. B6 fires on "the first +> alarm-to-acknowledgement measurement," which nothing in the repo produces and Core 13 says has +> never been measured. B2 quotes "137 `style=` occurrences, 134 outside `webtheme.py`" — now 0 +> literal / 8 computed. + +Verified. B4's trigger is self-defeating as the reviewer states: nobody can observe the first +thing the owner *missed*; what is observable is the owner saying afterwards that they missed it. +B6's trigger names a measurement that Core 13 itself says does not exist ("no number is asserted, +because none has been measured") and that no code in this repo emits; as written it can be +satisfied only by the very instrumentation its own clause would govern. B2's figures re-measured +on `279a6ef`: **0 literal, 8 computed** (`_support.inline_style_sites()` → 47 TOKEN / 8 COMPUTED +/ 0 literal; `_support.style_block_literal_sites()` → 0). + +**Deviation from the brief this proposal was drafted under, stated plainly.** The instruction was +to "true up B2's numbers". I did not overwrite them. The string "137 `style=` occurrences, 134 of +them outside `webtheme.py`" is a **verbatim quotation of Brief A**, a Phase-0 evidence document +outside this repo. Rewriting the numbers inside the quotation marks would turn a true citation +into a fabricated one — Brief A does not say "0 and 8". OSV1-033 records this exact string as an +out-of-repo honest limit, and its own probe re-measured it as accurate for its time: + +> (For the record, the SEED reconcile re-measured Brief A's claim against the tree: 137 total, +> 134 outside `webtheme.py` -- exactly right.) + +So the quotation is preserved byte-for-byte and dated, and the current measurement is added +beside it. That closes the misleading-figure defect without breaking a quote. If the owner +prefers the quotation simply deleted, that is a ratify-with-edits away. + +**What does NOT change.** Nothing here binds — the Backlogged section's own preamble says +"nothing here binds until then", and these three clauses remain unbound. No trigger is made +*easier* to fire in substance: B4 still needs a real missed reclaim, B6 still needs a real +interval; both are simply now stated as something a person can observe happening. B2's trigger +sentence — "the exemption register named in Core 4 reaches zero" — is untouched, and Brief A's +quotation is byte-identical. No Backlogged clause is promoted into Core by this proposal; that +remains an owner amendment. No ledger row quotes any of these three lines. + +--- + +## What does NOT change — the whole blast radius + +- **No `src/` change. No kit change. No probe change.** Nothing in + `src/amplifier_work_tracker/`, `tests/conformance/`, or `ledger/checks/` is edited by this + proposal. Every check keeps asserting exactly what it asserts today. +- **No check is widened or narrowed.** Changes 1 and 3 describe existing checks more precisely; + they do not change what runs. `pytest ledger/checks -q` (60 passed), `make ledger-mutate` + (69/69), and `make test-conformance-a` (41 passed, 1 xfailed) all keep the results they have + on `279a6ef`. +- **No promise is removed and no work that keeps a promise is broken.** These are additive + clarifications and pointer repairs. Nothing here is a new version of the contract. +- **No clause changes tier.** Core 1 stays A, Core 4 stays A, Core 5 stays A, Core 12 and Core 13 + stay NOT-ASSERTABLE. +- **No Core clause body is edited except Core 4's**, which gains one appended sentence. Core 1, + Core 5, Core 12 and Core 13 keep their clause bodies verbatim; only their machine-check, + cadence or evidence lines move. +- **No quotation is altered.** Brief A's B2 quotation is preserved byte-for-byte. The Changelog's + two `webapp.py:37-44` quotations are untouched. +- **The custody boundary is untouched.** `contracts/custody-coordination.v1.md` is not opened; + the citation stays one-way, as Phase-1 ruling Need 3 settled. +- **Status stays FROZEN.** This proposal does not unfreeze the contract; it is a v1 amendment, + not a v2 authoring. +- **Conformance 1–7, Reserved 1–6, and the Freeze Bar are untouched.** + +--- + +## Ledger consequence — one line, plus one trap worth naming + +On ratification, `OSV1-000` must be re-hashed for `contracts/operator-surface.v1.md` and the +mandatory full-ledger re-review of all 36 OSV1 rows performed — never a silent hash bump — with +the notes of `OSV1-001`, `OSV1-005`, `OSV1-006`, `OSV1-007`, `OSV1-018`, `OSV1-019` and +`OSV1-033` re-reviewed against the moved text. + +**Measured, and it differs from what this proposal was briefed to expect: no row's quote needs +re-anchoring.** Checked, not assumed — every one of these six changes was tested against the +quote each affected row actually carries in `ledger/rows.yaml`: + +| row | clause | what it quotes | disturbed? | +|---|---|---|---| +| OSV1-001 | Core 1 | clause body, line 19 | no — Change 1 edits `:21` and inserts after `:23` | +| OSV1-002 / -003 | Core 2 | clause body, line 31 | no — Change 5 edits the evidence line `:37` | +| OSV1-005 / -006 | Core 4 | sentences 1 and 2 of line 55 | no — Change 2 appends after sentence 3 | +| OSV1-007 | Core 5 | clause body, line 67 | no — Change 3 edits the machine check `:69` | +| OSV1-018 / -019 | Core 12 / 13 | machine-check lines `:153`, `:167` | no — Change 4 edits the cadence lines | +| — | Backlogged 2 / 4 / 6 | *no row quotes these* | n/a | + +A surviving quote is not a re-review, so the notes still need walking — several of them +(OSV1-006's INCREASE rule, OSV1-007's honest limit 2, OSV1-033's out-of-repo B2 paragraph) +describe precisely the text these changes move into the contract. + +**The trap.** `test_row_osv1_033` asserts that the **Changelog** cites exactly one in-repo file: + +```python +cited = {m.group(1) for m in _SOURCE_CITE.finditer(changelog)} +assert cited == {"webapp.py"} +``` + +`_SOURCE_CITE` is `` r"`([A-Za-z_][A-Za-z_0-9]*\.py):(\d+(?:-\d+)?)`" `` — any backticked +`.py:` inside the `## Changelog` section. So the ratifying Changelog entry **must not +write `` `webtheme.py:211-230` `` (or any other non-`webapp.py` file:line) in backticks**, or +OSV1-033 goes red on a bookkeeping detail. Describe Change 5 in prose, or extend the probe in the +same change. Core 2's evidence line itself is safe: it lives outside the Changelog and carries no +backticks. + +--- + +## Not in this proposal — seen, and deliberately left out + +1. **Core 10's `xfail(strict=True)` — a source change, not a contract change.** + `test_antigoals_enforced` (`tests/conformance/operator_surface/test_tier_a.py:1108`) is + `xfail(strict=True)` because `_oldest_ready_item` (`src/amplifier_work_tracker/webapp.py:902`) + calls `bd.list` with no `limit`. Verified on `279a6ef`: `grep -rn '_oldest_ready_item' src/` + returns **one** line — its own definition. The function is dead. OSV1-015 reads CONFORMS + honestly, because Core 10 scores calls "reached from a view" and dead code is not reached from + a view. The clause is correct as written; **the fix is deleting the dead function**, which + retires the marker and restores Core 10's unbounded-query conjunct to catching things. + → **File as a work item: delete `_oldest_ready_item` from `webapp.py` and remove the + `xfail(strict=True)` marker in the same change.** No contract text is involved. + +2. **Kit docstrings still quote pre-RC-2 wording** (Freeze 9, pass 2, note 2: *"Nit: kit + docstrings still quote pre-RC-2 wording"*). Also a source-side change, in + `tests/conformance/operator_surface/browser/test_tier_b.py`, not contract text. Named here so + it is not lost; not drafted here because a contract proposal is the wrong instrument for it. + +3. **Backlogged 4's own citation `` `__init__.py:711` `` is a dead pointer.** Measured on + `279a6ef`: `src/amplifier_work_tracker/__init__.py` is **9 lines long**. The reviewer did not + name this; I found it while verifying Change 6. It is left out because repairing it needs a + ruling on what it was meant to point at — the reclaim path has moved since Brief A — and + guessing a pointer is how the Change 5 defect was created in the first place. + → **Returned as a need:** someone who knows the Brief A §3 reference should say what + `__init__.py:711` was citing before it can be re-anchored. + +4. **Nothing was left out as a preference.** Each of the six changes above traces to a named + finding in an independent review of the locked text, and each was re-verified against + `279a6ef` before being drafted. The one place I departed from the drafting brief — preserving + Brief A's quotation in Change 6a rather than overwriting its numbers — is argued in that + section rather than done silently. + +--- + +## The owner's word + +One of four: **ratified** · **ratified as edited** · **declined** · **later**. + +Write the stamp on the blank line below, **on its own line**, starting at the very beginning of +that line with the word `ratified` and containing `by owner`. The two forms the guard accepts: + +- `ratified by owner` +- `ratified as edited by owner` + +A stamp written anywhere else, or with anything in front of it on the line, will not unlock +`contracts/operator-surface.v1.md`. If the answer is **declined** or **later**, write that word +instead — the guard will simply not open the file, which is the correct outcome. + +Owner's word: ______ + + + + + + +**Landing a ratified change is a separate, owner-gated step.** This proposal edits nothing. The +locked file is untouched by it. diff --git a/docs/workflow/OWNER-RETURN-LOG.md b/docs/workflow/OWNER-RETURN-LOG.md new file mode 100644 index 0000000..0c4fa18 --- /dev/null +++ b/docs/workflow/OWNER-RETURN-LOG.md @@ -0,0 +1,23 @@ +# Owner return log + +One entry per return of the intent steward (clock-stamped) or per unprompted brief (date only). Newest last. + +## 2026-09-06 08:39 - they came back to a locked contract and switched the session to converge-manager + +**Time away.** About eleven hours since you said "looked, ratify." last night; one lock landed in that time (PR #88, the operator-surface contract went FROZEN), and no lanes ran — this cycle was housekeeping, not a wave. + +**Finished.** The contract is locked and the ledger agrees with it (I re-ran `pytest ledger/checks` — 60 passed — and `make ledger-mutate` — 69 of 69 mutations still turn their probe red); the stale "pinning" prose on two ledger rows is trued up in this PR (the same two checks re-run green after the edit, and a scan for pin-prose above a green row now finds none); a proposal file for six small wording fixes the external reviewer found is written beside the locked contract and waits for your word; the one remaining code residue (a dead function that keeps one Tier-A check deferred) is filed as a claimable item. + +**Stuck.** Nothing stopped — but one question could not be answered on this machine: the contract's Backlogged 4 cites `__init__.py:711`, a file that is nine lines long today, and nobody here knows what the original brief was pointing at, so that pointer is left as-is in the proposal rather than guessed. + +**Needs you.** Two words: **ratify** (or "ratified as edited" / "declined") for `contracts/operator-surface.v2-candidate.md`, and **priority** — yes or later — for the Core 10 dead-function item `zhv`, which is a code change on a locked surface and I will not launch a lane for it without your word. + +**Anything quietly broken.** The lock's in-session guard did not fire: I edited the frozen contract from this session twice (once in each mode) and both edits went through — I reverted them at once and nothing reached git — because the guard's file patterns are relative to the session's working directory, which here is the multi-repo folder above the repo; the check that runs in CI (the ledger's hash row) does catch such an edit, so the repository was never actually exposed, and I have added the fix to this workspace's settings (active next session) and filed the defect against the converge bundle as `converge-qfi9`. + +
Technical detail + +- Lock: `contracts/operator-surface.v1.md` `**Status:** FROZEN` @ 279a6ef; OSV1 33 CONFORMS / 3 NOT-ASSERTABLE / 0 GAP / 0 VIOLATION; Freeze 1–10 met (1–7 measurement, 8+10 owner's recorded acts, 9 external review ×2). +- Guard: `hooks-candidate-guard` `normalize_repo_relative(path, cwd)` → `amplifier-work-tracker/contracts/…` ≠ `contracts/*.md`; pure-evaluator proof: cwd=repo → deny, cwd=workspace → continue, `**/`-prefixed globs → deny. Override in `.amplifier/settings.yaml` (workspace). +- This PR: v2 candidate (6 changes, evidence = Freeze 9 review), `lvn` prose repair (OSV1-024/025 + `test_row_osv1_025` docstring), `docs/workflow/{PLAN,OWNER-RETURN-LOG}.md`. +- Queue: `zhv` (Core 10 residual, ready), `1y2` (external), `lvn` (held → resolving on merge). +
diff --git a/docs/workflow/PLAN.md b/docs/workflow/PLAN.md new file mode 100644 index 0000000..b3dd378 --- /dev/null +++ b/docs/workflow/PLAN.md @@ -0,0 +1,29 @@ +# Operating picture — amplifier-work-tracker under Converge + +Regenerated each manager cycle from the repository's history and the shared queue (project `work_tracker`). Newest cycle last. + +## Governing documents +- `contracts/custody-coordination.v1.md` — DRAFT (Freeze 9 = owner ratification still open). +- `contracts/operator-surface.v1.md` — **FROZEN** 2026-09-05 (PR #88 → 279a6ef). Changes only by `contracts/operator-surface.vN-candidate.md`. +- `docs/VISION.md` — DRAFT. + +## Landed (from git log, main) +- 2026-09-05 279a6ef converge(FREEZE): operator-surface.v1 FROZEN — owner-ratified true-up #2 (RC-1/2/3), Freeze 8 record, FROZEN stamp; OSV1 SYNC rehash + full re-review (#88) +- 2026-09-05 d039b32 ledger(reconcile): re-check 2026-09-05 after hw-operator-surface — Freeze 5 met by measurement, 0 red Core rows; Freeze Bar reading (#86) +- 2026-09-05 7e43e73 highway(operator-surface) wave 4: calm pixels, swap survival, rendered floors, empty states, CLI isolation — Freeze 5 met (0 red Core rows) (#85) +- 2026-09-05 065da04 highway(operator-surface) wave 3: one source of visual truth — zero literal colour/font/size outside the token module (Core 4) (#84) +- 2026-09-05 6c2e9fa highway(operator-surface) wave 2: Tier-B browser conformance kit + Core 10 fixes (bounded L1 query, theme persists) + integration (#83) +- 2026-09-05 aec9991 highway(operator-surface) wave 1: Tier-A conformance kit + L0 hero = velocity+counts + contrast floor (3 lanes) (#82) +- 2026-09-04 65f0e91 converge(SEED): operator-surface.v1 conformance ledger -- 36 OSV1 rows, 33 probes, 10 items filed (#80) +- 2026-09-04 4aaee50 converge(ENCODE): operator-surface.v1 DRAFT contract + repo vision extended to two seams (owner-ratified 2026-09-04) (#79) + +## Cycle 2026-09-06 (manager: this session; owner returned 08:39 UTC) +- Guard probe: an in-place `edit_file` on the FROZEN contract went through in BOTH evaluation and converge-manager modes. Root cause measured with the module's pure evaluator: `hooks-candidate-guard` globs are cwd-relative and this workspace's cwd is the multi-repo root, so `contracts/*.md` never matched `amplifier-work-tracker/contracts/*.md`. Repo-side lock (OSV1-000 SYNC probe) does bite in CI. Workspace override added to `.amplifier/settings.yaml` (`**/contracts/*.md` …), effective next session start; upstream defect filed as `converge-qfi9`. +- Proposal drafted: `contracts/operator-surface.v2-candidate.md` — six post-lock text fixes from the Freeze 9 review (Core 1 route-to-cadence, Core 4 register growth, Core 5 check bound, Core 12/13 "ENCODE gate" defined, Core 2 citations re-anchored, Backlogged 2/4/6 triggers made observable). One need returned: Backlogged 4's `__init__.py:711` pointer is dead and nobody on the machine knows what Brief A §3 cited. +- Repaired in place (clause 8, five-edit class): `work_item_pipeline-lvn` — OSV1-024/025 stale PINNING lead-ins + OSV1-025 probe docstring; dispositions unchanged; ledger 60 passed, harness 69/69. +- Filed: Core 10 residual (dead `_oldest_ready_item`, Tier-A `test_antigoals_enforced` xfail) as a lane-ready item — see queue. +- 2026-09-06T08:52:47Z CALL ratify - contracts/operator-surface.v2-candidate.md needs your word ("ratified" / "ratified as edited" / "declined"). Parked: the v2 amendment + its ledger re-hash. Continued: lvn repair (this PR), Core 10 residual item filed and claimable, converge-qfi9 filed upstream. + +## Queue (work_tracker) at this cycle +- ready: `1y2` (external, not this operation) + the Core 10 residual item filed this cycle. Held: `lvn` (this session, resolving on merge). +- Width: 0 lanes running; nothing under width — the only lane-shaped item is the Core 10 residual, held for the owner's priority word since it is a src change on a frozen surface (kit + ledger re-derivation). diff --git a/ledger/checks/test_operator_rows.py b/ledger/checks/test_operator_rows.py index c1b1a42..a3dee7f 100644 --- a/ledger/checks/test_operator_rows.py +++ b/ledger/checks/test_operator_rows.py @@ -1724,8 +1724,10 @@ def test_row_osv1_024() -> None: def test_row_osv1_025() -> None: - """Conformance 6 pin: the fixture exists, reads THIS ledger's register, and - its GOOD half is still deferred against OSV1-005.""" + """Conformance 6, CONFORMS: the fixture exists, reads THIS ledger's register, + and its GOOD half runs undeferred and passes (flipped 2026-09-05 after OSV1-005 + went green; direction REGRESSION). Docstring trued up 2026-09-06, lvn -- it used + to read "still deferred against OSV1-005", the opposite of the assertion below.""" kit = _kit_source() assert "check_visual_single_source" in _kit_defs(kit), ( f"OSV1-025 (Conformance 6): {TIER_A_KIT} no longer implements " diff --git a/ledger/rows.yaml b/ledger/rows.yaml index 1152f65..bbf8dea 100644 --- a/ledger/rows.yaml +++ b/ledger/rows.yaml @@ -2805,9 +2805,13 @@ kind: probe ref: test_row_osv1_024 notes: > - PINNING ROW -- the fixture exists and discriminates, but its GOOD half does - not pass, so the probe pins that deferral. A passing probe here is NOT - conformance. Flip direction VIOLATION-MOVEMENT. + FLIPPED GAP -> CONFORMS 2026-09-05 (highway wave-1 integration): Conformance 5's + GOOD half runs undeferred and PASSES on the real L0. Flip direction is now + REGRESSION (a re-deferral or a failing good half turns the probe red). + Prose trued up 2026-09-06 (work_item_pipeline-lvn); the pin text below is + kept as dated history. Was a PINNING row: "the fixture exists and discriminates, + but its GOOD half does not pass, so the probe pins that deferral. A passing + probe here is NOT conformance. Flip direction VIOLATION-MOVEMENT." MEASURED 2026-09-05. `tests/conformance/operator_surface/test_tier_a.py` implements `hero.velocity_and_counts` at the location Conformance 5 names, @@ -2850,9 +2854,13 @@ kind: probe ref: test_row_osv1_025 notes: > - PINNING ROW -- the fixture exists and discriminates, but its GOOD half does - not pass, so the probe pins that deferral. A passing probe here is NOT - conformance. Flip direction VIOLATION-MOVEMENT. + FLIPPED GAP -> CONFORMS 2026-09-05 (highway wave-3 integration, after OSV1-005 went green): Conformance 6's + GOOD half runs undeferred and PASSES against this ledger's register. Flip direction is now + REGRESSION (a re-deferral or a failing good half turns the probe red). + Prose trued up 2026-09-06 (work_item_pipeline-lvn); the pin text below is + kept as dated history. Was a PINNING row: "the fixture exists and discriminates, + but its GOOD half does not pass, so the probe pins that deferral. A passing + probe here is NOT conformance. Flip direction VIOLATION-MOVEMENT." MEASURED 2026-09-05. `tests/conformance/operator_surface/test_tier_a.py` implements `visual.single_source` at the location Conformance 6 names: