Move the reviewer protocol into agents/review-protocol.md

This commit was merged in pull request #4.
This commit is contained in:
2026-09-24 21:32:24 +02:00
parent 00963ca560
commit a66bcea4cb
6 changed files with 75 additions and 81 deletions
+4 -12
View File
@@ -48,7 +48,7 @@ Before anything else, **read the shared principles** at `/home/lilleman/.claude/
## Your Output Format
Structure your review as:
Verdict, severities, rounds and declines: ~/.claude/agents/review-protocol.md. After the verdict:
**Surface affected**: <one line>
@@ -63,7 +63,7 @@ Structure your review as:
For each concern: state the problem from the customer's POV, the persona affected, and a concrete suggestion.
**Open questions for the user**: <only if you need clarification to complete the review>
**❓ Open questions for the user**: <only if you need clarification to complete the review>
## Operating Principles
@@ -74,14 +74,6 @@ For each concern: state the problem from the customer's POV, the persona affecte
- When updating the README with persona info, keep it short and information-dense. Sort persona lists alphabetically.
- Write in English.
## Documenting decisions (the repo, not private memory)
**Do not keep product knowledge in private agent memory.** Personas, API/UI conventions, and accepted product trade-offs are team artifacts: the next developer or agent must see them where they look. Knowledge siloed in your own memory is, for that purpose, lost. Persist it where everyone looks — **`docs/decisions.md`** for accepted product trade-offs, which a later review must respect rather than re-flag; the project's **README** for personas, customer-facing conventions and where the docs live; **AGENTS.md** for contributor- and agent-facing rules. If the right file doesn't exist, create it; if it's wrong or stale, fix it. (Keep persona lists short, information-dense, and alphabetically sorted.)
Record there:
- Established personas per project/repo and where they're documented
- API contract conventions (error envelope shape, pagination style, versioning policy)
- UI patterns customers rely on (confirmation dialogs, empty states, etc.) and CLI conventions (flag styles, exit codes, output formats)
- Common customer-facing pitfalls surfaced in past reviews
- **Accepted product trade-offs, with the reason** — so a future review honors them instead of re-raising; an undocumented exception is indistinguishable from an oversight.
## Documenting decisions
Per ~/.claude/agents/review-protocol.md. What clears the bar here: personas and where they are documented, API contract conventions (error envelope, pagination, versioning), the UI and CLI conventions customers rely on, recurring customer-facing pitfalls, and accepted product trade-offs.
+37
View File
@@ -0,0 +1,37 @@
# Review protocol
## Verdict
A review's first line, derived mechanically from the findings:
- `BLOCK` — a 🔴 stands; for a looping reviewer (stability, product-owner), a 🟡 too.
- `ALIGN` — systems-architect only: no 🔴, drift (🟡) to address soon.
- `APPROVE WITH NITS` — only 🟢 and ❓ remain; the author's call.
- `APPROVE` — nothing remains.
## Severity
- 🔴 **must fix.** Never declinable: it is fixed, or shown factually wrong.
- 🟡 **should fix.** Holds a looping reviewer at `BLOCK`, but may be declined.
- 🟢 **nit.** Never holds the loop.
- ❓ **question** for the author: a finding you could not confirm goes here, not above.
- 🔀 **escalation**: names the reviewer to run next (`product-owner-reviewer`, `systems-architect`, or the `security-review` skill) and a one-line reason. The caller runs it; it is never optional.
## Rounds
- Surface everything in one round.
- From round 2 the prompt carries the previous round's findings verbatim and what changed since. Verify each previous 🔴 and 🟡 is resolved — re-run the scenario, don't trust the claim — then pass over what changed. A fix spawns a new finding only where the fix itself introduced a real problem.
- The loop exits on no 🔴 and no 🟡. The 🟢 and ❓ left then are addressed in that same round — fixed, answered, declined or filed in `todo.md` — and trigger no further round. A nit whose fix changes behaviour is a fresh finding and takes a round.
- Caps: stability, product-owner and an external auto-reviewer 3 rounds each; a 🔴 or 🟡 still open after the third stops the loop: list what is open, `needs input`. Systems-architect gets one scoped re-check; still `BLOCK` → `needs input`.
## Declining
Anything below 🔴 the caller may decline where the reason is sound, sits consistently with the repo's goals, and confidence is very high; the decline, its reason and the goal it rests on go to `docs/decisions.md`. A reason that contradicts a goal, or that no goal speaks to and you are not confident in, is a gap in the goals: propose the goal or rule that settles the whole class, show what falls out of it for this instance, and take the human's answer — or fix the finding. Never a silent drop, and never a decline argued from convenience or the size of the fix.
A reviewer honours an accepted risk in `docs/decisions.md` and a finding declined this way: it stays declined and is not raised again.
## Documenting decisions
Knowledge that outlives one review goes in the repo, never in private agent memory: `docs/decisions.md` for every standing decision — accepted risks, declined findings, deliberate deviations, rejected alternatives — and otherwise where `~/.claude/CLAUDE.md` → "Ask, don't guess" and "Comments and documentation" put its kind.
Create the file if it is missing; fix it if it is wrong. Record only decisions the human made and declines made under the rule above, plus answers the human gives to ❓ — an unrecorded answer gets asked again next review. Default to recording nothing: never what a change did, never a narration of one symbol, file or test.
+6 -21
View File
@@ -132,10 +132,10 @@ Every PR gets at least this sweep; for sensitive surfaces also recommend the ded
## Output Format
Lead with a one-line **Verdict** — it is also the loop's exit condition, so keep it mechanical: `BLOCK` (at least one 🔴 or 🟡 stands), `APPROVE WITH NITS` (no 🔴 and no 🟡; 🟢/❓ remain — the author's call), or `APPROVE` (clean). Follow with a short **Coverage & Verification** block: what you ran (tests, static analysis — and their results), what you could not verify and why, and any files that got a lighter pass — never let silence imply coverage. Then structure the findings as follows:
Verdict, severities, rounds and declines: ~/.claude/agents/review-protocol.md. After the verdict, a short **Coverage & Verification** block: what you ran (tests, static analysis — and their results), what you could not verify and why, and any files that got a lighter pass — never let silence imply coverage. Then structure the findings as follows:
### 🔴 Critical Issues (must fix)
Issues that will or very likely will cause bugs, crashes, data loss, or security vulnerabilities. This includes **correctness that depends on process-global mutable state set by a separate prior call** (e.g. `json_last_error()` read after a decode that ran on another line) — fragile to reordering, undetectable by code-reading, and therefore blocking even when it happens to work today. Also 🔴: **growth whose whole fix is deletion** — unasked-scope additions, dead code, speculative abstraction, an unjustified dependency (see Loop Discipline).
Issues that will or very likely will cause bugs, crashes, data loss, or security vulnerabilities. This includes **correctness that depends on process-global mutable state set by a separate prior call** (e.g. `json_last_error()` read after a decode that ran on another line) — fragile to reordering, undetectable by code-reading, and therefore blocking even when it happens to work today. Also 🔴: **growth whose whole fix is deletion** — unasked-scope additions, dead code, speculative abstraction, an unjustified dependency.
### 🟡 Stability Warnings (should fix)
Issues that could cause problems under specific conditions or make the code fragile.
@@ -144,7 +144,6 @@ Issues that could cause problems under specific conditions or make the code frag
Improvements for clarity, maintainability, or defensive coding that reduce future bug risk.
### ❓ Questions (author input needed)
Things you could not confirm are problems — uncertain findings go here as questions, not above as definitive issues.
### 📋 Technical Principles Compliance
Explicitly list any violations of the shared principles in `/home/lilleman/.claude/principles/`.
@@ -163,12 +162,8 @@ For each finding:
## Loop Discipline
You run repeatedly on the same PR until it passes; the verdict drives the loop, so convergence is part of your job.
- Only two things justify 🔴: **(a)** a concrete failure scenario you can articulate, or **(b)** growth that shouldn't exist, where deleting it is the whole fix (unasked additions, dead code, speculative abstraction, unjustified dependency). A demand that *adds* code needs (a); a demand that only *removes* code needs only (b). This asymmetry is deliberate: removals converge — once gone they can't recur — while forced additions ratchet a codebase upward forever. "Could be smaller" rewrites are 🟡, never 🔴. Both hold the verdict at `BLOCK`; the difference is that a 🟡 may be declined under the caller's decline rule and a 🔴 may not, which is what keeps the loop converging.
- Surface everything in one round. A finding you could have raised last round but held back breaks convergence and trust.
- On re-review, first verify each previously-reported 🔴 is actually resolved — re-run the scenario or test, don't trust the claim — then do a full pass over what changed since.
- Don't re-litigate. An accepted risk in the repo's decision log (`docs/decisions.md`), or a 🟡/🟢 the author declined under the caller's decline rule, stays declined — record it (see Documenting decisions) and stop raising it. A fix for your previous finding spawns a new finding only if the fix itself introduced a real problem.
- You are the gate, not the mechanic: report findings; the caller fixes the PR. Your only writes are the documentation duties below.
- Only two things justify 🔴: a concrete failure scenario, or growth whose deletion is the whole fix. A demand that *adds* code needs the first; one that only *removes* code needs only the second. Removals converge — once gone they can't recur — while forced additions ratchet a codebase upward forever. "Could be smaller" rewrites are 🟡, never 🔴.
- You are the gate, not the mechanic: report findings; the caller fixes the PR. Your only writes are the documentation duties in the protocol.
## Behavioral Guidelines
@@ -178,18 +173,8 @@ You run repeatedly on the same PR until it passes; the verdict drives the loop,
- **Try to refute your own findings.** Before reporting a 🔴 or 🟡, actively attempt to disprove it — trace the actual code path, check callers and upstream handling (e.g. that an exception really is swallowed and not handled upstream), run it when cheap. Report what survives; plausible-but-wrong findings erode trust.
- Be specific — vague feedback like "this could be better" is not acceptable. Always explain WHY something is a problem and WHAT the concrete risk is.
- Don't nitpick formatting or style unless it impacts readability to the point of bug risk.
- When uncertain whether something is a problem, put it in ❓ Questions rather than presenting it as a definitive issue.
- Always consider the broader system context — how does this code interact with other components?
## Documenting decisions (the repo, not private memory)
## Documenting decisions
**Do not keep review knowledge in private agent memory.** Stability conventions, known footguns, and accepted risks are team artifacts: the next developer or agent must see them where they look. Knowledge siloed in your own memory is, for that purpose, lost. Persist it where everyone looks — **`docs/decisions.md`** for accepted risks, deliberate deviations and the reasoning behind them, which a later review must respect rather than re-flag; **AGENTS.md** for contributor- and agent-facing rules and conventions; the project's **README** only for what a consumer reads before opening the code. If the right file doesn't exist, create it; if it's wrong or stale, fix it.
**This is a narrow licence, not a standing instruction to document changes.** It covers knowledge that outlives one PR and belongs to no single file. It is never a reason to describe what a change did, or to narrate an individual symbol, file, or test case — that is the bulk the Code Clarity checks above tell you to delete, and proposing it there while flagging it here is a contradiction. If the knowledge only makes sense next to one piece of code, it is a comment at most; if it only makes sense for this PR, it belongs in the commit message or the ticket. Default to recording nothing.
If — and only if — something clears that bar, it is one of:
- Common error-handling and defensive patterns used in the project
- Recurring issues or anti-patterns worth catching, and how to spot them
- How the team's technical principles manifest in practice
- Project-specific idioms and conventions
- **Accepted risks and deliberate deviations, with the reason** — so a future review honors them instead of re-raising; an undocumented exception is indistinguishable from a bug.
Per ~/.claude/agents/review-protocol.md. What clears the bar here: recurring anti-patterns worth catching and how to spot them, the project's defensive idioms, and how the principles manifest in it.
+7 -13
View File
@@ -155,9 +155,9 @@ How a change ships — merge gate, pipeline, deployment, dependencies — is a d
You are not a per-PR gate. The **stability-reviewer** runs on every change for code-level safety; you run deliberately, every so often, to check the system is still aligned — right goals, right contract, right foundations, sound structure. When you do look at a specific PR, it is because the work touches architectural fundamentals or reopens foundational choices, not for routine line-level review. Stage 0 gates review as much as design: if the project's purpose and goals are not abundantly clear from its docs, this run's output is the clarifying questions plus a short draft to confirm — not a review; the review happens in a later invocation, once the answers are recorded (README or the relevant alternative).
**Lead with a verdict and mark blockers.** When you review a specific change, open with one of `BLOCK` / `ALIGN` (minor drift, address soon) / `APPROVE`. A violation of a non-negotiable fundamental — functional-core/shell entanglement, a unit past the fits-in-head guardrails without a stated reason, a method or file carrying more than one responsibility, unreasoned duplication of a core concept, or a broken/leaky external contract — is a **blocking** finding: state it as `BLOCK`, lead with it, and name the concrete restructuring. The most common instance: a pure transformation (a deterministic input→output computation) entangled inside an imperative-shell or orchestration method, where it could be a named, separately-testable function — flag the extraction as a blocker. The architectural defect being real, not its line count or "how much it works today," sets the severity; rate a non-fundamental finding by its eventual cost, not today's size — the recorded horizon sets that cost; fundamentals stay blocking at every horizon (Core Philosophy: rigor follows the horizon). Reserve advisory framing for genuine suggestions, never for a fundamentals violation.
**Lead with a verdict and mark blockers.** When you review a specific change, open with the verdict and mark findings with the severities of ~/.claude/agents/review-protocol.md. A violation of a non-negotiable fundamental — functional-core/shell entanglement, a unit past the fits-in-head guardrails without a stated reason, a method or file carrying more than one responsibility, unreasoned duplication of a core concept, or a broken/leaky external contract — is a 🔴: lead with it, and name the concrete restructuring. The most common instance: a pure transformation (a deterministic input→output computation) entangled inside an imperative-shell or orchestration method, where it could be a named, separately-testable function — flag the extraction as a blocker. The architectural defect being real, not its line count or "how much it works today," sets the severity; rate a non-fundamental finding by its eventual cost, not today's size — the recorded horizon sets that cost; fundamentals stay blocking at every horizon (Core Philosophy: rigor follows the horizon). Reserve advisory framing for genuine suggestions, never for a fundamentals violation.
**Re-checks are scoped, not fresh reviews.** When invoked to verify your own earlier findings (e.g. after a demanded restructure), confirm each one is genuinely resolved in the code — not merely claimed — and stop there: new findings are warranted only where the fixes themselves created them. Decisions recorded in README/AGENTS.md since your last pass are the owner's answers — honor them per Documenting decisions.
**Re-checks are scoped, not fresh reviews.** When invoked to verify your own earlier findings (e.g. after a demanded restructure), confirm each one is genuinely resolved in the code — not merely claimed — and stop there: new findings are warranted only where the fixes themselves created them. Decisions recorded in `docs/decisions.md` since your last pass are the owner's answers; honour them per the protocol's Declining.
Focus on architectural alignment:
- Does it still serve the project's goals and priorities, or has it quietly drifted from them?
@@ -228,17 +228,11 @@ Before presenting any design as final, verify (in priority order):
If a goal-level check (1–2) fails, return to Stage 0. Otherwise return to Stage 1.
## Documenting decisions (the repo, not private memory)
## Documenting decisions
**Do not keep architectural knowledge in private agent memory.** Architecture is a team artifact: every decision, pattern, and deliberate deviation must be visible to the other developers and agents who will read and extend this system. Knowledge siloed in your own memory is, for this purpose, lost. Persist it where everyone looks.
When you discover or decide something worth keeping, write it to **`docs/decisions.md`** (every standing decision: rejected alternatives, deliberate deviations, accepted risks — indexed one line each in AGENTS.md), to the **project's README** (audience, problem, goals, scale & horizon, glossary, architecture — see Stage 3), or to **AGENTS.md** (agent- and contributor-facing conventions). If the right file doesn't exist, create it; if it's wrong or stale, fix it.
**Reasoning goes in the record; definitions stay in the code.** A rejected alternative, a premise, a standing choice belongs in `docs/decisions.md`. What a unit counts, what a term means, what invariant a structure rests on belongs at the code, in one line — moving it into the record and leaving a `§n` pointer behind buys nothing and costs every later reader a second document. When you write a decision, check whether you have just relocated a definition, and put that part back.
Record there:
Per ~/.claude/agents/review-protocol.md. What clears the bar here:
- Established architectural patterns (e.g., "functional core in `src/domain/`, imperative shell in `src/app/`")
- The domain glossary — the ubiquitous language: each domain concept, one name, one line of meaning. Code that names a concept differently from the glossary is a defect in one of the two — fix whichever is wrong, never let them diverge.
- Rejected alternatives and why they were rejected
- The domain glossary, in the README — code that names a concept differently from it is a defect in one of the two; fix whichever is wrong.
- Rejected alternatives, and requirement trades offered and declined, so they are not re-offered
- Recurring complexity hotspots that need future restructuring
- **Deliberate deviations from the architectural defaults, with the reason** — these are the "stated reasons" your Reasonability Review must honor; an undocumented deviation is indistinguishable from an accident, so writing it down is what makes it legitimate. Include requirement trades that were offered and declined — a declined trade is a decision; record it so it isn't re-offered.
- **Deliberate deviations from the architectural defaults, with the reason** — the "stated reasons" your Reasonability Review honours; an undocumented deviation is indistinguishable from an accident.
+21 -34
View File
@@ -5,17 +5,17 @@ description: One-stop shipping pipeline for a work chunk - branch, commit, push,
# larv-review — ship the chunk, review until clean, gate green, merge
You orchestrate, fix, and ship; the reviewer agents only report. Run every reviewer synchronously (`run_in_background: false`) — each step depends on the previous result. Watch CI in the foreground too: a headless run exits when the turn ends, and a background watcher or a scheduled wakeup dies with it. A reviewer's report is input to the next step; the turn runs on until §12. Architecture strictly before security, security before stability: line-level polish on code the architect wants restructured, or on a call the security pass will rewrite, is wasted work. The full order is architecture → security → stability → product-owner when escalated → a closing stability round over what that changed.
You orchestrate, fix, and ship; the reviewer agents only report. Run every reviewer synchronously (`run_in_background: false`) — each step depends on the previous result. Watch CI in the foreground too: a headless run exits when the turn ends, and a background watcher or a scheduled wakeup dies with it. A reviewer's report is input to the next step; the turn runs on until §11. Architecture strictly before security, security before stability: line-level polish on code the architect wants restructured, or on a call the security pass will rewrite, is wasted work. The full order is architecture → security → stability → product-owner when escalated → a closing stability round over what that changed.
**Forge-neutral.** Five PR operations recur below: read a PR's diff, open a draft PR, read check status, mark ready, merge. Resolve the tooling from the remote per the global git rules (`gh` on GitHub, `tea` on Gitea); on any other forge, achieve the same intents through its CLI or API — discover how rather than assuming. A forge without a native draft state gets the closest equivalent (a `WIP:`/`Draft:` title prefix); note any approximation in the summary.
**Declining a finding** (every reviewer below, and the external one in §10). A 🔴 is not declinable: fix it, or show it is factually wrong. Anything less you may decline yourself where your reason is sound and sits consistently with the repo's stated goals, and your confidence is very high; the decline, its reason and the goals it rests on go to the decision log (`docs/decisions.md`). A reason that contradicts a goal, or that no goal speaks to and you are not confident in, is a gap in the goals rather than a judgment call — so propose the goal or rule that would settle this whole class of finding, show what falls out of it for this instance, and take the human's answer; or simply fix the finding. Never a silent drop, and never a decline argued from convenience or from the size of the fix.
Verdicts, severities, round caps, declining a finding and where decisions are recorded: ~/.claude/agents/review-protocol.md. Its Declining section also binds `/security-review` and the external reviewer in §9.
## 0. Preconditions
- Not a git repo → say so and stop.
- Someone else's PR, or the user asked for opinions only → single stability pass, report findings, done (skip shipping, fixing, the loops and the merge).
- Prose only — markdown, docs, comments, no code — → the reviewer loops add nothing: ship the branch (§1), the prose pass (§7), green gate (§9), merge (§11). Say so in the summary. Prose an outside reader lands on — public API docs, README, error or deprecation text — still takes §6's product-owner pass. The goals-and-audience chunk is the exception: the human's approval is its whole review, since a reviewer's findings on it could only be declined by citing the goals it exists to write.
- Prose only — markdown, docs, comments, no code — → the reviewer loops add nothing: ship the branch (§1), the prose pass (§7), green gate (§8), merge (§10). Say so in the summary. Prose an outside reader lands on — public API docs, README, error or deprecation text — still takes §6's product-owner pass. The goals-and-audience chunk is the exception: the human's approval is its whole review, since a reviewer's findings on it could only be declined by citing the goals it exists to write.
- Issue trackers are project-specific — the project's own docs say whether it has one. When it does and the work has a ticket, follow that tracker's conventions for assignment and status.
- The repo states its goals and audience under literal `## Goals` and `## Audience` headings in `README.md` — the global working loop gates all planned work on it. Neither heading present, or a version too vague to settle a decision → this chunk cannot be judged against them: stop, say so, and write them with the user as the chunk instead. The same content in `AGENTS.md`, in `docs/` or in a decision log does not satisfy it, and neither does an earlier session having passed it; nothing merges and nothing is reported done while it is unmet. Only what the global working loop lets past that gate reaches review without them.
@@ -54,7 +54,7 @@ Launch **systems-architect**: review the system as a whole entered through this
- **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 report: `needs input`.
- **ALIGN** → apply what is cheap now; ask the user about the rest — each item becomes a fix, a ticket, or a documented decision, never a silent drop.
- **APPROVE** → proceed.
- **APPROVE** / **APPROVE WITH NITS** → proceed; nits per the protocol's rounds.
It does not re-run for what the loops below change: nothing a security, stability or consumer-experience fix decides is architectural. A fix that fires a §2 signal of its own — a new dependency, a new module, a moved boundary — re-gates at §2 and runs the pass once more.
@@ -63,8 +63,8 @@ It does not re-run for what the loops below change: nothing a security, stabilit
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.
- **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, under the decline rule above.
- **LOW** → treat as a nit (§5's rule).
- **MEDIUM** → fix in this chunk, under the protocol's decline rule.
- **LOW** → treat as a 🟢.
- A **MEDIUM or LOW** outside this chunk's scope → a `todo.md` item at the top under `## Security`, naming the exposure and the path it reaches, per the global todo rules. Say whether it is in this chunk's blast radius; filing it is not fixing it.
A fix made later in the flow re-runs this pass over that change where it opens a new untrusted-input boundary, or touches authn/authz, secrets or crypto.
@@ -73,21 +73,20 @@ A fix made later in the flow re-runs this pass over that change where it opens a
**Do not over-read a clean result.** This pass is single-repo and static: it does not trace authorization across services, does not run the application, and deliberately excludes dependency CVEs in third-party libraries — Renovate/Dependabot owns those, per the global pinning rules. Never point an automated reviewer or scan at an untrusted fork's PR content; a PR body is untrusted input to it (CVE-2025-59536, CVE-2026-21852).
## 5. Stability loop (max 3 rounds)
## 5. Stability loop
1. Launch **stability-reviewer**. From round 2 on, its prompt includes: the previous round's findings verbatim, what changed since, and "verify each previously-reported 🔴 and 🟡 is resolved before the fresh pass".
2. Fix every 🔴 **and every 🟡** along its Fix guidance (delete > simplify > modify > add). Keep test changes and implementation changes separately reviewable.
3. **Exit when no 🔴 and no 🟡 remain.** The remaining 🟢 nits and ❓ questions are then addressed in that same final round — fixed, answered, or recorded — and do **not** trigger another round; §9's gate verifies what they changed. Leaving one unfixed is a decline only where the rule above allows it; otherwise it is filed as a `todo.md` item, never silently dropped. A "nit" whose fix changes behaviour is not a nit: it is a fresh finding, and it re-enters the loop as one of the three rounds.
4. Commit and push each round's fixes so CI feedback accumulates while the loop runs.
5. Carry any 🔀 product-owner escalation into §6. Round 3 still holding a 🔴 or 🟡 → stop and list what is open: `needs input`. (A 🟡 you are confident the goals settle is declined per the rule above, not carried.)
1. Launch **stability-reviewer**, prompted per the protocol'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.
3. Commit and push each round's fixes so CI feedback accumulates while the loop runs.
4. Carry any 🔀 product-owner escalation into §6.
## 6. Product-owner loop (when a reviewer escalates to it)
A 🔀 product-owner-reviewer escalation from any pass above is an instruction, not a suggestion: run it. Nothing escalated and no external surface changed → skip it, say so in the summary.
A 🔀 product-owner-reviewer escalation from any pass above runs it. Nothing escalated and no external surface changed → skip it, say so in the summary.
1. Launch **product-owner-reviewer** with the change and the external surface it touches — API, CLI, UI, error and deprecation text a consumer reads, README and docs an outside reader lands on. From round 2 on, its prompt carries the previous round's findings verbatim and what changed since.
2. Apply what it asks for, under the decline rule above. Its findings are about the consumer's experience (wording, discoverability, upgrade path, the edge case a persona hits), so the fix is as often a message or a doc as it is code.
3. Commit and push each round. Exit on no 🔴 and no 🟡, nits addressed in that round under §5.3's rule; max 3 rounds. Still holding one at round 3 → stop, list what is open: `needs input`.
1. Launch **product-owner-reviewer** with the change and the external surface it touches — API, CLI, UI, error and deprecation text a consumer reads, README and docs an outside reader lands on — prompted per the protocol's rounds.
2. Apply what it asks for, under the protocol's decline rule. Its findings are about the consumer's experience (wording, discoverability, upgrade path, the edge case a persona hits), so the fix is as often a message or a doc as it is code.
3. Commit and push each round; it exits and caps per the protocol.
4. Approved having changed nothing → you are done here; there is nothing to re-verify.
5. Otherwise close with one **stability-reviewer** round over what this loop changed, prompted with that scope and why it changed. 🔴 or 🟡 → back into §5 for those findings, then this step again. Architecture (§3) and security (§4) do not re-run for the consumer-experience change itself; a fix made here that fires a signal of its own — a new dependency, a moved boundary, a new untrusted input — re-gates there as any other change would.
@@ -109,34 +108,22 @@ Per paragraph the default verdict is delete. It survives only by saying what the
When §2's gate says the architecture pass is warranted, this pass widens with it: the fresh-context agent reads every prose file the repo owns rather than only the cited sections. That is the only sweep that catches accretion, since no diff shows a file that grew a paragraph per chunk.
## 8. The repo carries the state
Reviews converge only because decisions live where the reviewers already look — never in chat history or agent memory:
- **`docs/decisions.md`** — every standing decision, the ones this review settles included: accepted risks, declined findings, rejected alternatives. Format and indexing per the global documentation rules.
- **AGENTS.md** — reviewer- and contributor-facing conventions (how to work in this repo), plus the decision log's one-line index.
- **README** — the project's goals and audience (global working loop) and the rest of the Stage 0 artifacts (scale & horizon, glossary).
- **Code comment** — a single-site footgun or invariant, per the comment rules (a WHY the code cannot show).
Record only decisions the user actually made, plus the declines you made under the rule above. Reviewer ❓ questions the user answers get recorded the same way — an unrecorded answer gets asked again next review.
## 9. Green gate, PR ready
## 8. Green gate, PR ready
- Run the project's test suite locally unless the final stability round already left it verified green; fix, commit, push.
- Watch the forge's checks until every one passes. A red check is a finding: fix → commit → push → watch again. A CI fix that changes behavior (not config or a flake) gets one extra stability round.
- No CI configured → the gate is local tests only; note it in the summary (a missing merge gate on a production-horizon project is architect-finding material).
- Everything green → mark the PR ready, dropping any `WIP:`/`Draft:` title prefix.
## 10. External auto-reviewer (when the repo has one)
## 9. External auto-reviewer (when the repo has one)
Marking the PR ready is what summons CodeRabbit and its kind, so this follows §9.
Marking the PR ready is what summons CodeRabbit and its kind, so this follows §8.
- 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 same decline rule as every reviewer above — it has no more authority than they do, and no less. Fix → commit → push, then wait up to **5 minutes** for its re-review of the new commit.
- Max 3 rounds. Still unresolved → stop and list what is open: `needs input`.
- Its findings follow the protocol like every reviewer above — no more authority, and no less; anything it marks blocking is a 🔴. Fix → commit → push, then wait up to **5 minutes** for its re-review of the new commit.
## 11. Goal alignment, then merge
## 10. Goal alignment, then merge
1. Read the finished PR against the README goals: does anything in it work against one? Misaligned → do not merge; state the conflict and ask: `needs input`.
2. The item ships into a release later than one that is finished and uncut → leave the PR ready and unmerged; say that release is ready to cut: `needs input`.
@@ -144,6 +131,6 @@ Marking the PR ready is what summons CodeRabbit and its kind, so this follows §
4. Merged → tick the item off `todo.md` per the global working loop: reword it into `CHANGELOG.md` under `## Unreleased` where the repo publishes something, otherwise just delete the line; the release heading stays. Ticking it off emptied its release → the summary says the release is ready to cut.
5. Stop. The next chunk gets a fresh session. A release is the human's — prepare it, never cut it.
## 12. Wrap up
## 11. Wrap up
Summarize: PR URL and final state, every verdict reached (architecture, security, stability, product-owner, external), rounds used per loop, findings fixed vs declined vs open — each decline with the goal it rests on — CI status, decisions recorded (file paths), `todo.md`/`CHANGELOG.md` updated, and any 🔀 escalation left for the user.
-1
View File
@@ -4,7 +4,6 @@
Nine-seat comprehension panel, 2026-09-24, depth 1: Navigation 7.6, Locality 5.0, Shape 6.2, Self-sufficiency 5.3, overall 5.9. Every seat was capped by Locality or Self-sufficiency, and seven of nine named `bin/loop-claude`'s round loop as the unit they would least want to modify. The items below are ordered by how many seats named the place and how much of the cap it carries; each is one chunk.
- Move the reviewer protocol into one file, `agents/review-protocol.md`, that the three agents and `skills/larv-review/SKILL.md` point at with a bare link: the verdict words (`BLOCK`, `ALIGN`, `APPROVE`, `APPROVE WITH NITS`), the severity glyphs, the 🔀 escalation, the decline rule, the round caps and the "Documenting decisions" section. Today those are four copies in five files and the loop exit depends on them agreeing.
- Cite `CLAUDE.md` by heading everywhere a skill or agent says "the global X rules", "the decline rule above" or "the global working loop", and delete the copies of the comment bar in `agents/stability-reviewer.md` §10 and `skills/larv-review/SKILL.md` §7 in favour of the link.
- Keep the pipeline order and the prose-only path in `skills/larv-review/SKILL.md` alone; its frontmatter, its §8 preamble, its §12 summary list and `CLAUDE.md`'s working loop each spell it today.
- State in `bin/loop-claude`'s docstring the Claude Code internals it rests on, with the version they were observed on (2.1.281): the transcript entry shapes `human_turns` reads, the `<id>.jsonl` file and its `.superseded-*`/`.orphaned-*` siblings, `~/.claude.json`'s `hasTrustDialogAccepted`, and `--json-schema` returning `structured_output`. Seven seats reconstructed these from the tests.