docs: correct four factual defects in the README, and fix the hero SVG

[MongLong0214]

What this PR became, and why it is smaller than it started

It began as the A–Z review's README restructure. The restructure cannot be done in this PR, and the reason is a contract, not a preference.

test/readme-order.test.ts:141,174 binds section order across all four language files:

const FILES = ['README.md', 'README.ko.md', 'README.ja.md', 'README.zh-CN.md']
it('all four files have consistent relative order', ...)

T-1016 requires the same demo asset in all four; T-1015 requires the exposure table, the delivery/capture naming for every host class, and the clone-carried vs notes-backed distinction in every file. Restructuring English alone failed 18 tests across 5 files. Restructuring all four would take over the translated READMEs, which belong to #590.

So the restructure is inherently a coordinated four-file change and belongs with #590, not ahead of it. What survives here is every factual correction the review found — those needed no structural change, and they are the part that was actually wrong.

The four corrections

1 — the headline denominators contradicted the generated block. The prose claimed 16/580 and 109/579; the checker-owned block in the same file reports 585 and 584 runs per arm, with 110 in the off arm. Two different denominators for one study, in one file.

prose (unchecked)      2.8% (16/580)  ·  18.8% (109/579)
generated (checked)    585 and 584 runs per arm; commitlore-off 110
corrected              2.7% (16/585)  ·  18.8% (110/584)

The prose drifted because nothing owned it — which is exactly the gap #590 is widening.

2 — the Capture column's "Yes" read as deterministic autocapture. What is installed is the prepare → verify → stage path. That every eligible commit reaches a terminal assessment on its own is a stronger property, certified on no host. The caption now separates available from guaranteed.

3 — the Provenance: vocabulary was missing two of its five values. SPEC §3 carries authored | drafted | inherited | reconstructed | unknown; the table listed three. drafted is what unattended capture writes, so the omitted value was the one a reader is likeliest to meet.

