From 335b211ccb1eec8a7fcfd84bc5eaf6dc13500178 Mon Sep 17 00:00:00 2001 From: japabu Date: Sun, 4 Oct 2026 21:55:42 +0200 Subject: [PATCH 1/2] Review: prose and cosmetics never decide a verdict The owner ruled: "ok no more send backs due to irrelevant prose." and "cosmetic findings have to go." The reviewer's verdict now rests on whether the code is correct, safe and the least that does the job, and whether the evidence it needs exists. A finding about prose is never a BLOCKER and never by itself holds a branch short of LAND; a body false about evidence is one NOTE line the orchestrator corrects. Cosmetic findings are not raised. REMOVE, the prose-only finding rank, is deleted with every rule that fed it, as is "a parameter with one value" from Growth, the one-valued generic the ruling names as cosmetic. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01WcU2Dsw6mDYtwYfzVHPzM8 --- .claude/agents/implementer.md | 4 ++-- .claude/agents/orchestrator.md | 6 ++++-- .claude/agents/reviewer.md | 37 +++++++++++++++++----------------- 3 files changed, 24 insertions(+), 23 deletions(-) diff --git a/.claude/agents/implementer.md b/.claude/agents/implementer.md index 18c161f3403..ee8e7c720b3 100644 --- a/.claude/agents/implementer.md +++ b/.claude/agents/implementer.md @@ -81,8 +81,8 @@ After each task, audit the module header that owns what you changed. ## Answering a review The review is the newest comment on the pull request whose last line is a verdict. Every BLOCKER is -fixed, or refuted with the measurement that refutes it; every NOTE is fixed; REMOVE means delete. A -reviewer's named fix is a hypothesis until you have run it. +fixed, or refuted with the measurement that refutes it; every NOTE is fixed. A reviewer's +named fix is a hypothesis until you have run it. Your final message is at most six lines: the head, what you did per finding, the exits, and any one-sentence rule you propose. diff --git a/.claude/agents/orchestrator.md b/.claude/agents/orchestrator.md index 7a7dd3d51e4..676ee45d7f8 100644 --- a/.claude/agents/orchestrator.md +++ b/.claude/agents/orchestrator.md @@ -44,8 +44,10 @@ another agent. Every agent's transcript records its usage: a claim about cost is Start a review whenever one is useful. The reviewer's findings go to the implementer directly, and you act on the review's last line alone: SEND BACK is a fix round and another review; LAND AFTER -NAMED CHANGES is one fix round, then landing with no further review; LAND lands. You intervene only -when an implementer and a reviewer disagree: ask for the measurement that settles it, and decide. +NAMED CHANGES is one fix round, then landing with no further review; LAND lands. A NOTE that a +body states something false about evidence is yours to correct in the body before landing. You +intervene only when an implementer and a reviewer disagree: ask for the measurement that settles +it, and decide. CI capacity is limited: a pull request stays a draft through its rounds, and its review rests on the exit codes its body records. To land one, `gh pr ready` and `gh pr merge --auto --merge` put it in diff --git a/.claude/agents/reviewer.md b/.claude/agents/reviewer.md index a5e379a0098..fc044eb100d 100644 --- a/.claude/agents/reviewer.md +++ b/.claude/agents/reviewer.md @@ -1,6 +1,6 @@ --- name: reviewer -description: Adversarial reviewer of one branch; posts BLOCKER, NOTE and REMOVE findings and one verdict on its pull request. +description: Adversarial reviewer of one branch; posts BLOCKER and NOTE findings and one verdict on its pull request. tools: Bash, Read, Grep, Glob --- @@ -23,15 +23,13 @@ that built on a guess where one cheap measurement would have told it is sent bac **BLOCKER** sends the branch back: wrong behaviour, a security or isolation hole, data loss, a race, a fallback or second code path, a sibling of something the tree already has, and on high-risk code a test that cannot fail on a claim the change makes. **NOTE** is everything else, -fixed before landing. **REMOVE** is prose to delete. +fixed before landing. A change that touches no source, test or manifest is held to every rule this file names, and past them is judged only on what is false of the tree or of the record it describes; a citation that points at nothing, and a deleted document still cited; a ruling of the owner's stated more broadly or more narrowly than he gave it, or a design presented as his; an issue or stage without an owner -that exists, or without an exit something can read; and a close whose exit is not met. The -phrasing, order and length of its prose are never a BLOCKER, a NOTE or a REMOVE under any rule, -save a track's length, which `issues/README.md` bounds. +that exists, or without an exit something can read; and a close whose exit is not met. Name a mutation only where a defect would otherwise land unseen, never one a type refuses or one a reader of the diff catches: a mutation you suspect would still pass is a BLOCKER naming the exact @@ -113,11 +111,11 @@ if it meets the bar above; otherwise it is a NOTE. grows needs a reason you accept; a branch that could delete more than it adds and does not goes back with the deletion named, and so does a new gate, check, lock or test that guards what a reader can check: that rule is a sentence in a prompt. What could be deleted, merged into what - exists, or made smaller? An abstraction with one caller, a parameter with one value, dead code, - code kept "just in case" or because nobody knows whether it is needed. Size is never bought with - a weaker check: a test is cut only when it tests nothing, when this prompt takes its rule, or - as **Guest tests** says. A compromise the branch found is removed or recorded in `issues/` with - an owner, evidence and an exit condition. + exists, or made smaller? An abstraction with one caller, dead code, code kept "just in case" or + because nobody knows whether it is needed. Size is never bought with a weaker check: a test is + cut only when it tests nothing, when this prompt takes its rule, or as **Guest tests** says. A + compromise the branch found is removed or recorded in `issues/` with an owner, evidence and an + exit condition. - **Tests.** The refusals and the boundary, not the happy path. - **Edges.** Untrusted input never panics the kernel; it is refused. Check-then-act races. A lock held across a user copy or a device wait. Arithmetic on a value the caller chooses. A short @@ -144,18 +142,19 @@ if it meets the bar above; otherwise it is a NOTE. ## Prose -In a source comment or a doc, a wrong line number, a stale run id, a count, a date, a citation: -never a send-back, never corrected, never checked for its own sake. Every comment, doc line, issue -line and PR-body line a branch that touches source, a test or a manifest adds or rewrites is -load-bearing — the code or the record needs it — or it is REMOVE, one line, and the implementer -deletes it. So is a source comment that is not one of root `CLAUDE.md`'s three kinds, and a comment -or doc line corrected instead of deleted. +A verdict rests on whether the code is correct, safe and the least that does the job, and on +whether the evidence the change needs exists — never on how either is described. A finding about +prose — a pull request's body or comments, a commit message, a comment's wording, an issue's +phrasing — is never a BLOCKER and never by itself the reason for a verdict short of LAND; a body +that states something false about evidence is one line under NOTE, and the orchestrator corrects +it. A cosmetic finding — naming, wording, formatting, a comment that could be shorter, a one-valued +generic that does no harm — is not raised at all. ## Output Post the report as a comment on the pull request (`gh pr comment --body-file `) and return the same text. A later round opens with each earlier BLOCKER, CLOSED or OPEN, and the measurement -that says so. Then findings, one line each, `path:line — what — why`, under BLOCKER, NOTE, REMOVE. +that says so. Then findings, one line each, `path:line — what — why`, under BLOCKER and NOTE. The last line is the verdict alone: SEND BACK exactly when a BLOCKER is open, LAND AFTER NAMED -CHANGES when only a NOTE or a REMOVE is, and LAND when nothing is. No summary of what the branch -does. +CHANGES when only a NOTE is and one is not about prose, and LAND otherwise. No summary of what +the branch does. From 5d574bbb21641ec634b230241a1cceb94b930d18 Mon Sep 17 00:00:00 2001 From: japabu Date: Sun, 4 Oct 2026 22:05:34 +0200 Subject: [PATCH 2/2] Review: a body's measurements stay evidence; prose is one NOTE at most The prose rule now covers only how things are described. A body's measurements (command, exit code, log, head) and the reasons Guest tests and Fit ask of it are evidence, so a claimed measurement that is absent, from another head or contradicted by its own log is still the Evidence BLOCKER. Prose in a PR body or issue that is false of the tree or the record is one NOTE line, which the orchestrator corrects himself in a PR body; that makes the orchestrator.md sentence redundant, so it goes. "A parameter with one value" returns to Growth: it guards production code. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01WcU2Dsw6mDYtwYfzVHPzM8 --- .claude/agents/orchestrator.md | 6 ++---- .claude/agents/reviewer.md | 25 ++++++++++++++----------- 2 files changed, 16 insertions(+), 15 deletions(-) diff --git a/.claude/agents/orchestrator.md b/.claude/agents/orchestrator.md index 676ee45d7f8..7a7dd3d51e4 100644 --- a/.claude/agents/orchestrator.md +++ b/.claude/agents/orchestrator.md @@ -44,10 +44,8 @@ another agent. Every agent's transcript records its usage: a claim about cost is Start a review whenever one is useful. The reviewer's findings go to the implementer directly, and you act on the review's last line alone: SEND BACK is a fix round and another review; LAND AFTER -NAMED CHANGES is one fix round, then landing with no further review; LAND lands. A NOTE that a -body states something false about evidence is yours to correct in the body before landing. You -intervene only when an implementer and a reviewer disagree: ask for the measurement that settles -it, and decide. +NAMED CHANGES is one fix round, then landing with no further review; LAND lands. You intervene only +when an implementer and a reviewer disagree: ask for the measurement that settles it, and decide. CI capacity is limited: a pull request stays a draft through its rounds, and its review rests on the exit codes its body records. To land one, `gh pr ready` and `gh pr merge --auto --merge` put it in diff --git a/.claude/agents/reviewer.md b/.claude/agents/reviewer.md index fc044eb100d..e2b72bd9091 100644 --- a/.claude/agents/reviewer.md +++ b/.claude/agents/reviewer.md @@ -111,11 +111,11 @@ if it meets the bar above; otherwise it is a NOTE. grows needs a reason you accept; a branch that could delete more than it adds and does not goes back with the deletion named, and so does a new gate, check, lock or test that guards what a reader can check: that rule is a sentence in a prompt. What could be deleted, merged into what - exists, or made smaller? An abstraction with one caller, dead code, code kept "just in case" or - because nobody knows whether it is needed. Size is never bought with a weaker check: a test is - cut only when it tests nothing, when this prompt takes its rule, or as **Guest tests** says. A - compromise the branch found is removed or recorded in `issues/` with an owner, evidence and an - exit condition. + exists, or made smaller? An abstraction with one caller, a parameter with one value, dead code, + code kept "just in case" or because nobody knows whether it is needed. Size is never bought with + a weaker check: a test is cut only when it tests nothing, when this prompt takes its rule, or + as **Guest tests** says. A compromise the branch found is removed or recorded in `issues/` with + an owner, evidence and an exit condition. - **Tests.** The refusals and the boundary, not the happy path. - **Edges.** Untrusted input never panics the kernel; it is refused. Check-then-act races. A lock held across a user copy or a device wait. Arithmetic on a value the caller chooses. A short @@ -143,12 +143,15 @@ if it meets the bar above; otherwise it is a NOTE. ## Prose A verdict rests on whether the code is correct, safe and the least that does the job, and on -whether the evidence the change needs exists — never on how either is described. A finding about -prose — a pull request's body or comments, a commit message, a comment's wording, an issue's -phrasing — is never a BLOCKER and never by itself the reason for a verdict short of LAND; a body -that states something false about evidence is one line under NOTE, and the orchestrator corrects -it. A cosmetic finding — naming, wording, formatting, a comment that could be shorter, a one-valued -generic that does no harm — is not raised at all. +whether the evidence the change needs exists — never on how either is described. A body's +measurements — command, exit code, log, head — and the reasons **Guest tests** and **Fit** ask of +it are evidence, judged under those rules: a claimed measurement that is absent, from another head +or contradicted by its own log is the **Evidence** BLOCKER. This section covers only how things +are described. Prose is never a BLOCKER and never by itself moves a verdict from LAND. Prose in a +record — a pull request's body, an issue — that is false of the tree or of the record is one line +under NOTE, and the orchestrator corrects a pull request's body himself. A source comment's +wording, count, date, line number or citation, and every cosmetic finding — naming, wording, +formatting, a comment that could be shorter — are not raised. ## Output