--- description: The standing execution loop for this repo — plan, implement, adversarial review, resolve, verify, record. Use for every substantive change. argument-hint: --- **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) 1. Read `AGENTS.md` in full if you have not this session. Read **§12 Standing 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 (D1–D20) 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 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. 5. 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): ` 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.md` entry (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 rolled `2026-02-30` > forward to `2026-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 ```bash 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 - `curl` the built HTML and confirm real content, not a shell - **Lighthouse mobile ≥ 95 on all four categories** — `npm run lighthouse`, after `npm run build`, on the pages the change touches or on all of them. Available again since 2026-08-31 (`AGENTS.md` §7). It exits non-zero on a breach, so **read the exit status** rather than the table. Do not substitute a manual DevTools run and describe it as the same check. Note when reporting that the accessibility figure is measured with `prefers-reduced-motion` forced - 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: ```bash grep -rE 'animation:[^;}]*(scroll\(\)|view\(\))' dist --include='*.css' ``` A hit means an `animation` shorthand was written beside `animation-timeline` and Lightning CSS folded them into an invalid declaration, which the parser then discards. The effect works in `npm run dev` and 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.