feat: D19 bounds the review loop; apply nine rulings; close Q46(a) and Q48–Q53
D19 into §3 and swept to all six destinations Pouya named: both agent briefs
(scope + severity filter), /build Phases 2–4 (non-gating questions, scope, stop
signal, two-round cap), /wrap, and CLAUDE.md (comments record decisions, not
history). Sweep verified by command, not recalled.
Rulings applied:
Q46(a) PUBLISHABLE — three §4 Offerings rows flipped; gate 1 records
[Pouya's stated basis], never [verified]. Step 5 unblocked.
Q48 closed, not site-relevant.
Q49 one §4 row, "Mediator"; read as declining Q49(b), so worksFor stays out.
Q50 DEVIATES — ships as name + slogan, not the concatenation. Flagged.
Q51 OBA sections stay; the regulator/voluntary distinction recorded.
Q52 docs/reference/deploy-credential-verification.md — 18 read-only AWS
calls, re-run rather than transcribed, access key ID redacted.
Q53 memberOf emitted on /about/'s Person node.
Two review rounds. The headline finding was this session's own: the Q53 sweep
was asserted and never run, leaving six in-scope records saying memberOf was
withheld — including §12 R10, which is read aloud every session. Round 2 then
found that round 1's simplification had put memberOf on / as well; the per-page
opt-in is restored, because Pouya's ruling turns on /about/'s visible HTML.
Also fixed: MEMBERSHIP_ORGS had orphaned BOUTIQUE's D16 JSDoc; /'s title now
derives from the constants; §7's deploy row stated and retracted three facts.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0148NztQskLKKApP5SzAA78e
This commit is contained in:
co-authored by
Claude Opus 5
parent
77a7b410b2
commit
fd5f610982
@@ -27,6 +27,35 @@ A diff or a set of files, and the specs in `docs/`. You are deliberately **not**
|
||||
given the implementer's account of why the work is correct — form your own view
|
||||
from the artefact.
|
||||
|
||||
## Scope — D19, and it is a hard boundary
|
||||
|
||||
**In scope:**
|
||||
|
||||
- `dist/` and `src/` — what a visitor actually receives
|
||||
- the specs that direct copy: `docs/01-architecture.md`,
|
||||
`docs/03-content-spec.md`, `docs/04-seo-spec.md`, `docs/07-fees.md`
|
||||
- `AGENTS.md` **§3, §4, §7, §9, §12** — the operative sections
|
||||
|
||||
**Out of scope:**
|
||||
|
||||
- the `AGENTS.md` **Change Log**
|
||||
- the agent briefs in `.claude/agents/`, including this one
|
||||
- `AGENTS.md` prose outside the five sections named above
|
||||
- the **historical accuracy of code comments** — whether a comment's account of
|
||||
how the code got here is still true
|
||||
|
||||
A false statement in a Change Log entry gets corrected when someone notices it.
|
||||
It does not get a review pass, because **no visitor reads it.** Pouya's ruling,
|
||||
2026-08-28 (D19), on the session where most of a second review round's findings
|
||||
were defects in the first round's own fixes: *"they are defects in the record
|
||||
about the record, and that is infinite regress."*
|
||||
|
||||
**What this does not narrow.** A code comment that states a **live constraint**
|
||||
wrongly is in scope — it will mislead the next implementer into shipping the
|
||||
defect. What is out of scope is the comment's account of its own revision
|
||||
history. And a comment that is longer than the code it explains is now itself a
|
||||
finding under `CLAUDE.md`'s D19 convention: report it as **simplicity**, lens 6.
|
||||
|
||||
## Lenses — work all of them
|
||||
|
||||
**1. Correctness.** Does it do what `docs/01-architecture.md` and
|
||||
@@ -84,5 +113,20 @@ For each finding:
|
||||
rather than dressing up a preference as a bug.
|
||||
- **The fix**, specifically
|
||||
|
||||
### Severity filter — D19
|
||||
|
||||
**Report blocking and should-fix. Raise a `consider` only if acting on it would
|
||||
change what ships.**
|
||||
|
||||
The standing bias above says an approving review that misses a real defect is a
|
||||
failure. This is its twin, and Pouya added it 2026-08-28: **a review that reports
|
||||
twenty things in order to produce twenty small edits has spent more than it
|
||||
saved.** Both failures are real and they pull in opposite directions. The
|
||||
resolution is *not* to soften a genuine defect — it is to stop promoting
|
||||
preferences into findings.
|
||||
|
||||
If you are uncertain whether something is a defect, the standing bias still
|
||||
applies: report it, at the severity your confidence supports.
|
||||
|
||||
If you genuinely find nothing at a given severity, say which lenses you applied
|
||||
and what you checked, so the gap is auditable. **"Looks good" is not a review.**
|
||||
|
||||
@@ -13,6 +13,38 @@ The site this replaces contained a fictitious founder, invented matter values
|
||||
and a testimonial attributed to a person who does not exist. Your existence is
|
||||
the control that stops that recurring.
|
||||
|
||||
## Scope — D19, and it is a hard boundary
|
||||
|
||||
**In scope:**
|
||||
|
||||
- `dist/` and `src/` — what a visitor actually receives
|
||||
- the specs that direct copy: `docs/01-architecture.md`,
|
||||
`docs/03-content-spec.md`, `docs/04-seo-spec.md`, `docs/07-fees.md`
|
||||
- `AGENTS.md` **§3, §4, §7, §9, §12** — the operative sections
|
||||
|
||||
**Out of scope:**
|
||||
|
||||
- the `AGENTS.md` **Change Log**
|
||||
- the agent briefs in `.claude/agents/`, including this one
|
||||
- `AGENTS.md` prose outside the five sections named above
|
||||
- the **historical accuracy of code comments** — whether a comment's account of
|
||||
how the code got here is still true
|
||||
|
||||
A false statement in a Change Log entry gets corrected when someone notices it.
|
||||
It does not get a review pass, because **no visitor reads it.** Pouya's ruling,
|
||||
2026-08-28 (D19), on the session where most of a second review round's findings
|
||||
were defects in the first round's own fixes: *"they are defects in the record
|
||||
about the record, and that is infinite regress."*
|
||||
|
||||
**What this does not narrow, and read this carefully.** Your subject is **claims
|
||||
about Pouya, his credentials, his experience and his practice** — and one of
|
||||
those in a code comment is in scope wherever it could reach a page or mislead an
|
||||
implementer into writing one. `src/data/site.ts` and `src/data/schema.ts` carry
|
||||
the register's wording in comments *precisely because the wording is the
|
||||
compliance*; audit those exactly as you would copy. What is out of scope is a
|
||||
comment's account of **how the code got here** — which version said what, which
|
||||
review found it.
|
||||
|
||||
## Method
|
||||
|
||||
1. Read `AGENTS.md` §4 in full — the Verified table, the Forbidden table, and
|
||||
@@ -105,6 +137,17 @@ machine-readable misrepresentation is still a misrepresentation.
|
||||
A table: **claim quoted verbatim · location · verdict (VERIFIED / NOT IN
|
||||
REGISTER / FORBIDDEN) · the register line it matches, or what to do instead.**
|
||||
|
||||
### Severity filter — D19
|
||||
|
||||
Report **FORBIDDEN** and **NOT IN REGISTER** findings in full — those are the
|
||||
job, and none of them is optional. Below that line, raise a wording preference
|
||||
only if acting on it would change what ships. Pouya's ruling, 2026-08-28: *"a
|
||||
review that reports twenty things to make twenty small edits has spent more than
|
||||
it saved."*
|
||||
|
||||
This does not soften the rule above it. **A claim not in the Verified table does
|
||||
not ship**, at any count.
|
||||
|
||||
Then a single line: **PASS** — every assertion traced — or **FAIL**, with the
|
||||
count of untraceable claims.
|
||||
|
||||
|
||||
@@ -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 (D1–D18) it touches
|
||||
- which locked decisions (D1–D19) 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
|
||||
@@ -36,6 +36,13 @@ 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 **both** review agents on the change, in parallel:
|
||||
@@ -49,6 +56,22 @@ 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.
|
||||
|
||||
### 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.
|
||||
|
||||
### 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*.
|
||||
|
||||
If the change touches no user-facing copy, `claims-auditor` may be skipped — say
|
||||
so explicitly.
|
||||
|
||||
@@ -69,6 +92,18 @@ under review pressure is exactly where the second defect lives.
|
||||
> 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
|
||||
|
||||
@@ -30,12 +30,18 @@ reasoning.
|
||||
instances survived all three, one of them inside the definition of the agent
|
||||
whose job is to catch it.
|
||||
|
||||
4. **Check §12 Standing Reminders.** Is anything now due? Should something new
|
||||
4. **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 it does
|
||||
not block a page, a deploy or a claim, it belongs in this entry as a note, not
|
||||
in §9 as a number — and retire the non-gating ones you find while you are in
|
||||
there. Pouya's ruling, 2026-08-28.
|
||||
|
||||
5. **Check §12 Standing Reminders.** Is anything now due? Should something new
|
||||
be added — a decision Pouya parked, or one you made on his behalf that he has
|
||||
not yet ratified?
|
||||
|
||||
5. **Leave the tree clean.** `git status` should show only intended changes. No
|
||||
6. **Leave the tree clean.** `git status` should show only intended changes. No
|
||||
stray build output, no `.env`, no credentials, no `aws-inventory.txt`.
|
||||
|
||||
6. Report: what changed in `AGENTS.md`, what is open, and the single most useful
|
||||
7. Report: what changed in `AGENTS.md`, what is open, and the single most useful
|
||||
next action.
|
||||
|
||||
Reference in New Issue
Block a user