Pouya LajevardiandClaude Opus 5
2ea4c0f8ac
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
8.2 KiB
description, argument-hint
| description | argument-hint |
|---|---|
| The standing execution loop for this repo — plan, implement, adversarial review, resolve, verify, record. Use for every substantive change. | <what to build, e.g. "the /med-arb/ page" or "step 4 of the build order"> |
ultrathink
Task: $ARGUMENTS
Execute the six-phase loop below. Do not skip a phase because the task looks small — the loop is the quality mechanism, not ceremony. If a phase genuinely does not apply, say which and why before moving on.
Phase 1 — Plan (think hard before writing anything)
- Read
AGENTS.mdin full if you have not this session. Read §12 Standing Reminders and surface anything live to Pouya before you start. - Read the specs in
docs/that bear on this task. - Restate the task in your own words, and name:
- which locked decisions (D1–D20) it touches
- which specs govern it
- which facts it needs from the §4 Verified register
- Stop and ask if you find a conflict — between the task and a locked decision, between two specs, or between the task and a fact you do not have. A blocked build is a correct build. Never resolve a conflict by guessing, and never soften a claim to make it defensible.
- State your plan before implementing.
Phase 2 — Implement
Follow CLAUDE.md conventions. Zero JavaScript by default. Tokens only, no raw
hex, no magic numbers. Semantic HTML. Every page gets its metadata.
Where you need a fact you do not have: TODO(pouya): <the exact question> in the
source and a new numbered question in AGENTS.md §9. Do not invent it.
But do not open a numbered question for something that gates nothing — D19.
The Q-series is past 50 and most recent additions gate nothing. If an observation
does not block a page, a deploy or a claim, it is a Change Log note, not a
numbered question — and retire the non-gating ones you find. A TODO(pouya) in
source is not this case: it blocks the page it sits on, so it still gets a
number.
Phase 3 — Adversarial review (this is not optional)
Invoke one review agent on the change:
adversarial-reviewer— correctness, accessibility, crawlability, performance, security, simplicity
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 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
If a round's findings are predominantly about the record rather than the output, stop the round and say so. That is the symptom of the loop feeding on 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.
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
For every finding: fix it, or decline it with a stated reason. Silence is not a response. A declined finding is recorded in the Change Log with the reasoning, so a later reader can see the judgement was made rather than missed.
If you fix anything material, re-run Phase 3 on the fix. A patch written under review pressure is exactly where the second defect lives.
This is not ceremony, and here is the measurement. On the Astro 5 → 7 upgrade (
AGENTS.mdentry (t), 2026-08-26) the second review pass returned six findings. Four of the six were defects in the first round's own fixes — including a date validator whose replacement silently rolled2026-02-30forward to2026-03-02, and a title rule whose fix rejected all five planned launch articles. None of the four existed before the review started. Skip the re-review and you ship the repair, not the bug.
Two rounds is the cap — D19
Round 1 reviews the change. Round 2 reviews the material fixes. There is no round 3: fix what round 2 finds, and ship.
The measurement above is why round 2 exists. The measurement below is why round 3 does not. On 2026-08-28 two rounds produced 48 findings, and most of round two's were defects in round one's own fixes — so each further round both finds and manufactures defects, and past two the manufacture rate exceeds the value of the marginal finding. Pouya's ruling. State this reasoning when you stop at two, so a later reader does not read the cap as laxness.
Phase 5 — Verify — run it, do not assert it
npm run check
npm run build
npm run check:claims
check:claims greps the built pages for the §4 Forbidden set — Pouya's ruling,
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
with a Change Log entry; do not delete one to make a build pass.
Then, as applicable to what changed:
-
Serve
dist/and confirm the page renders its full content with JavaScript disabled — the failure this whole project exists to fix -
curlthe built HTML and confirm real content, not a shell -
Lighthouse mobile ≥ 95 on all four categories— UNAVAILABLE.@lhci/cliwas removed on 2026-08-26 and is not re-added until build step 7 (AGENTS.mdR11, §7). Report it as not run, tool unavailable. Do not substitute a manual DevTools run and describe it as the same check -
Every internal link resolves
-
Metadata present: unique title, description, canonical, OG, JSON-LD
-
No scroll-driven animation was eaten by the minifier. This must return nothing:
grep -rE 'animation:[^;}]*(scroll\(\)|view\(\))' dist --include='*.css'A hit means an
animationshorthand was written besideanimation-timelineand Lightning CSS folded them into an invalid declaration, which the parser then discards. The effect works innpm run devand is dead in the build.
Never report a check as passing that you did not run. "Should pass" is not a result. If you could not run something, say which and why.
Phase 6 — Record
Append a AGENTS.md Change Log entry, newest first: what changed, old → new,
why, and any decision or plan — including declined findings and anything
deferred. Update Current Truth in place where the change made a section stale.
Re-stamp facts you re-checked with today's date.
If the entry claims a change was applied across files, cite the command and paste its output. Write that claim only after reading the output. Recall is not evidence — three entries on this project asserted a completed sweep and instances survived all three.
Then report to Pouya: what shipped, what the review found, what you declined and why, and what remains open.