Pouya LajevardiandClaude Opus 5
210bc25a26
Steps 7a through 10 as one authorised run. Nothing deployed (D11).
7a Lighthouse returns as `lighthouse@13.4.1` + `chrome-launcher`, NOT
`@lhci/cli`. AGENTS.md §7's advisory attribution was wrong: the carriers
were @lhci/cli's own `tmp` and @puppeteer/browsers' `extract-zip`, not
Lighthouse, which audits clean. A deliberate deviation from R11's literal
trigger, recorded with what it costs. Local gate; CI has no Chrome.
7b OG card generator (satori + sharp) discharges R15 — 20 typed cards plus
per-article cards; the portrait stays on / and /about/ by Q40. Insights
plumbing: ArticleCard, Prose, the index, the article route, articleGraph,
and /'s section 7. Card copy is constrained structurally because text in a
JPEG cannot be grepped by check:claims: every headline IS its page's <h1>,
enforced by `npm run og:proof`.
7c Five drafted launch articles, draft: true / reviewedByPouya: false. An
independent compliance audit returned 76 findings and 57 unsourced
assertions; all blocking and should-fix applied.
8 /contact/, the intake form, and backend/intake/ (undeployed). Plain HTML
POST to a same-origin /api/intake with a 303 redirect, so the form works
with zero JavaScript. docs/05 records three deliberate deviations.
9 /fees/ on Q59's ruling — overtime runs from the session cap, and the
reservation point ships adjacent to the rate. One-page PDF bio discharges
R16; /bio/ is its source, so the circulated artefact stays inside the
review apparatus.
10 /legal/privacy/ and /legal/terms/, written to the backend as built. Three
of the policy's statements are derived and cannot drift.
Also: /about/'s inverse credentials band (approved at step 6); Q59 closed;
R15 and R16 discharged; and a fix to shipped copy — /practice/energy/ asserted
the absence of a regulation the source extract says must not be asserted.
Review: adversarial-reviewer, two rounds (D20/D19). Round 1 returned 16
findings including two blocking — an invisible ghost button on /fees/ at
1.00:1 that Lighthouse scored 100, and a privacy policy that named one data
processor when there are two. All 16 acted on.
Lighthouse, 22 pages, mobile: performance 99-100, accessibility 100,
best practices 100, SEO 100 on every indexable page, CLS 0.000.
AGENTS.md entry (ah) has the detail, including four of my own verification
commands that were wrong and what each of them nearly caused.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Md3GndFqWPzK78xAoebsg5
179 lines
8.4 KiB
Markdown
179 lines
8.4 KiB
Markdown
---
|
||
description: The standing execution loop for this repo — plan, implement, adversarial review, resolve, verify, record. Use for every substantive change.
|
||
argument-hint: <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)
|
||
|
||
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): <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.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.
|