Answer prose round 1: 0 🔴, 8 🟡; state what rule-hook refuses, split the decision and credit it to item 73, order review-findings.md by first use, invert the report-naming sentence, and reword the changelog, the stability scratch line and the replay's comments

This commit is contained in:
2026-10-18 01:21:35 +02:00
parent 2b1d3707c8
commit f6f84e534b
10 changed files with 36 additions and 30 deletions
+1 -1
View File
@@ -36,7 +36,7 @@ Decisions live in `docs/decisions.md`:
- rules/: `CLAUDE.md` holds the worker's rules that no file path can scope, and each topic's rules for the worker live in a `rules/` file that Claude Code loads by its `paths:` frontmatter
- worker: a chunk's worker writes the simplest change that solves its item, test first wherever a test can check the change, and reads a technical principle only where the item, a finding or its own record names it; larv-review's reviewers hold the change to the principles and to the standards in `skills/larv-review/standards/`
- tests: each test earns its keep as the technical principles' test bullet says, and the worker takes a test's expected values from its item, never from the code
- review: each reviewer under `agents/` writes its full report into the chunk's review folder under `~/.local/state/larv-review/` and returns the worker its verdict and one line per finding; rule-hook refuses any other file call from it
- review: each reviewer under `agents/` writes its full report into the chunk's review folder under `~/.local/state/larv-review/` and returns the worker its verdict and one line per finding; rule-hook refuses its Edit and MultiEdit, and any Write outside `~/.local/state/larv-review/`
- review: stability and product-owner report only a defect, a broken requirement of the plan or the goals, a breach of a technical principle, or for stability a hard place the change touches; each architect finding names a later change the PR makes harder; prose runs only on a chunk that changes prose
- review: the stability pass mutation-tests the lines a chunk changes, in place of measuring test coverage
- routing: one ladder of (model, effort) rungs, ordered by the Artificial Analysis Intelligence Index with Fable 5.1 at max on top; a task's L picks its worker's rung and its E + I its reviewers', by fixed steps counted from the cheapest rung of the project's model
+1 -1
View File
@@ -2,7 +2,7 @@
## Unreleased
- Each reviewer under `agents/` writes its full report to a file under `~/.local/state/larv-review/`, which larv-review names in its prompt, and returns only its verdict and one line per finding, so a review takes less of the worker's context. The worker reads a finding's full entry before it fixes or answers a 🔴 or 🟡. Each reviewer now holds Write. `rule-hook` refuses a reviewer's Edit and MultiEdit, and any Write outside that folder, and takes no override. Each chunk's folder stays after the merge, so `stability-replay` can replay a later round, which it does on a copy of the folder.
- Each reviewer under `agents/` now writes its full report to a file that larv-review names in the reviewer's prompt, in a folder per chunk under `~/.local/state/larv-review/`. It returns only its verdict and one line per finding, so a review takes less of the worker's context. The worker reads a finding's full entry before it fixes or answers a 🔴 or 🟡. Each reviewer now holds Write. `rule-hook` refuses a reviewer's Edit and MultiEdit, and any Write outside `~/.local/state/larv-review/`; no override waives this rule. Each chunk's folder stays after the merge, so `stability-replay` can replay a round that reads an earlier round's report. It replays on a copy of the folder.
- `loop-claude` asks an interrupt's question on its own terminal and resumes the worker headless with your one-line answer, so the loop no longer waits for you to leave a claude session. Type `/talk` instead to open the worker's session in claude, as every interrupt did before, to read the diff or discuss first. A release ready to cut opens that session at once. Pressing Enter on an empty answer stops the loop, exit 2. Keys typed before the question shows are dropped, and a pasted answer keeps only its first line; type `/talk` for a longer one. The judge counts that answer as yours, like one typed in claude: the chunk stays open until the answer is recorded, where a later chunk could need it.
- When a worker's run ends with a question and a request for a higher rung, `loop-claude` now steps the worker one rung up as the judge interrupts, or as it answers the question with a quote from `README.md` or another file it may quote. The judge must quote a passage showing that the escalation trigger the run cites fired. Before, the step was lost for an answered question, and the worker carried on from the answer on its old rung. The step has the same limits as the step on an unfinished verdict, and no later ruling of that cycle carries a second escalation. The archive's interrupt and quoted-answer outcomes now name the worker's rung.
- A scoring run due because a release's items ran out costs four more seats: it is done twice on one head. `larv-review agreement` compares how often Mid A and the inherited architect vote alike in paired rulings with how often their overall scores move the same way between the two runs. After 10 such pairs it gives a verdict, and on `Assumption fails:` larv-review asks you whether to keep the paired ruling.
+1 -1
View File
@@ -66,7 +66,7 @@ The rules only reviewers apply, for quality, comments, READMEs and prose, live i
4. A review rules the work below standard: systems-architect's BLOCK, a finding against larv-review's `standards/quality.md`, or a vote `record-ruling` counts as worse, in the report that stands after any relaunch one rung up (`larv-review` §3 → "Rung up").
When one fires, hand the hard part, edits included, to a subagent on the rung loop-claude's prompt names, one above yours. Open the subagent's prompt with the marker loop-claude's prompt gives, then the trigger's evidence. Each later subagent on that task runs on that rung or higher, and each further escalation trigger moves the task one rung higher, up to the highest rung loop-claude's prompt names. Ask the human before going higher. Where loop-claude's prompt names no escalation, as on the ladder's top rung or off it, keep the task in your own thread.
- Give a subagent only the access its job needs, and state the limits in its prompt. One that only reads, such as a prose review, gets no shell and no edits; a reviewer under `agents/` also writes its report to the file larv-review names, and rule-hook refuses it any other Write, Edit or MultiEdit. One that probes a build tags the image as throwaway and removes it afterwards, writes only to the session scratchpad, and removes no image or file it did not create.
- Give a subagent only the access its job needs, and state the limits in its prompt. One that only reads, such as a prose review, gets no shell and no edits. A reviewer under `~/.claude/agents/` writes only its report, under `~/.local/state/larv-review/`, and rule-hook refuses it every other Write, every Edit and every MultiEdit. One that probes a build tags the image as throwaway and removes it afterwards, writes only to the session scratchpad, and removes no image or file it did not create.
- Check `README.md` first for build, test, install, and codegen commands, and fix one that misbehaves in the same change. Refresh `README.md` whenever you change what it describes, keeping it true, not longer.
- Where `~/.claude/bin/rule-hook` does not check it, such as an image named in test code, a Kubernetes manifest, a `docker run` line or a file a Bash command writes, pin a container image to its full patch version and a GitHub Action to a semver tag.
+1 -1
View File
@@ -12,7 +12,7 @@ You are an elite stability-focused code reviewer with deep expertise in defensiv
1. **Scope the change.** You review every PR; a fresh invocation has no prior context, so determine the diff yourself. Diff the PR branch against its base (`gh pr diff`, or `git merge-base <base> HEAD` then `git diff`), and review the changed lines **plus enough surrounding code and callers** to judge correctness — read the whole changed file when practical; a diff alone hides whether a caller breaks. Read the PR description and, when the project uses an issue tracker (project-specific — check its docs) and the change references a ticket, that ticket: the diff is judged against its stated intent, and a scope mismatch in either direction is a finding — claimed-but-unimplemented, and implemented-but-unasked (#2).
2. **Read every file under `~/.claude/principles/`**, the shared principles, and `~/.claude/skills/larv-review/standards/quality.md`. These are mandatory org guidelines; all code MUST comply with each that applies. A file's `Applies to` line says what it covers; one without the line covers every change. Re-read each time — they change. Flag violations prominently.
3. **Read README.md, AGENTS.md and `docs/decisions.md`** in the current project for project-specific conventions, build instructions, tooling, and the accepted trade-offs a reviewer should honor rather than re-flag. Note the documented test, lint, and static-analysis commands — you will run them.
4. **Verify, don't just read.** Run the test suite and static analysis/linters through the project's container tooling, unless a decision puts them on the host; tear down test containers afterwards. A full-suite run catches broken callers that diff-reading misses. When a suspected bug is cheap to confirm, reproduce it — a scratch script, a targeted test run — before reporting it. Put scratch work in a directory you create for this run, through Bash, since Write is for your report alone, and delete it when done; delete nothing else, since a directory the prompt names may hold other agents' files. Leave the working tree exactly as you found it. Anything you could not run goes in Coverage & Verification, never silently skipped.
4. **Verify, don't just read.** Run the test suite and static analysis/linters through the project's container tooling, unless a decision puts them on the host; tear down test containers afterwards. A full-suite run catches broken callers that diff-reading misses. When a suspected bug is cheap to confirm, reproduce it — a scratch script, a targeted test run — before reporting it. Make scratch work with Bash, since Write is for your report alone. Put it in a directory you create for this run, and delete it when done; delete nothing else, since a directory the prompt names may hold other agents' files. Leave the working tree exactly as you found it. Anything you could not run goes in Coverage & Verification, never silently skipped.
5. **Mutation-test the changed lines.** Run the project's documented mutation command, or else a widely deployed mutation tool for the language: cargo-mutants for Rust, Infection for PHP, mutmut for Python, Stryker for JavaScript and TypeScript. Limit it to the lines the change adds or modifies, through the tool's own option where it has one (cargo-mutants `--in-diff <diff file>`, Infection `--git-diff-lines`, Stryker `--mutate <file>:<lines>`); otherwise mutate only the changed files and keep only the mutants on changed lines. Run it through the project's tooling, as in step 4, on a scratch copy: the tools write files. Report its wall time and mutant count in Coverage & Verification, or why nothing was mutated. Ignore a surviving mutant that leaves behaviour unchanged, or changes only message or log text no caller or user depends on. Report one 🟡 per test to add or strengthen, naming the surviving mutants it would catch.
6. **Two passes minimum, then hunt absences.**
- *Breadth:* every hunk in every changed file, no skimming. Track which files you have covered; batch large diffs, never truncate the review.
+1 -1
View File
@@ -1,7 +1,7 @@
"""The chunk's review folder, where each reviewer writes its report: skills/larv-review/SKILL.md → "Reports"."""
import os
# Under the home folder: outside every checkout, so no project sees a report; kept across a reboot, so a resumed chunk still reads its rounds. A fixed path, since a headless session has no scratchpad.
# Why here: docs/decisions.md → `review: each reviewer under agents/ writes its full report into the chunk's review folder`.
REPORTS = ".local/state/larv-review"
+1 -1
View File
@@ -24,7 +24,7 @@ default branch lacks, and those logged under the branch's own name.
Run with no arguments in a terminal, it prints this help.
Exit 2 with the rule, why it holds and how to override it, when a rule blocks the call, or when an
Exit 2 with the rule, why it holds and, where the rule takes an override, how to write one, when a rule blocks the call, or when an
override cannot be logged; 0 otherwise. `rule-hook overrides` exits 1 when git cannot read the
checkout or the branch's reflog. Exit 1, a non-blocking error to Claude Code, on input it
cannot read.
+4 -4
View File
@@ -11,8 +11,8 @@ branch stands at the newest commit authored before the round's chunk began, so a
shows the chunk's change. The prompt names the clone in place of the worktree it named, which the
chunk has since removed. A round whose code it cannot find in this way is not replayed; stderr
names it and why. The prompt also names a copy of the chunk's review folder in place of that
folder, holding only the reports written after the chunk began and before the round did. A replay whose prompt still
names the review folder finds nothing.
folder, holding only the reports written after the chunk began and before the round did. A replay
whose prompt still names the review folder finds nothing.
It first replays every round on the project's rung, the reference reviewer. Findings on record
that the reference reviewer does not raise again may rest on code or rules that have changed
@@ -174,12 +174,12 @@ def review(found: Round, code: Code, rung: Rung, home: pathlib.Path, effects: Ef
def reviewed_in(found: Round, code: Code, rung: Rung, home: pathlib.Path, effects: Effects, clone: str, reports: str) -> str | Failure | Limited:
"""The report of found's reviewer on rung, replayed on code cloned into clone, with its review folder copied into reports."""
# The reviewer writes its report into a copy of the chunk's review folder, so it leaves the chunk's reports as they were and still reads the earlier rounds its prompt names. The copy holds only the reports written after the chunk began and before the round began: the round's own report, later ones, and an earlier attempt's at the item in the same worktree, would hand the reviewer the findings it is to find.
# The round's own report, any later one, and one from an earlier attempt at the item in the same worktree would each hand the reviewer the findings it is to find.
folder = pathlib.Path(review_folder(str(home), code.path))
for written in folder.iterdir() if folder.is_dir() else ():
if written.is_file() and found.began <= written.stat().st_mtime < found.seconds:
shutil.copy2(written, reports)
# The folder goes first: for a worktree outside home, its path holds the worktree's, which code.path would otherwise turn into the clone's.
# Replace the folder's path first: outside home it contains the worktree's path, which replacing code.path would otherwise turn into the clone's.
prompt = found.prompt.replace(str(folder), reports).replace(f"~/{folder.relative_to(home)}", reports).replace(code.path, clone)
# A spelling the rewrite misses, such as $HOME/, would leave the reviewer the live folder and the findings in it.
if REPORTS in prompt.replace(reports, ""):
+10 -4
View File
@@ -218,13 +218,19 @@ The decision `worker: a chunk's worker writes the simplest change…` has the wo
Valid while the worker writes the tests that larv-review's reviewers hold to the principles.
## review: each reviewer under `agents/` writes its full report into the chunk's review folder under `~/.local/state/larv-review/` and returns the worker its verdict and one line per finding; rule-hook refuses any other file call from it
## review: each reviewer under `agents/` writes its full report into the chunk's review folder under `~/.local/state/larv-review/` and returns the worker its verdict and one line per finding; rule-hook refuses its Edit and MultiEdit, and any Write outside `~/.local/state/larv-review/`
2026-10-18, the agent, shipping lilleman's plan item. Serves goal 1.4: a report the worker does not need line by line no longer fills its context. Goal 1.1 holds because the worker reads a finding's full entry before it answers a 🔴 or 🟡.
2026-10-18, lilleman through todo item 73. Serves goal 1.4: a report the worker does not need line by line no longer fills its context. Goal 1.1 holds because the worker reads a finding's full entry before it answers a 🔴 or 🟡.
The worker names each report's file in the reviewer's prompt, per `skills/larv-review/SKILL.md` → "Reports", and `skills/larv-review/review-findings.md` → "Report" sets what the reviewer returns. Each reviewer holds Write for that. Claude Code passes a subagent's type to a PreToolUse hook as `agent_type`, so `bin/rule_hook/reviewer_report.py` refuses a reviewer's Edit, MultiEdit, and Write outside the folder; no marker overrides it. A reviewer's Bash, as stability-reviewer holds, is not confined. The folder is fixed, since loop-claude's headless sessions have no scratchpad. It sits outside every checkout, so no project sees a report. It survives a reboot, unlike `/tmp`, so a resumed chunk still reads its earlier rounds. It is in the user's home, so no other local user plants a symlink that widens the folder, and `larv-review review-folder`, which makes the folder, leaves `~/.local/state/larv-review` readable by the user alone, since a report may quote a secret. A chunk keeps its folder after the merge: `stability-replay` hands a replayed reviewer a copy of the reports written after its chunk began and before its round did, so the replay reads the earlier rounds its prompt names, never the findings it is to find, and leaves the chunk's reports as they were. Claude Code's own subagent prompt tells a subagent to return findings rather than write report files; `review-findings.md` → "Report" overrides that, since the file is the worker's input, and a prose-reviewer probed on 2026-10-18 wrote its file. A general-purpose wrapper that launches the reviewer was not tried: Claude Code's documentation says a subagent cannot start another.
Each reviewer holds Write for its report. Claude Code passes a subagent's type to a PreToolUse hook as `agent_type`. So `bin/rule_hook/reviewer_report.py` refuses a reviewer's Edit and MultiEdit, and any Write outside `~/.local/state/larv-review/`; no marker overrides it. A reviewer's Bash, as stability-reviewer holds, is not confined.
Before this change, reports took a median 19k tokens per chunk, 8% of the worker's peak context, and lines carrying a severity mark were 9–24% of a report (2026-10-08, over 68 archived transcripts). `stability-replay` still counts each 🔴 and 🟡 by its line in the reviewer's reply, now a one-line summary. todo.md item 186 measures what the worker reads of the reports instead.
The folder is fixed, since loop-claude's headless sessions have no scratchpad. It sits outside every checkout, so no project sees a report. It survives a reboot, unlike `/tmp`, so a resumed chunk still reads its earlier rounds. It is in the user's home, so no other local user plants a symlink that widens it. A report may quote a secret, so `larv-review review-folder`, which makes the chunk's folder, leaves `~/.local/state/larv-review` readable by the user alone.
A chunk keeps its folder after the merge. `stability-replay` hands a replayed reviewer a copy holding only the reports written after the chunk began and before the round did. So the replay reads the earlier rounds its prompt names, never the findings it is to find. The chunk's own reports stay as they were.
Claude Code's own subagent prompt tells a subagent to return findings rather than write report files. `review-findings.md` → "Report" overrides that, since the file is the worker's input; a prose-reviewer probed on 2026-10-18 wrote the file its prompt named. A general-purpose wrapper that launches the reviewer was not tried: Claude Code's documentation says a subagent cannot start another.
Before this change, reports took a median 19k tokens per chunk, 8% of the worker's peak context, and lines carrying a severity mark were 9–24% of a report (2026-10-08, over 68 archived transcripts). `stability-replay` still counts each 🔴 and 🟡 by its line in the reviewer's reply, now a one-line summary. todo.md item 186 is to measure what the worker reads of the reports instead.
Valid while Claude Code passes `agent_type` to hooks inside a subagent. Without it, the rule refuses nothing, and a reviewer may write anywhere.
+3 -3
View File
@@ -45,9 +45,9 @@ A comment is prose, not code. Passes run in this order: line-level polish on cod
Give a reviewer without Bash the branch diff and `git ls-files`'s output in its prompt: some harnesses grant it Read alone.
**Reports.** Run `~/.claude/bin/larv-review review-folder` in the chunk's worktree: it makes the chunk's review folder and prints its path. Keep the folder after the merge: `stability-replay` replays a round from the reports its prompt names. Name in each prompt to an agent under `~/.claude/agents/` the file there that its full report goes to: `<pass>-round-<n>.md`, with the yardstick's name after the pass's for a principles-auditor, and `-rerun` before `.md` for a relaunch one rung up. It writes the report there and returns only its verdict and one line per finding. Before you answer a 🔴 or 🟡, read its entry: Grep the report for the finding's place, with the lines after it, rather than Read the whole report. rule-hook refuses a reviewer's write anywhere else.
`~/.claude/bin/larv-review` holds this section's mechanical rules: the chunk's review folder, the round count, the paired ruling's base and vote count, the scoring run's trigger, and the history's format and latest places, and its count of how often seats agree. Run it in the chunk's worktree; `~/.claude/bin/larv-review --help` states each rule. On exit 1, repair what its message names and run it again; when you cannot, ask the user.
`~/.claude/bin/larv-review` holds this section's mechanical rules: the round count, the paired ruling's base and vote count, the scoring run's trigger, and the history's format and latest places, and its count of how often seats agree. Run it in the chunk's worktree; `~/.claude/bin/larv-review --help` states each rule. On exit 1, repair what its message names and run it again; when you cannot, ask the user.
**Reports.** Run `~/.claude/bin/larv-review review-folder` in the chunk's worktree: it makes the chunk's review folder and prints its path. In each prompt to an agent under `~/.claude/agents/`, name the file in that folder for its full report: `<pass>-round-<n>.md`. For a principles-auditor, use `principles-<yardstick>-round-<n>.md`. For a relaunch one rung up, add `-rerun` before `.md`. Before you answer a 🔴 or 🟡, read its entry: Grep the report for the finding's place, with the lines after it, rather than Read the whole report. rule-hook refuses a reviewer's Edit and MultiEdit, and any Write outside `~/.local/state/larv-review/`. Keep the folder after the merge: `stability-replay` replays a round from the reports its prompt names.
**Precedent, then ask** — for the architecture pass and the full scan:
@@ -80,7 +80,7 @@ Give a reviewer without Bash the branch diff and `git ls-files`'s output in its
**Rung up.** A reviewer rules the work below standard when its report holds systems-architect's BLOCK or a finding against `standards/quality.md`. A comprehension seat does when `record-ruling` counts one of its votes as worse.
- **Ask.** Such a reviewer or seat may end its report asking for a rerun one rung up. Relaunch it only on the rung loop-claude's prompt names for it; where the prompt names none, the report stands.
- **Relaunch.** Relaunch a reviewer on that rung with the same prompt, its report file renamed per "Reports", and the path of the report that asked; its report stands in place of that one, in the same round. Relaunch a seat with the same prompt alone; its line replaces the one that asked in the votes file, before `record-ruling` runs. A relaunch cannot ask again.
- **Relaunch.** Relaunch a reviewer on that rung with the same prompt, except that it names the `-rerun` report file per "Reports", plus the path of the report that asked; its report stands in place of that one, in the same round. Relaunch a seat with the same prompt alone; its line replaces the one that asked in the votes file, before `record-ruling` runs. A relaunch cannot ask again.
- **Escalate.** A below-standard ruling in the report that stands is escalation trigger 4 in `~/.claude/CLAUDE.md` → "Working with the codebase".
**Findings.** A reviewer rates each finding 🔴 must fix, 🟡 should fix, 🟢 nit, ❓ question, or 🔀 escalation naming the reviewer whose concern it is.
+13 -13
View File
@@ -2,7 +2,7 @@
Words: `~/.claude/CLAUDE.md` → "Vocabulary".
A reviewer reads and reports; it edits nothing. It writes no file but its report, apart from the scratch files a reviewer holding Bash makes through it. Read `docs/decisions.md` and `todo.md` first: a finding declined or disproved in `docs/decisions.md` or in a comment at the code it concerns, or filed in `todo.md`, is not raised again, unless the decline works against a goal or a technical principle and names no `todo.md` item ending it.
A reviewer reads and reports; it edits nothing. It writes no file but its report, except the scratch files that a reviewer holding Bash makes with Bash. Read `docs/decisions.md` and `todo.md` first: a finding declined or disproved in `docs/decisions.md` or in a comment at the code it concerns, or filed in `todo.md`, is not raised again, unless the decline works against a goal or a technical principle and names no `todo.md` item ending it.
## Severity
@@ -14,18 +14,6 @@ A reviewer reads and reports; it edits nothing. It writes no file but its report
A finding against a technical principle names it and the file under `~/.claude/principles/` it lives in. A finding against `~/.claude/skills/larv-review/standards/quality.md` names that file and the rule it breaks.
## Report
Write your full report with the Write tool to the file your prompt names. The file is the worker's input, which it searches for each finding's entry, so write it even where your harness says to return findings directly. It holds the verdict, then every finding with its place, its evidence and its fix, as your agent file shapes them. Then return only:
- the verdict line
- one line per finding: its severity mark, its place, what is wrong in one sentence, and the file it breaks where that is `standards/quality.md` or a file under `~/.claude/principles/`, or for a 🔀 the reviewer it names, such as ``🟡 `bin/rank_todo.py:311` `place`: a cycle among blockers recurses forever (technical-principles.md)``
- for stability-reviewer, whether the tests passed, and at which commit
- `Rerun one rung up`, where your report ends with it
- the report's path
A prompt that names no file, or a Write that fails, gets the full report as your reply.
## Verdict
A review's first line, derived from the findings:
@@ -38,6 +26,18 @@ A review's first line, derived from the findings:
Where your report holds a finding against `~/.claude/skills/larv-review/standards/quality.md`, or you are systems-architect and return BLOCK, you may end it with the line `Rerun one rung up` when you want a more capable reviewer to check that ruling.
## Report
Write your full report with the Write tool to the file your prompt names. The file is the worker's input, which it searches for each finding's entry, so write it even where your harness says to return findings directly. It holds the verdict, then every finding with its place, its evidence and its fix, as your agent file shapes them. Then return only:
- the verdict line
- one line per finding, in this order: its severity mark, its place, and what is wrong, in one sentence. Where the finding breaks `standards/quality.md` or a file under `~/.claude/principles/`, end the line with that file's name. For a 🔀, end it with the reviewer it names. Example: ``🟡 `bin/example.py:42` `parse`: an empty line raises IndexError (technical-principles.md)``
- for stability-reviewer, whether the tests passed, and at which commit
- `Rerun one rung up`, where your report ends with it
- the report's path
A prompt that names no file, or a Write that fails, gets the full report as your reply.
## Rounds
- Handed neither earlier findings nor another pass's fix: surface everything.