feat: D20 moves the claims pass to cutover; rule Q56 unscoped; close Q55; freeze check:claims

Four rulings from Pouya, 2026-08-30, and their sweep.

D20 — the review protocol. Per build step the review is `adversarial-reviewer`
alone. `claims-auditor` no longer runs per step; it runs ONCE, at cutover, over
the whole finished site, as a blocking item near the top of docs/06's checklist.
`check:claims` is unchanged and still runs on every build and both deploy paths.
The reasoning is recorded in full in AGENTS.md D20, as a calibration and not an
erosion: nothing has shipped, so every claims finding so far has been about a
page no visitor can reach, and one pass over twenty finished pages catches more
than nine passes over drafts because it sees the site as a reader does. The
/med-arb/ ADRIC gloss is the proof — no individual claim was false, the defect
was adjacency, and adjacency does not exist until the pages sit next to each
other. The code reviewer stays per step because what it catches compounds.
What this costs is recorded honestly beside it, not summarised away.

D17 and D19 amended to match. D19's two-round cap governs the per-step code
review only; the single cutover claims pass runs until its findings are
resolved, because there is no second pass behind it.

Q56 — mediation is NOT scoped commercial. Thirteen shipped strings corrected
across five files: page titles, meta descriptions, hero ledes, section ledes,
the `Service` node's name and description, and `ProfessionalService`'s. §4's
mediation row stays unscoped, and the reason now sits beside both rows so the
asymmetry reads as designed: arbitration is scoped commercial because of a
LEGAL GATE (Q39 — family arbitration in Ontario requires prescribed training);
mediation has no such gate. `adversarial-reviewer` then found three surfaces
the sweep had missed, the worst on /practice/ — "These describe the process the
parties are choosing between, in commercial matters" scoped mediation with the
two words never appearing in the same element, so no proximity grep reached it.

Q55 — CLOSED WITHOUT BEING RESOLVED, and the difference is the ruling. The
Q.Arb stamp is split: `[verified]` on the status, `[Pouya's stated basis]` on
the date. The 2026-08-26 record is marked UNRECONCILED, permanently and on
purpose. The date is not published and nothing depends on it.

check:claims — FROZEN. Round 2 found five defects in round 1's own fixes to
that script, two of which made it worse than before the pattern existed. A
pattern is added only after a real breach reaches dist/, never speculatively,
and each addition ships with a probe plus a negative fixture. No refactors, no
coverage improvements. It is a tripwire, not a program.

Two conventions into CLAUDE.md: sweep the VOCABULARY, not only the subject
(`git grep 'Q.Arb'` is line-anchored and could not find ten lines entirely
about Q.Arb that never name it); and agent definitions load at session start,
so an edit to .claude/agents/*.md does not reach the session that made it.

Verified: check 0 errors, lint 0, build 0 (12 pages), check:claims 0.
Lighthouse not run — tool unavailable until build step 7.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Md3GndFqWPzK78xAoebsg5
This commit is contained in:
Pouya Lajevardi
2026-08-31 07:33:06 -04:00
co-authored by Claude Opus 5
parent 610edc24fd
commit 2ea4c0f8ac
14 changed files with 520 additions and 125 deletions
+28 -13
View File
@@ -19,7 +19,7 @@ does not apply, say which and why before moving on.
Reminders** and surface anything live to Pouya before you start.
2. Read the specs in `docs/` that bear on this task.
3. Restate the task in your own words, and name:
- which locked decisions (D1D19) it touches
- which locked decisions (D1D20) it touches
- which specs govern it
- which facts it needs from the §4 Verified register
4. **Stop and ask if you find a conflict** — between the task and a locked
@@ -45,24 +45,36 @@ number.
## Phase 3 — Adversarial review (this is not optional)
Invoke **both** review agents on the change, in parallel:
Invoke **one** review agent on the change:
- `adversarial-reviewer` — correctness, accessibility, crawlability,
performance, security, simplicity
- `claims-auditor` — every factual assertion traced to `AGENTS.md` §4
**Give them the diff and the specs. Do not give them your reasoning for why the
work is correct.** Your rationale anchors the reviewer and produces agreement
instead of review. They form their own view from the artefact; that independence
is the whole point of the phase.
**`claims-auditor` does NOT run here — D20, Pouya, 2026-08-30.** It runs **once,
at cutover**, over the whole finished site, as a blocking item on `docs/06`'s
checklist. Do not invoke it per step, and do not reinstate it because a change
set looks claim-heavy: that judgement was already made against the measured cost,
which `AGENTS.md` D20 records in full. If a claim genuinely worries you, the
answer is a `TODO(pouya)` and a §9 question — the thing that blocks — not an
unscheduled audit.
Two things carry the claims risk between now and cutover, and neither is
optional: **`npm run check:claims` in Phase 5**, and **Pouya reading the copy as
it is built**.
**Give it the diff and the specs. Do not give it your reasoning for why the work
is correct.** Your rationale anchors the reviewer and produces agreement instead
of review. It forms its own view from the artefact; that independence is the
whole point of the phase.
### Scope — D19
Review is bounded. **In scope:** `dist/`, `src/`, the specs that direct copy
(`docs/01`, `03`, `04`, `07`), and `AGENTS.md` §3, §4, §7, §9, §12. **Out of
scope:** the Change Log, the agents' own briefs, `AGENTS.md` prose outside those
sections, and the historical accuracy of code comments. Both briefs carry the
same boundary — do not widen it in the prompt.
sections, and the historical accuracy of code comments. Both agent briefs carry
the same boundary — do not widen it in the prompt. It binds the cutover claims
pass too, which is the one place `claims-auditor` still runs.
### The stop signal
@@ -72,8 +84,9 @@ itself, and noticing it is part of the job — not a licence to skip the phase.
The shape to watch for, from the session that produced D19: a Change Log sweep
that could not reproduce *because writing it changed the file it counted*.
If the change touches no user-facing copy, `claims-auditor` may be skipped — say
so explicitly.
**The claims pass is deferred, not deleted.** Say which review ran in your
report. "Reviewed" without naming the agent reads as both, and under D20 it is
one.
## Phase 4 — Resolve
@@ -113,8 +126,10 @@ npm run check:claims
```
`check:claims` greps the built pages for the §4 Forbidden set — Pouya's ruling,
2026-08-29. **Every pattern it catches is a finding neither review agent has to
spend a pass on**, which is D19 served directly. It self-tests its own patterns
2026-08-29. **Under D20 it is the only per-step claims control there is**, so
never skip it and never let a build ship on a stale `dist/`. It is a tripwire,
not a program: it catches the §4 breaches that are greppable and it makes no
claim about the ones that are not. It self-tests its own patterns
before it sweeps and refuses to run against an empty or stale `dist/`, so a pass
is a pass on the bytes that would ship. **A match is not yet a finding** — read
the context it prints. If a pattern is genuinely wrong, change it deliberately