Answer prose round 1: move the tool paragraph below the reviewer prompt rule, name the commands its and it pointed at, state the seats file's first line and the migration's two lines, and rewrite four --help paragraphs

This commit is contained in:
2026-10-09 01:37:56 +02:00
parent 642a8bc80b
commit efed78bf5e
5 changed files with 33 additions and 30 deletions
+1 -1
View File
@@ -2,7 +2,7 @@
## Unreleased
- larv-review's mechanical rules run in the new, tested `bin/larv-review`: the paired ruling's base (`ruling-base`), each pass's round count (`round-count`), the scoring run's trigger (`needs-scoring-run <item ID>...`), and the vote count, means and history format (`record-ruling` and `record-scoring`, which read a seats file and append to `docs/comprehension-history.md`). The skill says when to run each and what its answer means. A seats file line the tool cannot read fails the run, so a mistyped vote never counts as same. The base search compares the history before and after each merged change, so it no longer depends on how a line is worded, and orders a change's rulings by their headings' times. A release left with no plan item is due a scoring run however its items left, moved to another release included. A seats file must name commits the checkout holds. Scores a `comprehension floor:` decision entry still holds move into the history through `record-scoring`, as a `Mean:` line. When origin cannot be fetched, the tool reads it as last fetched and says so.
- larv-review's mechanical rules run in the new, tested `bin/larv-review`: the paired ruling's base (`ruling-base`), each pass's round count (`round-count`), the scoring run's trigger (`needs-scoring-run <item ID>...`), and the vote count, means and history format (`record-ruling` and `record-scoring`, which read a seats file and append to `docs/comprehension-history.md`). The skill says when to run each and what its answer means. A seats file line the tool cannot read fails the run, so a mistyped vote never counts as same. The base search compares the history before and after each merged change, so it no longer depends on how a line is worded, and orders a change's rulings by their headings' times. A release whose last plan item moves to another release is due a scoring run too, once work has landed towards it. A seats file must name commits the checkout holds. Scores a `comprehension floor:` decision entry still holds move into the history through `record-scoring`, as a `Mean:` line. When origin cannot be fetched, the tool reads it as last fetched and says so.
- The new `bin/metric-bench` benches cheap static metrics of a project's Python against the places its comprehension history names as hardest: cognitive complexity, length, shared state and change spread, each scored by how well it ranks the named functions above the rest. No metric enters review yet.
- larv-review blocks a merge when simulated readers rule that the PR makes the project read worse than the last measured commit: the default branch's newest merged change that added a scoring run to `docs/comprehension-history.md`, or whose last ruling there is better. A ruling of same leaves that commit in place, so a worse ruling may name places earlier chunks wrote. In each architecture pass Mid A and the inherited architect vote better, same or worse; when they disagree, the maintainability senior and Junior A vote too. A ruling needs a lead of two or more votes, else it is same, and a vote that names no place counts as same. A worse ruling never ships: after three rounds larv-review asks you for another round, a no leaves the PR unmerged, and so does an unattended run. The four-seat scoring run checks the comprehension floor only when a chunk ships or removes a release's last plan item, or ships an item naming the floor; between those runs the floor blocks nothing. A score under the floor blocks the merge until fixed or until you decide to ship; a decision in `docs/decisions.md` that lets every chunk ship under the floor counts as yours.
- larv-review reruns fewer passes after a fix. A fix reruns the pass whose 🔴 or 🟡 it answers, plus stability when the fix changes behaviour, security when it opens an untrusted-input boundary or touches authn/authz, secrets or crypto, and architecture when it carries an architectural decision. A rerun reviews only what changed since that pass last reviewed. A fix for a 🟢, a ❓ or any prose finding reruns no pass, and prose takes one round.
+24 -21
View File
@@ -8,27 +8,29 @@ branch, or else the local main or master, as the default branch. When the fetch
reads origin as last fetched and says so on stderr; the other two exit 1. The history is
docs/comprehension-history.md in the checkout.
ruling-base prints the commit a paired ruling reads against, then how it was found: the default
branch's newest merged change that adds a scoring run to the history, or whose last added paired
ruling, by its heading's time, is better; a merge commit is one change against its first parent.
With none, the base the history's first paired ruling names; with no ruling either, the merge base
of HEAD and the default branch.
ruling-base prints the commit a paired ruling reads against, then a line saying how it found it.
The base is the default branch's newest merged change that adds a scoring run to the history, or
whose last added paired ruling, by heading time, is better. A merge commit counts as one change
against its first parent. With no such change, the base is the one the history's first paired
ruling names; with no ruling either, it is the merge base of HEAD and the default branch.
round-count prints, for each pass, the highest <n> among this branch's commit titles opening
`Answer <pass> round <n>:`, counting commits the default branch does not hold, and marks a pass at
the cap of {cap} rounds, and a name in such a title that is no pass.
round-count prints each pass's count: the highest <n> among the titles opening
`Answer <pass> round <n>:` of commits the default branch does not hold. It marks each pass at the
cap of {cap} rounds, and each name in such a title that is not a pass.
needs-scoring-run prints why the chunk shipping the given todo.md item IDs, none for a chunk that
ships no item, takes a scoring run, or `No scoring run due.` It is due when the chunk ships an item
whose tagline names the comprehension floor, or when a release the default branch's todo.md names
has no item left in the checkout's todo.md, less the items shipped, and work has landed towards
it: the chunk ships one of its items, or it is the earliest release the default branch's todo.md
names and the default branch has a commit after its newest v* tag, or has no such tag.
needs-scoring-run takes the IDs of the todo.md items the chunk ships, none when it ships none, and
prints why the chunk is due a scoring run, or `No scoring run due.` It is due when the chunk ships
an item whose tagline names the comprehension floor, or when it leaves a release with no item in
the checkout's todo.md, less the shipped items, and work has landed towards that release. Work has
landed when the chunk ships one of the release's items, or when the release is the earliest the
default branch's todo.md names and the default branch has a commit after its newest v* tag, or has
no v* tag.
record-ruling and record-scoring read a seats file: a first line naming what the seats read, then
each seat's line, each followed by its places, one `- ` bullet each, as the history writes them. A
seat's line opens with its label, written exactly: `Junior A:`, `Mid A:`, `Maintainability
senior:` or `Inherited architect:`.
record-ruling and record-scoring read a seats file: a first line naming what the seats read,
`<PR or branch> at <commit>`, ending `, against <base>` for a paired ruling, then each seat's
line, each followed by its places, one `- ` bullet each, as the history writes them. A seat's line
opens with its label, written exactly: `Junior A:`, `Mid A:`, `Maintainability senior:` or
`Inherited architect:`.
PR #231 at abc1234, against def5678
@@ -54,8 +56,9 @@ names no `, against`. It appends the seats' scores and their means, rounded half
decimals, and prints the means and each one under the floor of {floor}.
Each record is appended to the history, created when missing, under a heading of the current UTC
time and the seats file's first line, or of that line alone when it opens with a date. Each commit
the line names must be in the checkout. Each run appends, so record a ruling or a run once.
time and the seats file's first line. A file holding a `Mean:` line alone opens with the date or
time its decision entry gives, and that line alone is the heading. Each commit the line names
must be in the checkout. Each run appends, so record a ruling or a run once.
Exit 1, saying why, on unknown arguments, an unknown item ID, a seats file it cannot read or that
breaks the shape above, or when git cannot start, finds no checkout or no default branch, cannot
@@ -155,7 +158,7 @@ def needs_scoring_run(default: str, ids: list[int]) -> Failure | None:
after = pathlib.Path(checkout, "todo.md").read_text(encoding="utf-8")
except (OSError, UnicodeDecodeError) as failure:
return Failure(f"could not read todo.md: {failure}")
# A plan a chunk is reshaping into one table has none yet on the default branch.
# While a chunk reshapes todo.md into one table, the default branch's todo.md has no items table.
planned = plan_items(before) if ITEMS_HEADER in before.splitlines() else []
if isinstance(planned, Failure):
return Failure(f"{default}'s todo.md: {planned.reason}")
+1 -1
View File
@@ -103,7 +103,7 @@ def plan_items(todo: str) -> list[Item] | Failure:
def scoring_run_due(before: list[Item], after: list[Item], ships: list[int], landed: bool) -> list[str] | Failure:
"""Why the chunk takes a scoring run, empty when it does not. before is the default branch's plan, after the chunk's, ships the IDs it ships, and landed whether the default branch holds a commit after the newest release tag. A release has work landed towards it when the chunk ships one of its items, or when it is the earliest release before names and landed holds."""
"""Why the chunk takes a scoring run, empty when it does not. before is the default branch's plan, after the chunk's, ships the IDs it ships, and landed whether the default branch holds a commit after the newest release tag. A release has work landed towards it when the chunk ships one of its items, or when it is the earliest release in before and landed holds."""
plan = {item.id: item for item in before + after}
if unknown := sorted(set(ships) - set(plan)):
return Failure(f"neither plan holds item {', '.join(map(str, unknown))}")
+1 -1
View File
@@ -279,7 +279,7 @@ class LarvReviewTool(unittest.TestCase):
def test_states_its_rules_and_finds_origins_default_branch_where_the_clone_recorded_none(self):
helped = self.run_tool("--help")
self.assertEqual(helped.returncode, 0, helped.stderr)
self.assertIn("the cap of 3 rounds", helped.stdout)
self.assertIn("cap of 3 rounds", helped.stdout)
self.git("remote", "set-head", "origin", "--delete")
self.assertEqual(self.run_tool("needs-scoring-run", "2").stdout, "No scoring run due.\n")
+6 -6
View File
@@ -39,12 +39,12 @@ A pass is one kind of review, a row of the table, named by its first column. Its
| Product-owner | product-owner-reviewer | changes an external surface: API, CLI, UI, error or deprecation text a consumer reads, README and docs an outside reader lands on |
| Prose | prose-reviewer | every chunk, one round |
`~/.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. 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.
A comment is prose, not code. Passes run in this order: line-level polish on code the architect wants restructured, or on a call the security pass will rewrite, is wasted work.
Give a reviewer without Bash the branch diff and `git ls-files`'s output in its prompt: some harnesses grant it Read alone.
`~/.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. 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.
**Precedent, then ask** — for the architecture pass and the full scan:
- **Skip.** A precedent is a `docs/decisions.md` entry, or a plan item crediting the pass, that the repo held before the chunk began. Where one holds the decision this change executes, skip the pass and cite that entry or item.
@@ -95,9 +95,9 @@ Then the comprehension check: simulated readers, launched per `~/.claude/skills/
- **Base.** The last measured commit, which `~/.claude/bin/larv-review ruling-base` prints.
- **Head.** Before each ruling, merge `origin/<default branch>` into this branch unless the head already holds it, so the seats see only this branch's change on top of the base.
- **Seats.** Mid A and the inherited architect. Write what they read and their replies into a seats file in your scratchpad, in the shape `~/.claude/bin/larv-review --help` shows, and run `~/.claude/bin/larv-review record-ruling <file>`. On `Split:`, launch the maintainability senior and Junior A together, add their lines, and run it again.
- **Ruling.** The `Ruling:` line it prints, which it appends to the history.
- **Ruling.** The `Ruling:` line `record-ruling` prints and appends to the history.
**Scoring run**, when `~/.claude/bin/larv-review needs-scoring-run <the IDs of the items the chunk ships, if any>` prints `Scoring run due:`. Run it before removing the chunk's items from `todo.md`. Junior A, Mid A, the maintainability senior and the inherited architect each score the project at the head from 1 to 10 overall and on four dimensions: Navigation, Locality, Shape and Self-sufficiency. Write their lines into a seats file and run `~/.claude/bin/larv-review record-scoring <file>`, which appends the run to the history and prints the four seats' means.
**Scoring run**, when `~/.claude/bin/larv-review needs-scoring-run <the IDs of the items the chunk ships, if any>` prints `Scoring run due:`. Run `needs-scoring-run` before removing the chunk's items from `todo.md`. Junior A, Mid A, the maintainability senior and the inherited architect each score the project at the head from 1 to 10 overall and on four dimensions: Navigation, Locality, Shape and Self-sufficiency. Write their lines into a seats file and run `~/.claude/bin/larv-review record-scoring <file>`, which appends the run to the history and prints the four seats' means.
The chunk does not merge while either holds:
@@ -110,10 +110,10 @@ Fix a worse ruling at the places the seats voting worse name, and the floor at t
Two files of the project keep the records:
- **History.** `docs/comprehension-history.md` keeps every paired ruling and scoring run, which `larv-review` appends; nothing edits them. Appending re-enters no pass. Resolve a merge conflict in the file by putting the default branch's entries first.
- **History.** `docs/comprehension-history.md` keeps every paired ruling and scoring run, which `larv-review` appends; never edit one. Appending re-enters no pass. Resolve a merge conflict in the file by putting the default branch's entries first.
- **Entry.** `docs/decisions.md` keeps one entry whose title opens `comprehension floor:`. It holds each decision to ship under the floor, with its scores.
A `comprehension floor:` entry written before the history may still hold a scoring run's five scores. The next scoring run moves them, and only them, into the history as its first run: run `~/.claude/bin/larv-review record-scoring` on a seats file whose first line is the date or time the entry gives, then what it names the run by and the commit, the one it names or else the one that wrote those scores into the entry, and whose one seat line is `Mean:` followed by the five scores. The rest of the entry stays.
A `comprehension floor:` entry written before the history may still hold a scoring run's five scores. The next scoring run moves them, and only them, into the history as its first run. Write a seats file of two lines and run `~/.claude/bin/larv-review record-scoring` on it. The first line is `<the date or time the entry gives>, <what the entry names the run by> at <commit>`, the commit being the one the entry names, or else the one that wrote those scores into it. The second is `Mean:` and the five scores, in the shape `--help` shows. The rest of the entry stays.
Put each ruling with its base and votes, and each run's five scores, in the summary. List in the entry each decision to ship under the floor, and file its places in `todo.md` per `~/.claude/CLAUDE.md` → "Todo items". A project without the entry gets it at its first scoring run, titled `comprehension floor: every dimension and the overall at 7.0 or above` and applying KISS (`~/.claude/principles/technical-principles.md`).