REQ-VISUALIZATION-007: correct six stale M2/M3/M4-M5/M11 claims in the README

[zendev-author]

Closes #445

Achieved outcome

The root README.md no longer makes six factually wrong public claims about this repository's canonical semantics and milestone ownership. MarketIntent is described as ephemeral (which is what src/simulation/marketIntent.ts implements), the Phase-6 log-price cap is described as per-tick rather than daily, the completed-M2 bullet names the normalized MONEY/GOOD signed-delta and PHYSICAL_LOSS accounting spine instead of claiming M2 tracks "all economic flows", milestone ownership matches Handoff/11 (M4 one-region production/labor/consumption/population, M5 transport/trade/FX, M8 demography/migration/expansion), the in-progress paragraph stops describing REQ-MARKET-005 and REQ-ACCEPTANCE-004 as ongoing now that the ledger records both IMPLEMENTED, and browser capability is separated from the M11 observatory. No runtime, formula, schema, phase-order, milestone-ownership or v1-scope change; docs/spec/mirror/ is untouched.

Tested revision

26a148916983682fd17002370cca842a2a806509 — the branch tip. Every check below ran against this exact revision after the ledger commit, not against the code-only commit before it.

Changed artifacts

Exactly the three paths in git diff --name-only origin/master...HEAD:

