Merge remote-tracking branch 'origin/main' into item-387

This commit is contained in:
2026-11-17 08:55:05 +01:00
18 changed files with 248 additions and 37 deletions
+1
View File
@@ -2,6 +2,7 @@
## Unreleased
- Add `larv-review round-title <pass>`, which prints a review round commit's title prefix with the 🔴, 🟡 and misread counts taken from the round's report. rule-hook refuses a round commit whose counts differ from that report, where the report exists and can be counted; a report must head each finding `### 🔴` or `### 🟡`, optionally followed by ` [misread]`.
- Add `workflow-bench/handoff_bench.py`, a bench of how a worker's step to a stronger model hands over the chunk, on six archived L 3 chunks. Sonnet 5.5 left five unfinished at its budget. On those, Opus 5.5 resuming Sonnet 5.5's session passed two and was partial on three, for a mean $0.68; a fresh session with a brief passed one and was partial on four, for $0.78. So a stepped worker still resumes its session.
- todo-item edit --blocked-by sets the "is blocked by" links of a Jira issue the loop filed.
- A `Touches:` list in the description of a Jira issue is read as one in `todo.md` is, a path or name that holds a backtick included: the Jira description spells it in backticks with no padding spaces, and the prediction reader takes that spelling too.
+1 -1
View File
@@ -182,7 +182,7 @@ Install puts only `loop-claude` on `PATH`; call the others by their path, such a
- `compress-archives` gzips each transcript in loop-claude's archive and each file in the review folders 30 days after it last changed, keeping all of them; Install's crontab line runs it daily.
- `deploy-release [--cut] [<checkout>]` moves `~/.claude`, or the checkout named, to the newest release, as Update says; with `--cut`, run in the development clone, it first cuts the next release, as Release says.
- `judge-replay <model>` replays loop-claude's judge on archived verdicts of the projects run on the model, and prints what each rung a review climbs to misses, and the lowest rung below them that, like each candidate above it, returns them; `judge-replay --help` states the replay.
- `larv-review <command>` holds larv-review's mechanical rules: the chunk's review folder, the paired ruling's base and vote count, each pass's round count, the scoring run's trigger and setup; the comprehension history's format, its latest places and its count of how often seats agree; and each reviewer's prompt header. `larv-review --help` states them. `settings.json` → `hooks` runs `larv-review reviewer-context` as each subagent starts. A reviewer under `agents/` whose frontmatter has `omitClaudeMd: true` starts without `CLAUDE.md`, and the command hands it that file's "Shared goal", "Prose" and "Vocabulary" sections.
- `larv-review <command>` holds larv-review's mechanical rules: the chunk's review folder, the paired ruling's base and vote count, each pass's round count and the opening of its round commit's title, the scoring run's trigger and setup; the comprehension history's format, its latest places and its count of how often seats agree; and each reviewer's prompt header. `larv-review --help` states them. `settings.json` → `hooks` runs `larv-review reviewer-context` as each subagent starts. A reviewer under `agents/` whose frontmatter has `omitClaudeMd: true` starts without `CLAUDE.md`, and the command hands it that file's "Shared goal", "Prose" and "Vocabulary" sections.
- `loop-claude <task>` runs a project's next chunks, each in its own tmux window, cycle after cycle; `loop-claude --help` states its contract.
- `metric-bench [history]` benches cheap static metrics of a project's Python against the places its comprehension history names as hardest; `metric-bench --help` states the metrics and the scores.
- `mutate-changes [--base <ref>] [--prefix <shell text>] [--jobs <n>]` mutation-tests the lines a branch changes and prints each mutant its tests don't kill; `mutate-changes --help` says which tool it runs for each language.
+1 -1
View File
@@ -12,4 +12,4 @@ Verdict, severities and rounds: ~/.claude/skills/larv-review/review-findings.md.
- Per principle or goal: every place the project departs from it, with file:line, the defect in one sentence and its concrete consequence. Then one line: followed, mostly, not followed, or does not apply and why.
- A departure a plan item plans away is named with that item, not raised.
- A decision in `docs/decisions.md` working against a goal or a technical principle is a 🔴 on the decision, unless it names the plan item that ends it. Weigh it hard: that it was decided is no reason.
- Report under one heading per yardstick.
- Report under one `##` heading per yardstick.
+14 -3
View File
@@ -1,4 +1,4 @@
"""Hold larv-review's mechanical rules: the chunk's review folder, the paired ruling's base and vote count, each pass's rounds, the scoring run's trigger and setup; the comprehension history's format, its latest places and its count of how often seats agree; and the header of each reviewer's prompt.
"""Hold larv-review's mechanical rules: the chunk's review folder, the paired ruling's base and vote count, each pass's rounds and its round commit's title, the scoring run's trigger and setup; the comprehension history's format, its latest places and its count of how often seats agree; and the header of each reviewer's prompt.
usage: larv-review {commands}
@@ -10,8 +10,8 @@ to 10. Each seat names the places it found hard.
Run it inside a project checkout or one of its worktrees. Each command but review-folder,
record-ruling, places and agreement first fetches origin, when the checkout has that remote, and
takes origin's default branch, or else the local main or master, as the default branch. When the
fetch fails, round-count and reviewer-header read origin as last fetched and say so on stderr; the
other four exit 1.
fetch fails, round-count, reviewer-header and round-title read origin as last fetched and say so on
stderr; the other four exit 1.
The history is docs/comprehension-history.md in the checkout.
review-folder makes the chunk's review folder, where each reviewer writes its report, and prints its
@@ -142,6 +142,15 @@ it. It exits 1 when the pass takes no more rounds, when `project-config` fails i
the principles or standards folder is not a folder with a file in it, or, with --rerun, when the
report that asked is missing.
round-title takes a pass as reviewer-header does. It prints how the commit that answers the pass's
unanswered round opens its title, after any prefix the project's commit-title template adds, up to
and including the `;` before the summary, such as `Answer prose round 1: 0 🔴, 2 🟡 (0 misread);`. It
counts the findings in the round's report in the review folder, or in its rerun's where there is
one: each line that opens `### 🔴` or `### 🟡`, and of them each whose mark is followed by
`[misread]`. rule-hook's round-title-counts refuses a round title whose counts differ from that
report's. It exits 1 when the pass takes no more rounds, or the report is missing, unreadable or
says BLOCK without such a line.
reviewer-context is the SubagentStart hook. It reads the hook's input on stdin. For a reviewer
whose definition under ~/.claude/agents/ has `omitClaudeMd: true`, and so starts without CLAUDE.md,
it prints the hook reply that hands the agent the Shared goal, Prose and Vocabulary sections of
@@ -176,6 +185,7 @@ from larv_review.plan import plan_reasons
from larv_review.scoring_setup import prepare_scoring
from larv_review.history_commands import read_agreement, read_places, record_ruling, record_scoring
from larv_review.reviewer_header import reviewer_header
from larv_review.round_title import round_title
from project_config.main import title_templates
@@ -231,6 +241,7 @@ COMMANDS = {
"places": Command("places", no_arguments, lambda given: printed(read_places(pathlib.Path.home()))),
"agreement": Command("agreement", no_arguments, lambda given: printed(read_agreement(pathlib.Path.home()))),
"reviewer-header": Command("reviewer-header <pass> [--rerun]", fits_reviewer_header, run_reviewer_header),
"round-title": Command("round-title <pass>", lambda given: len(given) == 1 and given[0] in REVIEWERS, lambda given: with_default_branch(lambda default: printed(round_title(default, given[0], pathlib.Path.home())), stale_ok=True)),
"reviewer-context": Command("reviewer-context", no_arguments, lambda given: printed(hook_reply(sys.stdin.read(), pathlib.Path.home()))),
}
SHAPES = " | ".join(command.shape for command in COMMANDS.values())
+3 -3
View File
@@ -9,7 +9,7 @@ from forge.commands import forge_of, runner
from record_store.stores import goals_store, local_file, store
from larv_review.history_commands import history_file, places_report
from project_config.main import located, title_templates
from review_rules.review_folder import made_review_folder
from review_rules.review_folder import made_review_folder, rerun_report, round_report
from forge.pulls import open_pull
from larv_review.plan_listing import plan_listing
from plan_store.stores import store as plan_store
@@ -47,11 +47,11 @@ class Launch:
def asked(self) -> pathlib.Path:
"""The round's report, which asks for the rerun where there is one."""
return self.folder / f"{self.pass_}-round-{self.round_}.md"
return round_report(self.folder, self.pass_, self.round_)
def header(self) -> str:
asked = self.asked()
report = f"{asked.with_name(asked.stem + '-rerun.md')}, in place of {asked}, which asked for this rerun" if self.rerun else str(asked)
report = f"{rerun_report(asked)}, in place of {asked}, which asked for this rerun" if self.rerun else str(asked)
return "\n".join([
f"Pass: {self.pass_}, round {self.round_}.",
f"PR: {self.pull}.",
+27
View File
@@ -0,0 +1,27 @@
"""round-title: print the opening of a round commit's title, counted from the round's report."""
import pathlib
from git_cli.git_repo import branch_titles, top
from failure import Failure
from review_rules.review_folder import findings_in, review_folder, standing_report
from review_rules.round_titles import round_prefix
from project_config.main import title_templates
from larv_review.reviewer_header import unanswered_round
def round_title(default: str, pass_: str, home: pathlib.Path) -> str | Failure:
"""The title prefix of pass_'s unanswered round, counted from that round's report in the chunk's review folder."""
titles = branch_titles(default)
if isinstance(titles, Failure):
return titles
templates = title_templates(None, home)
if isinstance(templates, Failure):
return templates
round_ = unanswered_round([templates.summary(title) for title in titles], pass_)
if isinstance(round_, Failure):
return round_
worktree = top()
if isinstance(worktree, Failure):
return worktree
findings = findings_in(standing_report(pathlib.Path(review_folder(str(home), worktree)), pass_, round_))
return findings if isinstance(findings, Failure) else round_prefix(pass_, round_, findings)
+17 -1
View File
@@ -1093,7 +1093,7 @@ class LarvReviewTool(unittest.TestCase):
def test_help_and_the_usage_line_list_the_same_commands(self):
usage = next(line for line in self.run_tool("--help").stdout.splitlines() if line.startswith("usage: larv-review "))
listed = usage.removeprefix("usage: larv-review ").split(" | ")
self.assertEqual([shape.split()[0] for shape in listed], ["review-folder", "ruling-base", "round-count", "needs-scoring-run", "scoring-run-owed", "record-ruling", "prepare-scoring", "record-scoring", "places", "agreement", "reviewer-header", "reviewer-context"])
self.assertEqual([shape.split()[0] for shape in listed], ["review-folder", "ruling-base", "round-count", "needs-scoring-run", "scoring-run-owed", "record-ruling", "prepare-scoring", "record-scoring", "places", "agreement", "reviewer-header", "round-title", "reviewer-context"])
self.assertIn(f"usage: larv-review {' | '.join(listed)}", self.run_tool().stderr)
def test_takes_a_local_main_without_origin_and_reads_origin_as_last_fetched_when_the_fetch_fails(self):
@@ -1173,6 +1173,22 @@ class LarvReviewTool(unittest.TestCase):
self.assertIn(f"Report: write it to {folder}/prose-round-2-rerun.md, in place of {folder}/prose-round-2.md, which asked for this rerun.", lines)
self.assertFalse(any(line.startswith("Places:") for line in lines), "only architecture and stability take the places")
def test_round_title_counts_the_unanswered_rounds_report_and_names_one_that_is_missing(self):
folder = self.checkout.parent / ".local" / "state" / "larv-review" / "proj"
folder.mkdir(parents=True)
(folder / "prose-round-1.md").write_text("BLOCK\n\n### 🔴 [misread] `a.md:1`: wrong\n\n### 🟡 `b.md:2`: worse\n\n### 🟢 `c.md:3`: nit\n")
ran = self.run_tool("round-title", "prose")
self.assertEqual((ran.returncode, ran.stdout, ran.stderr), (0, "Answer prose round 1: 1 🔴, 1 🟡 (1 misread);\n", ""))
self.commit("Answer prose round 1: 1 🔴, 1 🟡 (1 misread); fix")
missing = self.run_tool("round-title", "prose")
self.assertEqual((missing.returncode, missing.stdout), (1, ""))
self.assertIn(f"no report at {folder}/prose-round-2.md", missing.stderr)
(folder / "prose-round-2.md").write_text("BLOCK\n\n### 🟡 a\n\nRerun one rung up\n")
(folder / "prose-round-2-rerun.md").write_text("APPROVE\n")
self.assertEqual(self.run_tool("round-title", "prose").stdout, "Answer prose round 2: 0 🔴, 0 🟡 (0 misread);\n", "the rerun's report stands in place of the one that asked")
for given in (["security"], ["Prose"], ["prose", "2"], []):
self.assertEqual(self.run_tool("round-title", *given).returncode, 1, given)
def test_reviewer_header_refuses_a_pass_at_its_cap_and_a_pass_no_agent_reviews(self):
self.commit("Answer stability round 1: a")
self.commit("Answer stability round 2: b")
+33
View File
@@ -3,6 +3,7 @@ import os
import pathlib
from failure import Failure
from review_rules.round_titles import Findings, reported
# 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"
@@ -24,3 +25,35 @@ def made_review_folder(worktree: str, home: pathlib.Path) -> pathlib.Path | Fail
except OSError as failure:
return Failure(f"could not make the review folder {folder}: {failure}")
return folder
def round_report(folder: pathlib.Path, pass_: str, round_: int) -> pathlib.Path:
"""The report of pass_'s round round_ in the review folder, which asks for the rerun one rung up where there is one."""
return folder / f"{pass_}-round-{round_}.md"
def rerun_report(asked: pathlib.Path) -> pathlib.Path:
"""The report of the rerun one rung up that `asked` asks for. It stands in place of `asked`."""
return asked.with_name(asked.stem + "-rerun.md")
def standing_report(folder: pathlib.Path, pass_: str, round_: int) -> pathlib.Path:
"""The report that stands for pass_'s round round_ in the review folder: the rerun's where there is one, else the round's."""
asked = round_report(folder, pass_, round_)
return rerun_report(asked) if rerun_report(asked).exists() else asked
def findings_in(report: pathlib.Path) -> Findings | Failure:
"""The findings a round's report gives, as round_titles.reported counts them; a Failure where the report blocks yet heads no finding as review-findings.md → "Report" asks, since its count would then be wrong."""
try:
text = report.read_text(encoding="utf-8")
except FileNotFoundError:
return Failure(f"no report at {report}")
except (OSError, UnicodeDecodeError) as failure:
return Failure(f"could not read {report}: {failure}")
findings = reported(text)
if isinstance(findings, Failure):
return Failure(f"{report} cannot be counted: {findings.reason}; count its findings by hand")
if text.lstrip().startswith("BLOCK") and findings.red + findings.yellow == 0:
return Failure(f"{report} says BLOCK but opens no finding with `### 🔴` or `### 🟡`; count its findings by hand")
return findings
+20 -1
View File
@@ -1,7 +1,8 @@
"""The titles of larv-review's round commits, `Answer <pass> round <n>: <k> 🔴, <m> 🟡 (<j> misread); <summary>`: each pass's round count against its cap, and the findings the rounds reported. <j> counts the 🔴 and 🟡 findings a reviewer marked `[misread]`."""
"""The titles of larv-review's round commits, `Answer <pass> round <n>: <k> 🔴, <m> 🟡 (<j> misread); <summary>`: each pass's round count against its cap, and the findings each round reported, as its title counts them and as its report does. <j> counts the 🔴 and 🟡 findings a reviewer marked `[misread]`."""
import dataclasses
import re
from failure import Failure
from review_rules.review_passes import PASSES
# The most rounds a pass takes per chunk, per `docs/decisions.md` → `review: a pass gets at most two rounds per chunk, …`. rule-hook's `round-cap` refuses a round commit that `past_cap` finds takes its pass past it, and `larv-review round-count` marks a pass that reached it.
@@ -16,6 +17,9 @@ EXAMPLE = "Answer stability round 1: 1 🔴, 2 🟡 (1 misread); flag a deleted
ROUND = re.compile(r"^Answer (.+?) round ([0-9]+):", re.IGNORECASE)
# What follows a round title's colon: the round's 🔴 and 🟡 counts, then how many of them a reviewer marked `[misread]`, a count that titles from before it lack, then `;` and its summary, if any.
FINDINGS = re.compile(r" ([0-9]+) 🔴, ([0-9]+) 🟡(?: \(([0-9]+) misread\))?(?:;|$)")
# A 🔴 or 🟡 finding's heading in a round's report, as skills/larv-review/review-findings.md → "Report" pins it: `### `, the severity mark, then ` [misread]` where the reviewer marked it so.
FINDING = re.compile(r"^### (🔴|🟡)( \[misread\])?", re.MULTILINE)
HEADING = re.compile(r"^#{1,6} .*$", re.MULTILINE)
@dataclasses.dataclass(frozen=True)
@@ -93,3 +97,18 @@ def round_findings(titles: list[str]) -> Findings | None:
return None
misreads = [found.misread for found in counts if found.misread is not None]
return Findings(sum(found.red for found in counts), sum(found.yellow for found in counts), sum(misreads) if len(misreads) == len(counts) else None)
def reported(report: str) -> Findings | Failure:
"""The 🔴 and 🟡 findings a round's report gives in FINDING headings, and how many of them the reviewer marked `[misread]`; a Failure naming a heading that holds a 🔴 or 🟡 in another form, which a count would miss."""
for heading in HEADING.findall(report):
pinned = FINDING.match(heading)
if ("🔴" in heading or "🟡" in heading) and (not pinned or "[misread]" in heading and not pinned.group(2)):
return Failure(f"its heading `{heading}` holds a 🔴 or 🟡 but doesn't open `### 🔴` or `### 🟡`, followed by ` [misread]` where marked so")
marks = FINDING.findall(report)
return Findings(sum(mark == "🔴" for mark, _ in marks), sum(mark == "🟡" for mark, _ in marks), sum(bool(misread) for _, misread in marks))
def round_prefix(pass_: str, round_: int, findings: Findings) -> str:
"""The opening of the round's commit title, up to and including the `;` before its summary."""
return f"Answer {pass_} round {round_}: {findings.red} 🔴, {findings.yellow} 🟡 ({findings.misread} misread);"
+46 -1
View File
@@ -1,10 +1,13 @@
import pathlib
import sys
import tempfile
import unittest
sys.path.insert(0, str(pathlib.Path(__file__).resolve().parents[1]))
from review_rules.review_folder import review_folder
from failure import Failure
from review_rules.round_titles import Findings
from review_rules.review_folder import findings_in, review_folder, standing_report
class ReviewFolder(unittest.TestCase):
@@ -14,3 +17,45 @@ class ReviewFolder(unittest.TestCase):
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")
class RoundReport(unittest.TestCase):
def test_counts_the_rounds_report_or_its_rerun_one_rung_up_where_there_is_one(self):
with tempfile.TemporaryDirectory() as temp:
folder = pathlib.Path(temp)
(folder / "prose-round-1.md").write_text("BLOCK\n\n### 🟡 a\n")
self.assertEqual(findings_in(standing_report(folder, "prose", 1)), Findings(0, 1, 0))
(folder / "prose-round-1-rerun.md").write_text("BLOCK\n\n### 🔴 [misread] a\n")
self.assertEqual(findings_in(standing_report(folder, "prose", 1)), Findings(1, 0, 1))
(folder / "prose-round-1-rerun.md").write_text("BLOCK\n\n### 🔴 a\n\n### 🟡 b\n")
self.assertEqual(findings_in(standing_report(folder, "prose", 1)), Findings(1, 1, 0))
def test_names_a_missing_report(self):
with tempfile.TemporaryDirectory() as temp:
missing = findings_in(standing_report(pathlib.Path(temp), "prose", 2))
self.assertIsInstance(missing, Failure)
self.assertEqual(missing.reason, f"no report at {temp}/prose-round-2.md")
def test_names_a_report_it_cannot_read(self):
with tempfile.TemporaryDirectory() as temp:
(pathlib.Path(temp) / "prose-round-1.md").mkdir()
unread = findings_in(standing_report(pathlib.Path(temp), "prose", 1))
self.assertIsInstance(unread, Failure)
self.assertTrue(unread.reason.startswith(f"could not read {temp}/prose-round-1.md: "), unread.reason)
def test_names_a_blocking_report_that_heads_no_finding_as_its_format_asks(self):
with tempfile.TemporaryDirectory() as temp:
(pathlib.Path(temp) / "prose-round-1.md").write_text("\nBLOCK\n\n- 🟡 `a.md:1`: worse\n")
unread = findings_in(standing_report(pathlib.Path(temp), "prose", 1))
self.assertIsInstance(unread, Failure)
self.assertEqual(unread.reason, f"{temp}/prose-round-1.md says BLOCK but opens no finding with `### 🔴` or `### 🟡`; count its findings by hand")
(pathlib.Path(temp) / "prose-round-1.md").write_text("APPROVE\n")
self.assertEqual(findings_in(standing_report(pathlib.Path(temp), "prose", 1)), Findings(0, 0, 0))
def test_names_a_report_whose_headings_it_cannot_count(self):
with tempfile.TemporaryDirectory() as temp:
(pathlib.Path(temp) / "prose-round-1.md").write_text("BLOCK\n\n### 1. 🟡 `a.md:1`: worse\n")
unread = findings_in(standing_report(pathlib.Path(temp), "prose", 1))
self.assertIsInstance(unread, Failure)
self.assertTrue(unread.reason.startswith(f"{temp}/prose-round-1.md cannot be counted: its heading `### 1. 🟡"), unread.reason)
self.assertTrue(unread.reason.endswith("; count its findings by hand"), unread.reason)
+23 -1
View File
@@ -4,7 +4,8 @@ import unittest
sys.path.insert(0, str(pathlib.Path(__file__).resolve().parents[1]))
from review_rules.round_titles import Findings, lacks_counts, past_cap, round_counts, round_findings, rounds_past_first
from failure import Failure
from review_rules.round_titles import Findings, lacks_counts, past_cap, reported, round_counts, round_findings, round_prefix, rounds_past_first, title_counts
class Rounds(unittest.TestCase):
@@ -79,5 +80,26 @@ class RoundFindings(unittest.TestCase):
self.assertIsNone(round_findings(["Answer stability round 1: 1 🔴, 2 🟡 (4 misread); fix"]))
class Reported(unittest.TestCase):
REPORT = "BLOCK\n\n### 🔴 [misread] `a.py:1` `f`: wrong\n\n### 🟡 `b.py:2`: worse\n\n### 🟡 [misread] `c.py:3`: worse\n\n### 🟢 `d.py:4`: nit\n\n### ❓ `e.py:5`: why\n\n- 🔴 `a.py:1` `f`: wrong, as the reply lists it\nText naming 🔴 and [misread].\n"
def test_counts_the_findings_whose_heading_opens_with_their_mark(self):
self.assertEqual(reported(self.REPORT), Findings(1, 2, 2))
def test_counts_none_in_a_report_without_findings(self):
self.assertEqual(reported("APPROVE\n\nNothing found.\n"), Findings(0, 0, 0))
def test_spells_the_title_prefix_a_round_commit_opens_with(self):
self.assertEqual(round_prefix("prose", 2, Findings(1, 2, 0)), "Answer prose round 2: 1 🔴, 2 🟡 (0 misread);")
self.assertEqual(title_counts(round_prefix("prose", 2, Findings(1, 2, 1))), Findings(1, 2, 1), "the prefix parses as the counts it spells")
def test_counts_none_of_a_report_whose_headings_hold_a_mark_in_another_form(self):
for heading in ["### 1. 🟡 `a.py:1`: worse", "## 🔴 Must fix", "#### 🟡 a sub-heading", "### 🟡 `a.py:1`: worse [misread]"]:
with self.subTest(heading):
unread = reported(f"BLOCK\n\n### 🔴 `b.py:2`: wrong\n\n{heading}\n")
self.assertIsInstance(unread, Failure)
self.assertEqual(unread.reason, f"its heading `{heading}` holds a 🔴 or 🟡 but doesn't open `### 🔴` or `### 🟡`, followed by ` [misread]` where marked so")
if __name__ == "__main__":
unittest.main()
+2 -1
View File
@@ -57,6 +57,7 @@ from rule_hook.repeat_read import read_breaches
from rule_hook.reviewer_report import report_breaches
from rule_hook.reviewer_rung import reviewer_breaches, skill_breaches
from rule_hook.round_cap import round_cap_breaches
from rule_hook.round_report import round_report_breaches
from command_lines.shell_command import simple_commands
from project_config import templates
from rule_hook.todo_check import todo_breaches
@@ -142,7 +143,7 @@ def commit_breaches(commit: CommitCall, home: pathlib.Path) -> list[Breach]:
titles = config.titles if isinstance(config, ProjectConfig) else templates.BARE
# A checkout no config names has no branch template, so no title of its must fit one.
branch = checkout_branch(commit.directory) if isinstance(config, ProjectConfig) else None
return unread + title_breaches(commit, titles, config.branch if isinstance(config, ProjectConfig) else templates.BRANCH, branch) + round_cap_breaches(commit, titles) + todo_breaches(commit.directory, home)
return unread + title_breaches(commit, titles, config.branch if isinstance(config, ProjectConfig) else templates.BRANCH, branch) + round_cap_breaches(commit, titles) + round_report_breaches(commit, titles, home) + todo_breaches(commit.directory, home)
def checkout_branch(directory: str) -> str | None:
+30
View File
@@ -0,0 +1,30 @@
"""rule-hook's check of a round commit's counts against the round's report in the chunk's review folder."""
import pathlib
from rule_hook.rules import Breach
from git_cli.git_command import CommitCall
from failure import Failure
from review_rules.review_folder import findings_in, review_folder, standing_report
from git_cli.git_repo import git
from review_rules.round_titles import ROUND, round_prefix, title_counts
from project_config.templates import Titles
def round_report_breaches(commit: CommitCall, titles: Titles, home: pathlib.Path) -> list[Breach]:
"""A breach for each round title whose counts differ from those its round's report gives. The round title is the commit title's summary, as `titles` cuts it. A title without all three counts is title_breaches' to refuse. A round whose report is missing or unreadable, or says BLOCK without a finding heading, goes through, as does every round where git cannot name the commit's checkout within 5 seconds."""
summaries = [titles.summary(message.strip()) for message in commit.messages]
rounds = [(named, counts) for summary in summaries if (named := ROUND.match(summary)) and (counts := title_counts(summary)) and counts.misread is not None]
if not rounds:
return []
worktree = git("rev-parse", "--show-toplevel", cwd=commit.directory, timeout=5, guarded=True)
if isinstance(worktree, Failure):
return []
folder = pathlib.Path(review_folder(str(home), worktree.strip()))
breaches = []
for named, counts in rounds:
pass_, round_ = named.group(1).lower(), int(named.group(2))
report = standing_report(folder, pass_, round_)
found = findings_in(report)
if not isinstance(found, Failure) and found != counts:
breaches.append(Breach("round-title-counts", f"{report} counts `{round_prefix(pass_, round_, found)}`; open the title's summary with that, which `larv-review round-title {pass_}` prints", commit.directory))
return breaches
+1 -1
View File
@@ -84,7 +84,7 @@ RULES: dict[RuleName, Rule] = {
),
"round-title-counts": Rule(
f"a larv-review round's commit title gives the counts of 🔴 and 🟡 findings the round reported, and how many of them a reviewer marked `[misread]`, at most the two together, such as `{EXAMPLE}`, since score-outcomes counts them",
f"a git commit whose message opens `{OPENING}`",
f"a git commit whose message opens `{OPENING}`; its counts are checked against the round's report in the chunk's review folder, where that report exists",
),
"run-heavy": Rule(
"a heavy command, which loads the machine for minutes, runs under ~/.claude/bin/run-heavy, so sessions running at once cannot starve the machine",
+26
View File
@@ -1055,6 +1055,32 @@ class Hook(unittest.TestCase):
def round_commit(self, title: str, given: str = "") -> subprocess.CompletedProcess:
return hook({"cwd": self.repo, "tool_input": {"command": f"git commit {given}-m '{title}'"}, "tool_name": "Bash"}, self.repo)
def test_a_round_commit_whose_counts_differ_from_its_report_is_refused(self):
home = tempfile.mkdtemp()
self.addCleanup(subprocess.run, ["rm", "-rf", home])
folder = pathlib.Path(home, ".local", "state", "larv-review", self.repo.lstrip("/"))
folder.mkdir(parents=True)
(folder / "stability-round-1.md").write_text("BLOCK\n\n### 🔴 [misread] `a.py:1`: wrong\n\n### 🟡 `b.py:2`: worse\n")
def commit(title: str) -> subprocess.CompletedProcess:
return hook({"cwd": self.repo, "tool_input": {"command": f"git commit -m '{title}'"}, "tool_name": "Bash"}, self.repo, {"HOME": home})
wrong = commit("Answer stability round 1: 1 🔴, 2 🟡 (0 misread); fix")
self.assertEqual(wrong.returncode, 2)
self.assertIn(f"Blocked by rule round-title-counts: {folder}/stability-round-1.md counts `Answer stability round 1: 1 🔴, 1 🟡 (1 misread);`", wrong.stderr)
self.assertEqual(commit("Answer stability round 1: 1 🔴, 1 🟡 (1 misread); fix").returncode, 0)
self.assertEqual(commit("Answer prose round 1: 0 🔴, 3 🟡 (0 misread); fix").returncode, 0, "a round whose report is missing goes through")
self.assertEqual(commit("Answer stability round 1: 1 🔴, 2 🟡 (0 misread); fix # rule-override round-title-counts: the reviewer wrote its findings as a list").returncode, 0)
self.assertEqual(commit("Answer Stability round 1: 1 🔴, 2 🟡 (0 misread); fix").returncode, 2, "a capitalised pass reads its report")
elsewhere = tempfile.mkdtemp()
self.addCleanup(subprocess.run, ["rm", "-rf", elsewhere])
moved = hook({"cwd": elsewhere, "tool_input": {"command": f"git -C {self.repo} commit -m 'Answer stability round 1: 1 🔴, 2 🟡 (0 misread); fix'"}, "tool_name": "Bash"}, elsewhere, {"HOME": home})
self.assertEqual(moved.returncode, 2, "the report is the commit's checkout's, not the hook's working directory's")
outside = hook({"cwd": elsewhere, "tool_input": {"command": "git commit -m 'Answer stability round 1: 1 🔴, 2 🟡 (0 misread); fix'"}, "tool_name": "Bash"}, elsewhere, {"HOME": home})
self.assertEqual((outside.returncode, outside.stderr), (0, ""), "outside a checkout no report is read")
(folder / "stability-round-1-rerun.md").write_text("BLOCK\n\n### 🔴 `a.py:1`: wrong\n\n### 🟡 `b.py:2`: worse\n\n### 🟡 `c.py:3`: worse\n")
self.assertEqual(commit("Answer stability round 1: 1 🔴, 2 🟡 (0 misread); fix").returncode, 0, "the rerun's report stands in place of the round's")
def test_a_round_commit_past_round_2_is_refused_and_offers_no_override(self):
ran = self.round_commit("Answer stability round 3: 0 🔴, 1 🟡 (0 misread); fix # rule-override round-cap: the human said yes")
self.assertEqual(ran.returncode, 2)
+2 -2
View File
@@ -63,7 +63,7 @@ A comment is prose, not code, in any file, and so is a docstring. A change to co
Give a reviewer without Bash `git ls-files`'s output in its prompt, since some harnesses grant it Read alone.
`~/.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; the history's format, its latest places and its count of how often seats agree; and the header of each reviewer's prompt. 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 chunk's review folder, the round count and each round commit's counts, the paired ruling's base and vote count, the scoring run's trigger; the history's format, its latest places and its count of how often seats agree; and the header of each reviewer's prompt. 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 reviewer-header <pass>` in the chunk's worktree, and open each prompt to an agent under `~/.claude/agents/` with what it prints; then say in a few lines what the change does and which files it touches. The command makes the chunk's review folder and writes the branch diff and the plan's listing into it. The header names that diff, the reviewer's full report, `<pass>-round-<n>.md`, in the folder, the folders of technical principles and review standards the project's config sets, the listing, and for architecture and stability the places too. For a reviewer whose definition starts it without `CLAUDE.md`, the header's last line names the file that holds the project principles and decision titles, which the reviewer reads first. For a relaunch one rung up, add `--rerun`: the report becomes `<pass>-round-<n>-rerun.md`, and the header names the report that asked. 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: `review-replay` replays a round from the reports its prompt names, and `compress-archives` gzips each file 30 days after it last changed.
@@ -83,7 +83,7 @@ Give a reviewer without Bash `git ls-files`'s output in its prompt, since some h
- **Round.** A round is one review by a pass's reviewer: the first and each re-entry. The rerun after the architect returns Stage 0 questions ("Architecture" below) and a relaunch one rung up ("Rung up" below) stay in their round.
- **Auto-reviewer.** The external auto-reviewer (§4) is a pass of its own, each review it posts, up to the cap, a round. Its count is the number of its reviews on the PR, less its reviews of a `Record the comprehension check:` commit, and `round-count` doesn't list it. A commit that answers one of its rounds takes an ordinary title, not an `Answer <pass> round` one, and a round that didn't change anything gets no commit.
- **Count.** Close each round of a pass other than the auto-reviewer with one commit that holds the round's fixes. Title it `Answer <pass> round <n>: <k> 🔴, <m> 🟡 (<j> misread); …`: `<pass>` is the pass's name in lower case, such as `full scan`, `<k>` and `<m>` are the 🔴 and 🟡 findings all the round's reviewers reported, and `<j>` is how many of those they marked `[misread]` (review-findings.md → "Misread"); a reviewer that marks none, such as `/security-review`, adds 0. Example: `Answer stability round 1: 1 🔴, 2 🟡 (1 misread); flag a deleted test`. A round that didn't change anything gets an empty commit (`git commit --allow-empty`). Push the commits when §4 runs next, where there is a remote. `~/.claude/bin/larv-review round-count` prints each pass's count and marks a pass at the cap.
- **Count.** Close each round of a pass other than the auto-reviewer with one commit that holds the round's fixes. Title it `Answer <pass> round <n>: <k> 🔴, <m> 🟡 (<j> misread); …`: `<pass>` is the pass's name in lower case, such as `full scan`, `<k>` and `<m>` are the 🔴 and 🟡 findings all the round's reviewers reported, and `<j>` is how many of those they marked `[misread]` (review-findings.md → "Misread"); a reviewer that marks none, such as `/security-review`, adds 0. Example: `Answer stability round 1: 1 🔴, 2 🟡 (1 misread); flag a deleted test`. For a pass an agent under `~/.claude/agents/` reviews, run `~/.claude/bin/larv-review round-title <pass>` and write only the summary after what it prints: the title up to and including its `;`, counted from the round's report. Where it exits 1 for want of a report it can count, count the findings by hand, and the hook lets the title through. rule-hook's `round-title-counts` refuses a title whose counts differ from that report's. A round that didn't change anything gets an empty commit (`git commit --allow-empty`). Push the commits when §4 runs next, where there is a remote. `~/.claude/bin/larv-review round-count` prints each pass's count and marks a pass at the cap.
- **Done.** A pass is done when its latest round leaves no 🔴 or 🟡 standing: none was reported, or each was shown factually wrong, declined, filed, or named under the bar per "Findings", or settled in the PR summary per "Comprehension check" → "Places", or, for the prose pass and a pass at its cap, fixed. A stability pass whose round's fixes skip the next round per "Re-entry" → "Mechanical answers" is done once that rule's run is clean. Resolve that round's 🟢s and ❓s per "Findings" too.
- **Cap.** A pass takes at most two rounds per chunk, and the release review's architecture and principles passes five; don't ask the user for more. Answer its last round's findings per "Findings": those fixes merge once the gate passes, unreviewed by that pass. rule-hook's `round-cap` refuses a round commit that would take a pass past its cap, and no override waives it. A review the auto-reviewer posts after its second isn't a round: fix none of it and rerun no pass for it, but file a security finding it raises per `~/.claude/CLAUDE.md` → "Working loop", and any other 🔴 in `todo.md`.
+1 -1
View File
@@ -32,7 +32,7 @@ Where your report holds a finding against `quality.md`, or you are systems-archi
## 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:
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. Open each finding with a `###` heading: its severity mark, `[misread]` where you marked it so, its place, then what is wrong, as in ``### 🔴 [misread] `bin/example.py:42` `parse`: an empty line raises IndexError``. `larv-review round-title` counts the round's 🔴 and 🟡 findings by these headings, so no other line of the report may open with `### 🔴` or `### 🟡`. Then return only:
- the verdict line
- one line per finding, in this order: its severity mark, `[misread]` where you marked the finding so, its place, and what is wrong, in one sentence. Where the finding breaks the review standards' `quality.md` or a file in the config's principles folder, 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)``
-20
View File
@@ -22,7 +22,6 @@
| 310 | 0.12.0 | | | **Compact a waiting worker's session shortly before its prompt cache expires, only when the human has not answered an interrupt by then.** | 3 | 2 | 3 | 6 | 4 | 1.4 by 3 | 0.9 |
| 393 | 0.12.0 | | decision | **Step an L 3 worker one rung up and an L 4 worker two up from the project's rung, as lilleman ruled on 2026-11-14.** | 2 | 1 | 3 | 4 | 4 | 1.4 by 3 | 0.9 |
| 298 | 0.12.0 | | | **Send the judge only the decision entries and the transcript tail a verdict needs, and keep the cut only where `judge-replay` changes no verdict kind.** | 3 | 3 | 3 | 7 | 4 | 1.4 by 2, 1.5 by 1 | 0.9 |
| 327 | 0.12.0 | | | **Have `larv-review` print a round commit's title prefix, counted from the round's report, and have rule-hook refuse a round title whose counts differ from it.** | 3 | 2 | 3 | 6 | 4 | 1.1 by 1, 1.4 by 1 | 0.6 |
| 365 | 0.13.0 | | | **Have `score-outcomes` read the finished and dropped items of a plan outside the checkout, from the project repo's history or from Jira's issue changelogs.** | 3 | 2 | 2 | 5 | 4 | 1.6 by 2, 1.1 by 2 | 1.2 |
| 368 | 0.13.0 | | | **Call a release review due, call a release ready to cut, and tell whether a chunk owes a scoring run, for a plan outside the checkout, from the project repo's history or from Jira.** | 3 | 2 | 2 | 5 | 4 | 1.6 by 2, 1.1 by 2 | 1.2 |
| 309 | 0.13.0 | | | **Run a scoring run's second pass on one head with two seats in place of four, once `larv-review agreement` shows the seats agree with each other more than a run agrees with its rerun.** | 2 | 2 | 2 | 4 | 2 | 1.4 by 3 | 1.2 |
@@ -207,25 +206,6 @@ Touches:
- `bin/loop_claude/test_loop_claude.py`: `JudgePrompt`, `Records`
- `bin/judge_replay/test_judge_replay.py`
### 327. Have `larv-review` print a round commit's title prefix, counted from the round's report, and have rule-hook refuse a round title whose counts differ from it.
The 0.8.0 audit (item 284) measured, over the 35 chunks that shipped 0.7.0: 72 commit calls in 33 chunks titled `Answer <pass> round <n>: R 🔴, Y 🟡 (K misread); <what changed>`, about 11k command tokens, most of them the summary. Each worker counts R, Y and K by hand. All three are in the round's report, `<pass>-round-<n>.md` in the review folder: R and Y are its finding headings, and K counts the findings the reviewer marked `[misread]`, as `bin/review_rules/round_titles.py` says. That module parses the counts for `score-outcomes`, which reports them as goal 1.1's signal, and rule-hook's `round_cap.py` checks only the round number, so nothing checks today that the counts match the report. Of the 8 titles whose report the audit could match, none miscounted; one report wrote its markers at line start rather than in `###` headings, so the reports' format varies by reviewer.
Add a `larv-review` subcommand that prints a round title's prefix, up to and including the `;`, from the round's report, and have rule-hook refuse a round title whose counts differ from it. Pin the marker format in each reviewer's definition under `agents/`, or count every format the reports use today. Where the report is missing, say so and let the commit through.
Left with the model: the summary after the `;`, and answering the findings.
Touches:
- `bin/larv_review/main.py`: `(module)` (small), `COMMANDS` (small)
- `bin/review_rules/round_titles.py`
- `bin/rule_hook/rules.py`: `title_breaches`, `RULES` (small)
- `bin/rule_hook/test_rule_hook.py`: `Commits`
- `bin/larv_review/test_larv_review.py`
- `bin/review_rules/test_round_titles.py`
- `skills/larv-review/review-findings.md`: `## Report` (small)
- `skills/larv-review/SKILL.md`: `## 3. Passes` (small)
- `README.md`: `## Tools` (small)
### 365. Have `score-outcomes` read the finished and dropped items of a plan outside the checkout, from the project repo's history or from Jira's issue changelogs.
lilleman's call, 2026-11-12: 0.10.0 and 0.11.0 switch the history tools off for a plan outside the checkout, and 0.13.0 holds only their ports. In Jira a dropped item, which `Drop item` commit titles mark today, is an issue resolved by a resolution the config names.