Pin the disproof's record, the round cap per chunk in Vocabulary, and drop larv-review's duplicate severity rules

This commit is contained in:
2026-09-28 19:34:56 +02:00
parent 2215d9c193
commit fc5f2f88f5
3 changed files with 11 additions and 12 deletions
+1 -1
View File
@@ -14,7 +14,7 @@ Shorter is better, none is best — chat output, commit messages, comments, docs
- **premises** — the goals and audience under `## Goals` and `## Audience` in the project's `README.md`.
- **release** — a semver version the human cuts.
- **reviewer** — a reporter of findings: an agent under `~/.claude/agents/`, `/security-review` or a forge's auto-reviewer.
- **round cap** — the rounds one loop of a looping reviewer may take.
- **round cap** — the runs one pass may take per chunk, re-entries included.
- **session** — a Claude Code session: one id, what `claude --resume` continues.
- **trigger** — a sign that a change carries an architectural decision the decision log does not hold, so the architecture pass is warranted; `larv-review` §2 lists them.
- **worker** — the headless claude that runs the task in a cycle, in the chunk's session.
+6 -6
View File
@@ -6,15 +6,15 @@ A reviewer reads and reports; it edits nothing. Read `docs/decisions.md` first:
## Severity
- 🔴 **must fix** — a goal, a principle or correctness broken. Fixed, or shown factually wrong; never declined.
- 🔴 **must fix** — a goal, a principle or correctness broken. Fixed, or shown factually wrong, with what disproved it recorded in `docs/decisions.md`; never declined.
- 🟡 **should fix** — worse than it needs to be. Fixed, or declined.
- 🟢 **nit** — fixed if cheap; never holds a pass.
- 🟢 **nit** — never holds a pass.
- ❓ **question** for the author: a finding you could not confirm goes here, not above.
- 🔀 **escalation** — names the reviewer whose concern it is (`product-owner-reviewer`, `systems-architect` or `/security-review`) and why, in one line. The orchestrator runs it.
Other reviewers map onto this scale:
- `/security-review`: HIGH is 🔴, MEDIUM 🟡, LOW 🟢. A HIGH shown not real is recorded with what disproved it.
- `/security-review`: HIGH is 🔴, MEDIUM 🟡, LOW 🟢.
- A forge's auto-reviewer: what it marks blocking is 🔴.
## Verdict
@@ -29,9 +29,9 @@ A review's first line, derived from the findings:
- Surface everything in round 1.
- From round 2 the prompt carries the previous round's findings verbatim and what changed since. Verify each earlier 🔴 and 🟡 is resolved — re-run the scenario, never trust the claim — then review what changed. A fix raises a new finding only where the fix itself introduced a real problem.
- A pass is done on no 🔴 and no 🟡. The 🟢 and ❓ left are addressed in that round — fixed, answered, declined or filed in `todo.md` — and take no further round, unless a fix changes behaviour.
- Round cap: a pass runs at most three times per chunk, re-entries included. A fourth run lists what is open and asks the human.
- A pass is done on no 🔴 and no 🟡. The 🟢 and ❓ left are addressed in that round — fixed, answered, declined or filed in `todo.md` — and take no further round, unless a fix changes behaviour: that takes one.
- Round cap: a pass runs at most three times per chunk, re-entries included. Instead of a fourth, list what is open and ask the human.
## Declining
A 🟡 or below may be declined where the reason is sound, consistent with the goals, and confidence is very high. The decline, its reason and the goal it rests on go to `docs/decisions.md`, with the human's decisions and answers to ❓; an unrecorded one is asked again next review. A reason no goal speaks to is a gap in the goals, taken per `~/.claude/CLAUDE.md` → "Ask, don't guess" — or fix the finding. Never a silent drop, and never a decline argued from convenience or the size of the fix.
A 🟡 or below may be declined where the reason is sound, consistent with the goals, and confidence is very high. The decline, its reason and the goal it rests on go to `docs/decisions.md`; an unrecorded one is raised again next review. A reason no goal speaks to is a gap in the goals: fix the finding, or ask per `~/.claude/CLAUDE.md` → "Ask, don't guess", which also says where an answer to a ❓ lands. Never a silent drop, and never a decline argued from convenience or the size of the fix.
+4 -5
View File
@@ -50,7 +50,7 @@ No signal fires → skip it, say so in the summary, don't ask. A signal fires wi
Launch **systems-architect**: review the system as a whole entered through this change; the decision log carries previously accepted decisions to honor, the README the goals and Stage 0 artifacts.
- **Stage 0 questions returned** (goals/audience/horizon unrecorded): relay them to the user, record the answers where the agent expects them (README), re-run once. No user → skip the pass, carry the questions into the summary.
- **BLOCK** → the restructure precedes everything below. Confirm with the user first when it materially reshapes their PR; apply it; re-run systems-architect once, scoped to verifying its own findings. Still BLOCK → stop and ask the human.
- **BLOCK** → the restructure precedes everything below. Confirm with the user first when it materially reshapes their PR; apply it; re-run systems-architect scoped to verifying its own findings, under the round cap.
- **APPROVE** / **APPROVE WITH NITS** → proceed; nits per the findings document's rounds.
### Comprehension floor (with every architecture pass)
@@ -61,8 +61,7 @@ Invoke the `comprehension-panel` skill's scoring run (`~/.claude/skills/comprehe
Run the built-in **`/security-review`** skill over the branch diff. It is the pass of record here: its value is a tuned exclusion list and a ≥0.8 confidence floor, which a hand-written reviewer would reproduce worse. A fix made in any pass after it re-enters it only where it opens a new untrusted-input boundary or touches authn/authz, secrets or crypto.
- **HIGH** → verify it is real, then fix it before this chunk ships: inside this chunk's blast radius it is fixed here, outside it on its own branch and PR with this chunk waiting behind it. Say which. A verified HIGH is never filed for later and never put to the human as a question. Verification showing it is not real is no decline but a disproof — record what disproved it, since a finding that is factually wrong needs no goal to reject.
- **MEDIUM** → fix in this chunk, or decline.
- **HIGH** → verify it is real, then fix it before this chunk ships: inside this chunk's blast radius it is fixed here, outside it on its own branch and PR with this chunk waiting behind it. Say which. A verified HIGH is never filed for later and never put to the human as a question.
- A **MEDIUM or LOW** outside this chunk's scope → a `todo.md` item per `~/.claude/CLAUDE.md` → "Todo items"; filing it is not fixing it.
**Escalate to a full scan** — the `claude-security` plugin (`/claude-security` → "Scan changes"), first-party and agent-verified — when the change touches authn/authz, secrets or crypto, a new untrusted-input boundary, or a new external surface. Same shape of judgment as §2's trigger: a signal with no record behind it, and a user reachable, is an ask. The plugin is not enabled by default; unavailable → say so in the summary rather than substituting a hand-rolled pass.
@@ -74,7 +73,7 @@ Run the built-in **`/security-review`** skill over the branch diff. It is the pa
A fix sent back here opens its loop with a round prompted with the fix's scope and why it changed.
1. Launch **stability-reviewer**, prompted per the findings document's rounds.
2. Fix every 🔴 **and every 🟡** along its Fix guidance (delete > simplify > modify > add). Keep test changes and implementation changes separately reviewable. §8's gate verifies what the final round's nits changed.
2. Fix every 🔴 **and every 🟡**, or decline it, along its Fix guidance (delete > simplify > modify > add). Keep test changes and implementation changes separately reviewable.
3. Commit and push each round's fixes so CI feedback accumulates while the loop runs.
4. Carry any 🔀 product-owner escalation into §6.
@@ -117,7 +116,7 @@ Marking the PR ready is what summons CodeRabbit and its kind, so this follows §
- Detect one from the repo — a reviewer's config file (`.coderabbit.yaml` and the like), or its comments on the repo's earlier PRs. None found → skip, say so.
- Wait up to **10 minutes** for its first review, checking about once a minute. Nothing by then → note it in the summary and carry on; a reviewer that arrives later is read the next time anyone visits the PR, never waited on twice.
- Its findings follow the findings document like every reviewer above — no more authority, and no less; anything it marks blocking is a 🔴. Fix → commit → push; a fix that changes behavior re-enters §5, then §8. Then wait up to **5 minutes** for its re-review of the new commit.
- Its findings follow the findings document like every reviewer above — no more authority, and no less. Fix → commit → push; a fix that changes behavior re-enters §5, then §8. Then wait up to **5 minutes** for its re-review of the new commit.
## 10. Goal alignment, then merge