4 — "Every route uses the same trust grading" stated an intention as an observation. A record has been observed grading directive through the CLI and claim through MCP with more than one runtime installed (#631, #635). Users meet the result, not the design.

The hero SVG

grok's adversarial review found six defects in a version I had already accepted. Two I had missed: the agent appeared nowhere in the image, so "delivered to the next agent" was asserted rather than shown; and 19px text rendered at 5.9px at mobile width. Now: 22px floor (24px for required elements), aria-labelledby + aria-describedby, no strikethrough, and the superseded record is a genuinely different record rather than the same one crossed out.

Verification

bash spec/verify.sh                    OK: 32 fixtures + README example sync + vocab table
node scripts/check-readme-numbers.mjs  block matches bench/report.ts
vitest readme + positioning + numbers + order + compatibility + demo   107 passed

Filed separately

• spec: bind signature mode to the signer allowlist in the normative text #645 — SPEC §7 still describes signature mode as G status only, while Bind a directive to an authorised signer, not to a signature #642 also requires the %GF fingerprint in commitlore.trustedSigner. Every other surface picked that up; the normative text did not.
• pre-push notes mirror reports ETIMEDOUT as a failure line when the push itself succeeded #632 — notes mirror (origin) failed: spawnSync git ETIMEDOUT reproduced on every push here.

[github-actions]

CommitLore — record lint

Trailers: clean — 2 commits in origin/main..5993aa2bb990d05cbb9f8013e3af031504a8db86
Active constraints: not read — commitlore: git log --follow accepts exactly one pathspec, so renames are not followed for 2 paths; query one path at a time to follow its rename chain (2 changed paths)

_{Trailer violations fail this check. Active constraints are informational — they are what the repository already decided, not a verdict on this PR.}

[MongLong0214]

grok adversarial review → six fixes (ffc8f1e)

The SVG was built by grok against the handoff spec, then reviewed adversarially by a fresh grok pass against the same acceptance criteria. It failed two of them. Both are invisible at desktop width, which is why the review was worth running.

#	Severity	Defect	Fix
1	High	The recipient was missing (AC-01). File, ACTIVE, SUPERSEDED and "not delivered" were all present, but nothing named the agent, so "it gives an agent the current decisions" was not readable from the image. <title> also said CommitLore "attaches" decisions to a path — the wrong mechanism.	delivered to the next agent; title and desc rewritten to delivery-to-an-agent
2	High	Unreadable at the specified size (AC-03). 19px labels render at ~5.9 CSS px at 375px, and GitHub's mobile column is nearer 330px. Secondary ink was 4.7:1.	floor raised to 22px, required elements 24px, secondary ink darkened, viewBox 320→340 to buy room
3	Medium	Same idea twice. Active Ruled-out — Reuse checkout pricing for admin quotes next to superseded Reuse calculatePrice for admin quotes read as one decision printed twice, i.e. "it still shows the old rule".	superseded is now a distinct earlier record: Earlier Limit — calculatePrice also served admin quotes
4	Medium	Strikethrough read as prohibition. A line through the superseded action, beside an active Ruled-out of the same action, claims closer to blocking than the product does.	strikethrough removed; superseded carried by position below the divider, a quieter label and lower contrast — more than colour alone
5	Low	Strikethrough overshot its text by ~80px	moot with 4
6	Low	aria-labelledby="title desc" concatenated both into one accessible name	aria-labelledby="title" + aria-describedby="desc"

Passing unchanged: one art direction, no terminal chrome, no gradient, 5 colours, no marketing headline inside the drawing, fully static, no external font/image/JS/foreignObject, no forbidden wording, 35 visible words, every run inside the 1200 viewBox with margin.

Defects 3 and 4 are the ones worth noting beyond this PR: both were the drawing claiming more than the product contract allows, which is the same class of error P0-README-02 fixed in the prose.

[MongLong0214]

Conformance restored, and the vocabulary drift closed with it (f70127a)

The first push failed git-matrix on macOS and ubuntu. That was the contract working, not a flake.

spec/verify.sh reads the README's complete-record code block as a conformance fixture and compares the vocabulary table against SPEC §3. Moving both to docs/protocol.md — which the review recommended — silently deletes those two checks rather than relocating them. Both are back, placed at the end so the record grammar no longer competes with the product entry.

Restoring the table also closed P0-README-04. It listed Provenance: authored | inherited <sha> | reconstructed while SPEC §3 line 124 carries drafted and unknown as well — and unattended capture writes drafted, so the missing value was the one a reader is most likely to meet.

Scope confirmed with the CommitLore CTO

The three translated READMEs are #590's, not this PR's. Hand-syncing them would route around the very drift #590 exists to fix. The boundary agreed:

#590 generates into all four	This PR owns
Provenance vocabulary values	table headers and surrounding prose
bench figures, denominators, rates	the sentences that frame them
Node floor, version	section structure and placement
capture certification state values	the wording that explains the state

The vocabulary correction is already in the #590 branch for all four languages. Merge order this PR → #590 rebase closes it without duplicate work, at the cost of a short mismatch on main.

Neither the generated block nor the vocabulary table is leaving the README. #590's goal is widening the set of facts the checker owns, not relocating them — the block stays where this PR placed it and #590 fills it, reusing the existing marker names and format. No follow-up PR to strip markers is needed.

Verification

bash spec/verify.sh                    OK: 32 fixtures + README example sync + vocab table
node scripts/check-readme-numbers.mjs  block matches bench/report.ts (54 lines, 4573 bytes)
in-page anchors                        6/6 resolve

606 → 352 lines.

Filed separately

commitlore: notes mirror (origin) failed: spawnSync git ETIMEDOUT; branch push continues reproduced on both pushes here and has been folded into #632 with the reproduction. Fail-open is by design; the message not saying whether a note is pending, whether the next push retries, or what to run is the open product decision.

[MongLong0214]

CI will not go green — two failures on check (24) and check (22.23.2)

Flagging now rather than letting the background watch wait for a green that is not coming.

1. Compatibility pointer count

× T-1122 the compatibility statement exists and is the authoritative one
  > README.md points at it exactly once
  → README.md must carry exactly one pointer: expected 6 to be 2

The restructure introduced more references to the compatibility document than the test allows. That test exists to keep one authoritative pointer rather than several drifting ones, so the fix is to reduce the references, not to relax the count — same reasoning as the conformance fixture you already restored.

2. Four commits carry a record with no Record-Id

× dogfooding: this repository obeys its own protocol > every in-scope record carries a Record-Id
  a0a7b83 docs: make the README a product entry, and say what capture does not do yet
  c5437ba docs: fix six defects grok's own review found in the hero SVG
  6fe4215 docs: keep the conformance fixture in the README, and complete the vocabulary
  ff33333 docs(readme): 등급 일관성 문장을 실측에 맞춰 정정

Each carries CommitLore trailers but no Record-Id:, and the protocol requires one per record.

This is the amend trap in #638. Adding the trailer means amending, and the hook then refuses the amend as a duplicate Record-Id against the commit it replaces — the escape today is --no-verify, which is exactly what #638 says teaches people to bypass the gate. If you hit that, use --no-verify for the amend and say so in the PR; the gate still validates the resulting message on the next real commit. I would rather record that we hit it than have it quietly shape how the history looks.

Reproduce both locally with:

npx vitest run test/readme.test.ts test/dogfood.test.ts

[MongLong0214]

New failure after the scope reduction — the record you added collides with an unrelated proposal

× guard against this repository > does not flag: document the exit codes in the README
  → expected [ '0.625 README를 제품 진입점으로 전면 재구성' ] to deeply equal []

Guard now treats "document the exit codes in the README" as an attempt to revive a ruled-out approach, at 0.625.

Why

The alternative you recorded is broad enough to swallow any README proposal:

Ruled-out: README를 제품 진입점으로 전면 재구성 | T-1015/T-1016이 4개 파일 일관성을 강제하는데 번역은 #590 소유라 이 PR에서 손댈 수 없다

The reason is precise — four-file consistency, translations owned by #590. The alternative is not: as written it reads as "restructuring the README", so anything about the README scores against it.

That test is a precision floor for guard. Guard is an experimental advisory with measured precision well below a gate (ADR-0020), and this case exists so it does not drift further. Relaxing it to make the PR pass would spend the floor to keep a record's wording.

The fix belongs in the record, not the test

Name what was actually rejected. It was not "restructuring the README" in general — it was restructuring only the English file while section order is a four-file contract. Something closer to:

Ruled-out: restructuring README.md alone, leaving the three translations on the old section order | T-1015 binds relative section order across all four files, so an English-only restructure cannot pass, and the translations belong to #590

That records the same decision, is more useful to the next person — it says what would be acceptable, a four-file change — and stops scoring against proposals that merely mention the README.

Worth noting the record did its job here in an unexpected way: it is the first time in this session that a recorded decision has actively pushed back on a later proposal. The pushback was wrong, and the reason it was wrong is that the alternative was written as a category rather than as the thing that was tried.

Reproduce with npx vitest run test/guard.test.ts.