Answer principles round 1: 1 🔴, 7 🟡; sort the new imports, test a symlink in the reports folder, own the folder's path in review_folder.py and check SKILL.md names it, redirect stability-replay's reviewer to a copy of the chunk's folder and keep folders after the merge, keep the folder private, override the harness's no-report-files note, and state what a reviewer may write
This commit is contained in:
+1
-1
@@ -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 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.
|
||||
- `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.
|
||||
|
||||
@@ -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. 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 `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.
|
||||
- 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.
|
||||
|
||||
|
||||
@@ -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, 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. 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.
|
||||
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.
|
||||
|
||||
@@ -5,6 +5,7 @@ import unittest
|
||||
|
||||
sys.path.insert(0, str(pathlib.Path(__file__).resolve().parents[1]))
|
||||
|
||||
from review_folder import REPORTS
|
||||
from rule_hook.reviewer_rung import REVIEWERS, SEAT, SECURITY_OPENER
|
||||
from repo_checks.test_python_floor import ROOT
|
||||
|
||||
@@ -28,3 +29,6 @@ class ReviewerLaunches(unittest.TestCase):
|
||||
def test_the_security_opening_is_the_sentence_larv_review_has_the_security_pass_open_with(self):
|
||||
security = LARV_REVIEW.split("### Security", 1)[1].split("### Overrides", 1)[0]
|
||||
self.assertIn(SECURITY_OPENER, security)
|
||||
|
||||
def test_larv_review_names_the_reports_folder_rule_hook_lets_a_reviewer_write_into(self):
|
||||
self.assertIn(f"`~/{REPORTS}/<the worktree's path", LARV_REVIEW)
|
||||
|
||||
@@ -1,9 +1,10 @@
|
||||
"""Refuse a reviewer's file call other than a Write of its report into the reports folder: skills/larv-review/review-findings.md → "Report"."""
|
||||
import os
|
||||
|
||||
from rule_hook.rules import Breach
|
||||
from rule_hook.call import Call
|
||||
from review_folder import REPORTS
|
||||
from rule_hook.reviewer_rung import REVIEWERS
|
||||
from rule_hook.rules import Breach, REPORTS
|
||||
|
||||
|
||||
def report_breaches(call: Call, path: str, home: str) -> list[Breach]:
|
||||
|
||||
@@ -5,6 +5,7 @@ import typing
|
||||
|
||||
from git_command import commits
|
||||
from round_titles import lacks_counts
|
||||
from review_folder import REPORTS
|
||||
from shell_command import Simple
|
||||
|
||||
RuleName = typing.Literal["action-pin", "commit-one-line", "ignorefile-sorted", "image-pin", "no-ai-attribution", "reviewer-report", "reviewer-rung", "round-title-counts", "todo-rank-check"]
|
||||
@@ -18,8 +19,6 @@ class Rule:
|
||||
overridable: bool = True
|
||||
|
||||
|
||||
# The reviewers' reports folder, under the home folder: outside every checkout, so no project sees a report, and kept across a reboot, so a resumed chunk still reads its rounds. A fixed path, since a headless session has no scratchpad.
|
||||
REPORTS = ".local/state/larv-review"
|
||||
RULES: dict[RuleName, Rule] = {
|
||||
"action-pin": Rule(
|
||||
"a GitHub or Gitea Action is pinned to a semver tag, such as @v3 or @v3.1.2, never to a branch, and to a commit SHA only in a pipeline that tests our own specific builds",
|
||||
|
||||
@@ -241,7 +241,16 @@ class ReviewerReport(unittest.TestCase):
|
||||
|
||||
def test_a_reviewer_writes_its_report_into_the_reports_folder(self):
|
||||
self.assertEqual(self.breached("Write", "/h/.local/state/larv-review/.claude-item-73/prose-round-1.md"), [])
|
||||
self.assertEqual(self.breached("Write", "prose-round-1.md", cwd="/h/.local/state/larv-review/x"), [], "a relative path resolves against the call's cwd")
|
||||
|
||||
def test_a_relative_path_resolves_against_the_calls_cwd(self):
|
||||
self.assertEqual(self.breached("Write", "prose-round-1.md", cwd="/h/.local/state/larv-review/x"), [])
|
||||
|
||||
def test_a_symlink_in_the_reports_folder_is_followed_to_where_it_points(self):
|
||||
home = pathlib.Path(self.enterContext(tempfile.TemporaryDirectory()))
|
||||
(home / ".local" / "state" / "larv-review").mkdir(parents=True)
|
||||
(home / ".local" / "state" / "larv-review" / "out").symlink_to(home)
|
||||
found = breaches_of(Call("Write", {"file_path": f"{home}/.local/state/larv-review/out/a.md", "content": "x"}, "/r", "prose-reviewer"), str(home), {})
|
||||
self.assertEqual(rules(found[2]) if found else [], ["reviewer-report"])
|
||||
|
||||
def test_a_reviewer_writing_anywhere_else_is_refused(self):
|
||||
for path in ["/r/README.md", "/h/.local/state/larv-review", "/h/.local/state/larv-review-x/a.md", "/h/.local/state/larv-review/../a.md", "/tmp/larv-review/a.md"]:
|
||||
@@ -250,6 +259,8 @@ class ReviewerReport(unittest.TestCase):
|
||||
|
||||
def test_a_reviewer_edits_no_file_even_in_the_reports_folder(self):
|
||||
self.assertEqual(self.breached("Edit", "/h/.local/state/larv-review/x/prose-round-1.md"), ["reviewer-report"])
|
||||
|
||||
def test_a_reviewers_multiedit_is_refused(self):
|
||||
self.assertEqual(self.breached("MultiEdit", "/r/a.py", "stability-reviewer"), ["reviewer-report"])
|
||||
|
||||
def test_the_worker_and_other_subagents_write_anywhere(self):
|
||||
@@ -402,7 +413,7 @@ class Hook(unittest.TestCase):
|
||||
|
||||
def test_help_lists_every_rule(self):
|
||||
helped = subprocess.run([str(HOOK), "--help"], capture_output=True, check=True, env=isolated_env(), text=True).stdout
|
||||
for rule in ["action-pin", "commit-one-line", "ignorefile-sorted", "image-pin", "no-ai-attribution", "reviewer-report", "round-title-counts", "todo-rank-check"]:
|
||||
for rule in ["action-pin", "commit-one-line", "ignorefile-sorted", "image-pin", "no-ai-attribution", "reviewer-report", "reviewer-rung", "round-title-counts", "todo-rank-check"]:
|
||||
self.assertIn(f" {rule}\n The rule: ", helped)
|
||||
self.assertIn("reviewer-report\n The rule: a reviewer writes nothing but its report", helped)
|
||||
self.assertRegex(helped, r" reviewer-report\n( .*\n){2} Takes no override\.\n")
|
||||
|
||||
@@ -46,6 +46,7 @@ from failure import Failure
|
||||
from rung_replay.search import first_reply, replayed
|
||||
from claude_code.transcript import first_timestamped_line, read_transcript
|
||||
from claude_code.entries import parse_entry, structured_output
|
||||
from review_folder import REPORTS, review_folder
|
||||
from model_routing.ladder import Rung
|
||||
|
||||
TOOL = "stability-replay"
|
||||
@@ -80,7 +81,7 @@ def main(argv: list[str], env: typing.Mapping[str, str], home: pathlib.Path, eff
|
||||
return failed(TOOL, f"no archived stability round of projects on {anchor.model} in {archive_root(home, env)} holds a 🔴 or 🟡 on code it can find")
|
||||
chosen = sample(list(codes), LATEST)
|
||||
# The project's rung is the reference, so the candidates start below it.
|
||||
replay = replayed(chosen, anchor, down_from(anchor)[1:], lambda found, rung: findings_found(found, codes[found], rung, anchor, effects), lambda _, found: sorted(found), "stability rounds")
|
||||
replay = replayed(chosen, anchor, down_from(anchor)[1:], lambda found, rung: findings_found(found, codes[found], rung, anchor, home, effects), lambda _, found: sorted(found), "stability rounds")
|
||||
if isinstance(replay, Limited):
|
||||
return limited_exit(TOOL, replay)
|
||||
print(report(anchor.model, anchor, chosen, replay))
|
||||
@@ -147,9 +148,9 @@ def commit_log(listed: str) -> list[tuple[str, float]]:
|
||||
return [(commit, float(authored)) for commit, authored in (line.split() for line in listed.splitlines())]
|
||||
|
||||
|
||||
def findings_found(found: Round, code: Code, rung: Rung, anchor: Rung, effects: Effects) -> set[int] | Limited:
|
||||
def findings_found(found: Round, code: Code, rung: Rung, anchor: Rung, home: pathlib.Path, effects: Effects) -> set[int] | Limited:
|
||||
"""The indexes of the round's findings that its replay on rung reports, as the reviewer on anchor matches them."""
|
||||
reviewed: str | Failure | Limited = first_reply(lambda: review(found, code, rung, effects))
|
||||
reviewed: str | Failure | Limited = first_reply(lambda: review(found, code, rung, home, effects))
|
||||
if isinstance(reviewed, Limited):
|
||||
return reviewed
|
||||
matched: set[int] | Failure | Limited = reviewed if isinstance(reviewed, Failure) else first_reply(lambda: match(found.findings, reviewed, found.root, anchor, effects))
|
||||
@@ -160,8 +161,15 @@ def findings_found(found: Round, code: Code, rung: Rung, anchor: Rung, effects:
|
||||
|
||||
|
||||
# The shell makes and removes the clone itself, and is tested on a temporary home as judge-replay's is; rounds.py's core takes the filesystem as an argument.
|
||||
def review(found: Round, code: Code, rung: Rung, effects: Effects) -> str | Failure | Limited:
|
||||
def review(found: Round, code: Code, rung: Rung, home: pathlib.Path, effects: Effects) -> str | Failure | Limited:
|
||||
clone = tempfile.mkdtemp(prefix="stability-replay-")
|
||||
# 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.
|
||||
folder = pathlib.Path(review_folder(str(home), code.path))
|
||||
(home / REPORTS).mkdir(mode=0o700, parents=True, exist_ok=True)
|
||||
reports = tempfile.mkdtemp(prefix="stability-replay-", dir=home / REPORTS)
|
||||
if folder.is_dir():
|
||||
shutil.copytree(folder, reports, dirs_exist_ok=True)
|
||||
prompt = found.prompt.replace(str(folder), reports).replace(f"~/{folder.relative_to(home)}", reports).replace(code.path, clone)
|
||||
try:
|
||||
for command in (
|
||||
("clone", "--quiet", "--shared", "--no-checkout", found.root, clone),
|
||||
@@ -172,12 +180,13 @@ def review(found: Round, code: Code, rung: Rung, effects: Effects) -> str | Fail
|
||||
if isinstance(ran := git(effects, found.root, *command), Failure):
|
||||
return ran
|
||||
args = ["--agent", REVIEWER, *rung.flags()]
|
||||
reply = claude_reply(effects.claude, args, clone, found.prompt.replace(code.path, clone), "claude")
|
||||
reply = claude_reply(effects.claude, args, clone, prompt, "claude")
|
||||
if isinstance(reply, Failure | Limited):
|
||||
return reply
|
||||
return reply["result"] if isinstance(reply.get("result"), str) else Failure("the reviewer replied with no report")
|
||||
finally:
|
||||
shutil.rmtree(clone, ignore_errors=True)
|
||||
shutil.rmtree(reports, ignore_errors=True)
|
||||
|
||||
|
||||
def match(findings: tuple[str, ...], replay_report: str, root: str, rung: Rung, effects: Effects) -> set[int] | Failure | Limited:
|
||||
|
||||
@@ -232,6 +232,28 @@ class Main(unittest.TestCase):
|
||||
self.assertIn(f" {self.checkout} 2026-10-14T10:00:00Z: 🟡 slow", out)
|
||||
self.assertTrue(out.endswith("finds: claude-sonnet-5-5 at high effort\n"))
|
||||
|
||||
def test_points_the_prompts_review_folder_at_a_copy_that_it_removes(self):
|
||||
folder = self.home / ".local" / "state" / "larv-review" / "code" / "proj-x"
|
||||
folder.mkdir(parents=True)
|
||||
(folder / "stability-round-1.md").write_text("round 1\n")
|
||||
self.set_prompt(f"Review branch x in {self.home}/code/proj-x. Write your report to ~/.local/state/larv-review/code/proj-x/stability-round-2.md; the last round's is ~/.local/state/larv-review/code/proj-x/stability-round-1.md.")
|
||||
seen = []
|
||||
|
||||
def review(rung):
|
||||
named = pathlib.Path(re.search(r"report to (\S+)/stability-round-2\.md", self.reviews[-1][4]).group(1))
|
||||
seen.append((named, (named / "stability-round-1.md").read_text()))
|
||||
(named / "stability-round-2.md").write_text("replayed\n")
|
||||
return {"type": "result", "result": f"review on {rung.model} {rung.effort}"}
|
||||
|
||||
code, _, err = self.run_main(["claude-opus-5-5"], lambda rung: {"found": [0, 1]}, review)
|
||||
self.assertEqual(code, 0, err)
|
||||
named, earlier = seen[0]
|
||||
self.assertEqual(named.parent, folder.parents[1], "the copy sits in the reports folder, where rule-hook lets the reviewer write")
|
||||
self.assertNotEqual(named, folder)
|
||||
self.assertEqual(earlier, "round 1\n")
|
||||
self.assertFalse(named.exists())
|
||||
self.assertEqual(sorted(path.name for path in folder.iterdir()), ["stability-round-1.md"])
|
||||
|
||||
def test_replays_the_rounds_of_every_chunk(self):
|
||||
self.write_chunk("proj", "c2", "2026-10-14T10:30:00Z")
|
||||
code, out, err = self.run_main(["claude-opus-5-5"], lambda rung: {"found": [0, 1]})
|
||||
|
||||
@@ -0,0 +1,16 @@
|
||||
import pathlib
|
||||
import sys
|
||||
import unittest
|
||||
|
||||
sys.path.insert(0, str(pathlib.Path(__file__).resolve().parent))
|
||||
|
||||
from review_folder import review_folder
|
||||
|
||||
|
||||
class ReviewFolder(unittest.TestCase):
|
||||
def test_keys_a_worktree_under_home_by_its_path_relative_to_home(self):
|
||||
self.assertEqual(review_folder("/h", "/h/code/proj-item-3"), "/h/.local/state/larv-review/code/proj-item-3")
|
||||
|
||||
def test_keys_a_worktree_outside_home_by_its_path_relative_to_the_root(self):
|
||||
self.assertEqual(review_folder("/h", "/srv/proj-item-3"), "/h/.local/state/larv-review/srv/proj-item-3")
|
||||
self.assertEqual(review_folder("/h", "/hx/proj"), "/h/.local/state/larv-review/hx/proj", "a sibling of home that shares its prefix is outside it")
|
||||
+3
-3
@@ -222,11 +222,11 @@ Valid while the worker writes the tests that larv-review's reviewers hold to the
|
||||
|
||||
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 🟡.
|
||||
|
||||
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. And it is in the user's home, so no other local user reads a report, which may quote a secret, or plants a symlink that widens the folder. A general-purpose wrapper that launches the reviewer was not tried: Claude Code's documentation says a subagent cannot start another.
|
||||
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 the worker makes `~/.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 it, so the replay reads the earlier rounds its prompt names 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.
|
||||
|
||||
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.
|
||||
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.
|
||||
|
||||
Valid while Claude Code passes `agent_type` to hooks inside a subagent.
|
||||
Valid while Claude Code passes `agent_type` to hooks inside a subagent. Without it, the rule refuses nothing, and a reviewer may write anywhere.
|
||||
|
||||
## 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
|
||||
|
||||
|
||||
@@ -45,7 +45,7 @@ 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.** The chunk's review folder is `~/.local/state/larv-review/<the worktree's path relative to ~, or to / outside it>/`. 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.
|
||||
**Reports.** The chunk's review folder is `~/.local/state/larv-review/<the worktree's path relative to ~, or to / outside it>/`. Make it, and keep `~/.local/state/larv-review` readable by you alone: `mkdir -p <folder> && chmod 700 ~/.local/state/larv-review`. Keep it 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 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.
|
||||
|
||||
@@ -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 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, 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.
|
||||
- **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.
|
||||
@@ -163,7 +163,7 @@ Launch prose-reviewer with what the diff touched and every section this review c
|
||||
1. Read the finished PR against the README goals: does anything in it work against one? It breaks a maintain goal → do not merge; redesign the change or drop its item. It works against an achieve goal → do not merge; ask the human, stating the conflict.
|
||||
2. Run the comprehension check (§3) where it runs; it runs once. When `origin/<default branch>` moves after that, return to §4, and keep the ruling and scoring run already recorded.
|
||||
3. Aligned, every pass done and everything green → **merge**. Follow the repo's merge method (`AGENTS.md`; ff-only where that is the convention). A repo withholds this in its `AGENTS.md` → leave the PR ready and unmerged, and say which line withheld it.
|
||||
4. Merged → remove the chunk's items from `todo.md` per `~/.claude/CLAUDE.md` → "Working loop", and the chunk's review folder.
|
||||
4. Merged → remove the chunk's items from `todo.md` per `~/.claude/CLAUDE.md` → "Working loop".
|
||||
5. Stop. The next chunk gets a fresh session.
|
||||
|
||||
## 6. Wrap up
|
||||
|
||||
@@ -2,7 +2,7 @@
|
||||
|
||||
Words: `~/.claude/CLAUDE.md` → "Vocabulary".
|
||||
|
||||
A reviewer reads and reports; it edits nothing, and writes only its report. 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, 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.
|
||||
|
||||
## Severity
|
||||
|
||||
@@ -16,7 +16,7 @@ A finding against a technical principle names it and the file under `~/.claude/p
|
||||
|
||||
## Report
|
||||
|
||||
Write your full report with the Write tool to the file your prompt names: the verdict, then every finding with its place, its evidence and its fix, as your agent file shapes them. Then return only:
|
||||
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)`
|
||||
|
||||
Reference in New Issue
Block a user