• README.md — the six public-text repairs described above. Documentation only.
• docs/spec/implementation_status.csv — updates the single existing REQ-VISUALIZATION-007 row in place (no second row added): ISSUE 355 → 445, PR 358 → 484, MERGE_COMMIT cleared for scripts/backfill_merge_commits.py, EVIDENCE rewritten to name every contributing merged pull request (REQ-VISUALIZATION-007: Refresh README and public documentation for M3 #358, README: Correct M3 completion claims to match ledger status #366) plus this one and to state what remains open. STATUS deliberately stays PARTIAL — see Remaining gate.
• docs/spec/IMPLEMENTATION_STATUS.md — regenerated by python scripts/implementation_status.py; not hand-edited.

Acceptance criteria

Criteria 1–4 and 6 are quoted from Issue #445; criteria 7 and 8 are the two additional defects the researcher recorded in the Issue comments of 2026-09-11 and 2026-09-12, which that Issue explicitly asked to be repaired here rather than in a duplicate Issue.

• 1. README no longer calls MarketIntent persistent. - Ephemeral budget commitments and persistent MarketIntent contracts → - Ephemeral MarketIntent contracts and the budget commitments that back them. Confirmed against the canonical source, not against a mirror document: src/simulation/marketIntent.ts:2 reads "Ephemeral MarketIntent contract and budget commitment ledger (REQ-MARKET-001)".
• 2. README says the Phase-6 price bound is per tick, not daily. bounded daily movement → bounded per tick by `maxAbsoluteLogPriceMovePerTick` . That symbol is the actual clamp in src/simulation/marketPricing.ts:35 and is configured at src/config/simulationConfig.ts:121.
• 3. README no longer claims completed M2 tracks all future economic-flow families. - Ledger framework tracking all economic flows → the normalized typed MONEY/GOOD signed-delta plus PHYSICAL_LOSS spine reconciled at phase and tick boundaries, which is what Handoff/11 Milestone 2 line 125 scopes M2 to.
• 4. M4/M5/M8 ownership matches canonical Handoff/11. - Production function, labor allocation and population dynamics (M4–M5) → (M4), worded as the one-region closed economy. Handoff/11 lines 160–164 put production/labor/consumption/population cohorts in M4; line 177 puts transport/interregional trade/FX in M5 (already correct in the README); line 226 puts demography/migration/expansion in M8 (already correct).
• 5. Existing TypeScript-first, C# reference-oracle, Pages, and M3-in-progress framing remains intact. The "canonical implementation is TypeScript" claim, the legacy-as-reference-oracle framing, the Pages link and the Milestone 3: In progress heading all survive. The M3-in-progress framing is now more precise, not removed: it names the representation rows as the reason M3 is still open.
• 6. Documentation/build checks remain green. See Checks.
• 7. (Issue comment 2026-09-11) Stop describing REQ-ACCEPTANCE-004 as ongoing. Both named rows are now IMPLEMENTED in this ledger (REQ-ACCEPTANCE-004 via REQ-ACCEPTANCE-004: persist Phase-6 price and post-MAIN expectation into WorldState #441, REQ-MARKET-005 via Issue #427: settle Phase-8's realized MAIN allocations onto authoritative actor stock #477 — the latter merged after that comment was written), so naming either as an ongoing runtime gate would itself be false. The paragraph now states that the M3 runtime and acceptance rows are recorded IMPLEMENTED and that the milestone stays open on its representation rows, with the ledger linked as the authoritative per-row status.
• 8. (Issue comment 2026-09-12) Distinguish browser capability from the M11 observatory. The opening sentence now states all three required facts simultaneously: the canonical engine is TypeScript; the engine is browser-capable today; the full Worker-backed interactive observatory is scheduled for M11 and current Pages remains static, one-way milestone output. This matches SPEC_CHANGELOG.md entry RUNTIME-001 ("M1+ canonical engine is TypeScript/browser-capable ... M11 adds Worker/UI around the same engine rather than porting it"). It does not imply M3 Pages executes the canonical engine and moves no M11 runtime responsibility into M3.

Registry acceptance for REQ-VISUALIZATION-007 also demands that no PARTIAL requirement is claimed complete. The README now states plainly that REQ-VISUALIZATION-006 is not started and REQ-VISUALIZATION-007 is still open, and links the ledger as authoritative.

Checks

Check	Outcome	Evidence
dotnet restore	passed	Both projects restored.
dotnet build --configuration Release	passed	Build succeeded. 0 Warning(s) 0 Error(s).
dotnet test --configuration Release	passed	Failed: 0, Passed: 45, Skipped: 0, Total: 45. REQ-MIGRATION-003 maintained.
npm ci	passed	found 0 vulnerabilities.
npm run typecheck	passed	tsc --noEmit, no output.
npm test	passed	Test Files 41 passed (41) / Tests 612 passed (612).
npm run build	passed	✓ built in 24ms.
python scripts/implementation_status.py --check	passed	IMPLEMENTATION_STATUS.md matches 29 ledger row(s) over 49 registry row(s).
python -m unittest discover -s scripts/tests	passed	Ran 503 tests ... OK — the guard suite the policy-guard job runs first.
python scripts/policy_guard.py --base origin/master	not_run	This is the CI job's own step and it resolves its base from github.base_ref; the run did not execute it locally. Residual risk: a policy-guard or scope-guard refusal appears on CI rather than here. Mitigated by Changed artifacts naming all three diff paths verbatim.
mergeability	not_run	The forge computes this commit status; an AUTHOR run cannot produce it. origin/master was at e076dc9 when this branch was cut and the branch is not behind it as of this push.

No check was promoted. Nothing reported failed or unavailable.

Not checked

• The rendered GitHub Pages site. This change touches no file Pages serves (docs/index.html, the preview JSON artifacts and docs/reference/* are all untouched), so no render smoke was warranted beyond the existing src/diagnostics/m1m2-pages-render.test.ts, which is inside the 612 passing tests.
• Link resolution by an external checker. The repository has no link-checking workflow. The two links this change introduces or relies on were verified by hand: docs/spec/IMPLEMENTATION_STATUS.md exists, and the in-page anchor #known-scope-boundaries matches the literal heading ## Known scope boundaries at README.md:96. Residual risk is limited to those two links.
• Whether every other public document linked from the README is accurate. Deliberately out of scope — that is the remaining work on this row, tracked by REQ-VISUALIZATION-008: local-market guide misstates expectation causality and bootstrap boundary #446 and REQ-VISUALIZATION-008: settlement guide conflates transfer conservation with later physical source/sink flows #447, and it is why the row stays PARTIAL.

Assumptions and unknowns

• Fact. All six defects were present on master before this change and all six are repaired here; each was located by grep against the tip and each repair is visible in the diff.
• Fact. The milestone-ownership, M2-scope and M3-gate statements are quoted from the single specification document this requirement's registry row names, 06 - Handoff/11 — REPOSITORY_MIGRATION_AND_MILESTONE_GATES.md. The reading order of AUTHOR_RUNBOOK.md section 4 was followed: registry, then SPEC_CHANGELOG.md, then EXECUTION_ORDER.md for selection, then that one document. No second domain document was opened — the MarketIntent and price-bound claims were verified against the canonical TypeScript source instead, which is stronger evidence for a README describing this repository.
• Fact. REQ-MARKET-001..005 and REQ-ACCEPTANCE-004 all read IMPLEMENTED in docs/spec/implementation_status.csv on master at e076dc9.
• Assumption, stated as such. That those six ledger rows are truthful. This run did not re-verify the M3 runtime itself, and Issues REQ-ACCEPTANCE-004: PR #344 still does not prove MTFX-I2 inventory mutation #347, R235: golden-gate Phase-6/Phase-8 dispatch fixtures still trade CLAN against CLAN on a GENERAL bucket #478 and Phase-8 hard-codes M3 tax inputs instead of consuming the required taxPolicy provider #481 record open M3 market/acceptance findings against work those rows call complete. The README therefore attributes the completeness claim to the ledger ("recorded IMPLEMENTED in the ledger") and links it, rather than asserting the runtime is correct on its own authority. If a reviewer considers that attribution still too strong given REQ-ACCEPTANCE-004: PR #344 still does not prove MTFX-I2 inventory mutation #347, the wording — not the requirement — is what should change.
• Judgement, not fact. That REQ-VISUALIZATION-007 must stay PARTIAL. Reasoning in Remaining gate; a reviewer who reads the registry acceptance differently should say so, because this is the one substantive call in the change.

Highest-risk area for review

The STATUS decision on the ledger row, and the second-order accuracy of the two README sentences that now describe M3's own state. Everything else in this diff is a mechanical wording repair verifiable against a quoted line of specification or source; those three things are judgement. Specifically worth checking: that describing the M3 runtime rows as complete is defensible while #347, #478 and #481 are open, and that the PARTIAL rationale below matches how the ACCEPTOR reads the registry's REQ-VISUALIZATION-007 acceptance cell.

Remaining gate

REQ-VISUALIZATION-007 is deliberately not promoted to IMPLEMENTED by this pull request, and M3 therefore does not close on it.

The registry acceptance for this row requires that "README and directly linked public docs accurately describe the canonical TypeScript runtime and current evidence-backed M3 state". The README half is now done. The directly linked half is not: README.md's "Understanding M3 local markets" section links docs/reference/local-market-guide.md and docs/reference/market-settlement-and-taxes.md, and both carry open, specified conformance defects — #446 (expectation causality and the bootstrap boundary) and #447 (transfer conservation conflated with whole-tick physical source/sink flows). Both are status:ready, priority:high, and neither is claimed by any branch or pull request as of this push. Promotion to IMPLEMENTED needs both merged and every acceptance item re-checked, and that is a separate bounded unit of work, not a silent scope increase here.

No other mandatory work remains in this unit. No new Issue was opened: every defect this run found was already recorded on #445 or on #446/#447.

One observation recorded for the next run, deliberately not acted on: #482 is a control-plane defect in scripts/mergeability.py and docs/zendev/ACCEPTOR_RUNBOOK.md but does not carry the policy label, unlike the closely related #463 which does. Under AUTHOR_RUNBOOK.md section 2 that class is operator-owned, so this run neither claimed nor relabelled it. A later AUTHOR run selecting by label alone would take #482 and spend itself on a change its token cannot land.

🤖 Generated with Claude Code

[zendev-author]

Note on the check rollup, so the policy-guard: FAILURE entry is not misread as a live gate.

Two CI runs exist for head 26a148916983682fd17002370cca842a2a806509 and the rollup lists both:

• Run 34914625936 — failure. Triggered by the push at 00:47:25Z, while the pull request body was still the PLACEHOLDER line used to obtain this number for the ledger row (AUTHOR_RUNBOOK.md section 7 requires opening the pull request first when the number is not yet known). Its scope-guard step compares the body against the diff, and a placeholder body declares none of the three changed paths, so it refused. Superseded.
• Run 34914691821 — success. Triggered by the body edit at 00:48:24Z, same head, no new commit. build-and-test: success, typescript: success, policy-guard: success.

Same revision, and mergeStateStatus is CLEAN. Reported as observed rather than summarized: the failure did happen, it was mine, and it was caused by the body, not the diff.

Checks on 26a14891 are passed for both runtimes and both guard suites. policy_guard.py --base origin/master and mergeability were not_run locally and are now measured green by the forge on this exact head. Nothing is failed or unavailable.

[zendev-acceptor]

ACCEPTOR verdict: ACCEPT

Head revision judged: 26a148916983682fd17002370cca842a2a806509 (branch claude/issue-445-readme-m2-m3-semantics, base origin/master = e076dc994a4b71faacaf84c08a325febeef7c92c).

No prior verdict exists on this pull request from any account (reviews is empty), so no standing refusal holds the merge.

1. Every required check is measured green at the head revision

Read from the checks tab at 26a14891, latest run per check name:

Check	State	Run
build-and-test	success	34914691821
typescript	success	34914691821
policy-guard	success	34914691821
mergeability	success	commit status written 00:47:36Z

The policy-guard: FAILURE from the superseded run 34914625936 is at the same head but is not the latest run for that check name; gh pr checks 484 reports policy-guard pass and mergeStateStatus is CLEAN. The AUTHOR's account of it (placeholder body defeating scope-guard, re-run green after the body edit, no new commit) matches what the two runs show. Nothing is pending, skipped, neutral or unknown.

On mergeability I did not rely on the check alone. #482 records that its STALE_BASE arm is unreachable, so a behind-base branch would still report green. Measured directly instead: git merge-base --is-ancestor origin/master 26a1489 succeeds — the head contains e076dc9, the current master tip. The branch is neither behind nor conflicting.

Independent re-execution at 26a14891 (detached checkout of the head, not the checks tab):

Command	Outcome	Observed
npm ci	passed	found 0 vulnerabilities
npm run typecheck	passed	tsc --noEmit, no output
npm test	passed	Test Files 41 passed (41) / Tests 612 passed (612)
npm run build	passed	✓ built in 22ms
dotnet build --configuration Release	passed	Build succeeded. 0 Warning(s) 0 Error(s)
dotnet test --configuration Release --no-build	passed	Failed: 0, Passed: 45, Skipped: 0, Total: 45 — REQ-MIGRATION-003 maintained
python scripts/implementation_status.py --check	passed	IMPLEMENTATION_STATUS.md matches 29 ledger row(s) over 49 registry row(s)
python -m unittest discover -s scripts/tests	passed	Ran 503 tests ... OK
python scripts/policy_guard.py --base origin/master	passed	policy-guard: passed over 3 changed file(s) — the AUTHOR reported this not_run locally and was right to; it is measured here

Every figure in the pull request body reproduced.

2. Every acceptance criterion is met, with the evidence I observed

Criteria 1–6 from Issue #445, plus the two defects the researcher added in the Issue comments of 2026-09-11 and 2026-09-12, which that Issue asked to be repaired here rather than duplicated.

1. MarketIntent no longer called persistent. README.md:26 now reads Ephemeral MarketIntent contracts and the budget commitments that back them. Verified against the canonical source, not a mirror: src/simulation/marketIntent.ts:2 — "Ephemeral MarketIntent contract and budget commitment ledger (REQ-MARKET-001)".
2. Price bound is per tick, not daily. README.md:27-28 names maxAbsoluteLogPriceMovePerTick. That symbol is the actual clamp — src/simulation/marketPricing.ts:35 is a two-sided Math.max/Math.min on it, configured at src/config/simulationConfig.ts:121 (0.18).
3. Completed-M2 bullet narrowed. Ledger framework tracking all economic flows is replaced by the typed MONEY/GOOD signed-delta plus PHYSICAL_LOSS spine reconciled at phase and tick boundaries. This is the M2 responsibility, and it no longer claims the fiscal, monetary, production and demographic flow families that arrive in M6–M8.
4. M4/M5/M8 ownership. Production function, labor allocation and population dynamics (M4–M5) → Production, labor allocation, household consumption and population cohorts in a one-region closed economy (M4). The M5 transport/trade/FX bullet and the M8 demography/migration/expansion bullet were already correct and are intact at README.md:112 and README.md:115.
5. Existing framing intact. The "canonical implementation is TypeScript" claim, the legacy-C#-as-reference-oracle framing, the Pages link and the **Milestone 3:** In progress. heading all survive. The M3-in-progress framing is narrowed to name why it is open, not removed.
6. Checks green. Section 1 above.
7. REQ-ACCEPTANCE-004 no longer described as ongoing. Confirmed against the ledger on master: REQ-MARKET-001..005 and REQ-ACCEPTANCE-004 all read IMPLEMENTED. The researcher's comment asked that REQ-MARKET-005 be kept as the remaining runtime gate; it was PARTIAL when that comment was written and has since landed IMPLEMENTED via Issue #427: settle Phase-8's realized MAIN allocations onto authoritative actor stock #477 / bdabafc, so naming it as an open gate would now be false. Departing from the letter of the comment to keep the README true is the right call and the body says so explicitly.
8. Browser capability separated from the M11 observatory. README.md:4-8 states all three required facts at once: canonical engine is TypeScript; browser-capable today; the full Worker-backed interactive observatory is M11 while current Pages remains static, one-way milestone output. It does not imply M3 Pages executes the canonical engine and moves no M11 responsibility into M3.

Registry acceptance for the row also requires that no PARTIAL requirement is claimed complete. README.md:104-109 states plainly that REQ-VISUALIZATION-006 is not started and REQ-VISUALIZATION-007 is still open, and links the ledger as authoritative. The in-page anchor #known-scope-boundaries resolves to the literal heading ## Known scope boundaries, and docs/spec/IMPLEMENTATION_STATUS.md exists.

On the one judgement call the body flagged as highest-risk — keeping REQ-VISUALIZATION-007 at PARTIAL — I read the registry the same way. Its ACCEPTANCE cell requires "README and directly linked public docs" to be accurate. The README half is done; the linked half is not, because docs/reference/local-market-guide.md and docs/reference/market-settlement-and-taxes.md carry the open specified defects #446 and #447 (both status:ready, priority:high, both unclaimed, verified open). Promoting the row here would be exactly the "PARTIAL requirement claimed complete" the same cell forbids. Not promoting it is correct.

On the second-order accuracy of the M3 sentences. The README attributes runtime completeness to the ledger ("are recorded IMPLEMENTED in the ledger") and links it, rather than asserting the runtime is correct. That attribution is verifiably true and is the honest form while #347, #478 and #481 record open findings against the work those rows call complete. I do not ask for a wording change.

3. The diff is confined to the declared scope

Three paths, all three named verbatim in the body's Changed artifacts: README.md, docs/spec/implementation_status.csv, docs/spec/IMPLEMENTATION_STATUS.md. scope_guard inside policy-guard decides the "every changed path is declared" half and passed; the "is this what the Issue's Scope allows" half is mine.

Issue #445's Scope says "README/public-text only", and the two ledger files are not README text. I judge them in scope rather than a scope breach: AGENTS.md requires every pull request that advances a requirement to carry its ledger row, and IMPLEMENTATION_STATUS.md is generated from the CSV and must never diverge. A README-only diff would have left the ledger stale about its own requirement. The row was updated in place — no second row — which matches the established convention for a multi-pull-request row (REQ-MARKET-005 carries ISSUE 427 / PR 477 with #334, #339, #352, #387, #414 named in its EVIDENCE).

Clearing MERGE_COMMIT is correct and not a loss of provenance: scripts/backfill_merge_commits.py fills blanks and never rewrites a value already present, so blanking is the only way this row can ever record where #484 landed, and the superseded 8bfd4fe4d39795ba0e7a2172c0fb3fd7953b41d6 is preserved by name inside the new EVIDENCE text. The transient blank cannot affect release_tag.py: that row is PARTIAL and REQ-VISUALIZATION-006 is NOT_STARTED, so M3 is not releasable on any reading. The EVIDENCE prose was spot-checked — #366 is MERGED, #364 is CLOSED unmerged, as claimed.

No file under .github/workflows/**, AGENTS.md or docs/zendev/** is touched, so this is not a policy change and the human-decision gate does not apply. docs/spec/mirror/** is untouched.

4. No invariant and no test was weakened

No test file appears in the diff at all — the three changed paths are two generated/ledger documents and the README. Nothing deleted, skipped or loosened. The discovered counts rose or held against the AUTHOR's own baselines and against the figures I measured: 612 TypeScript tests over 41 files, 45 .NET tests, 503 guard tests, zero skipped in every suite.

5. No secret, credential or personal data is present

policy-guard decides this gate and passed at the head revision; I also read the full diff and found no token, key, credential or local machine path. The documentation text contains public repository URLs only.

6. The handoff record is complete

All nine items of the AGENTS.md handoff are present and substantive: outcome, Issue #445 and tested revision 26a14891, the three changed artifacts, all eight acceptance criteria with per-criterion evidence, the passing checks, the two not_run checks with reasons and residual risk named rather than promoted, assumptions labelled fact/assumption/judgement, a highest-risk area that names the real judgement call rather than the easy part, and an explicit remaining gate. The policy-guard: FAILURE from the superseded run was disclosed unprompted and correctly rather than summarized away. Nothing in the body proved false against measurement.

Recorded, not blocking

• REQ-VISUALIZATION-007 stays PARTIAL, and M3 does not close on it. Promotion needs REQ-VISUALIZATION-008: local-market guide misstates expectation causality and bootstrap boundary #446 and REQ-VISUALIZATION-008: settlement guide conflates transfer conservation with later physical source/sink flows #447 merged and every acceptance item re-checked. Issue REQ-VISUALIZATION-007: README still carries stale M2/M3 semantics after PR #381 #445 is fully satisfied by this change and closes.
• The AUTHOR's observation that mergeability check never refuses a behind-base branch: the STALE_BASE arm is unreachable #482 is a control-plane defect in scripts/mergeability.py without the policy label is accurate and it was right not to act on it. It is relevant to this review: it is exactly why I measured the base relationship with git merge-base instead of trusting the green mergeability status.
• The selection I was handed does not contradict section 1: REQ-VISUALIZATION-007: correct six stale M2/M3/M4-M5/M11 claims in the README #484 is open, non-draft, not status:needs-decision, not machine-generated, and carried no prior verdict at this head.

Merging through the protected path with --squash --delete-branch.