Answer prose round 1: fold round-count's changes into the larv-review changelog entry, revise the decisions citing item 83 and stating the floor, reword the help, docstrings and seat-prompts placeholder, drop the archive layout comment that restates --help, and test the past-the-cap line

This commit is contained in:
2026-10-09 15:20:11 +02:00
parent 3c1cc85f34
commit 7e13778191
12 changed files with 21 additions and 19 deletions
+1 -2
View File
@@ -2,9 +2,8 @@
## Unreleased
- `larv-review round-count` ignores case in a round's commit title, counts a repeated round number as a round of its own, and says to ask you before another round once a pass is at or past the cap. `record-ruling` says to run it again with the votes file alone when it refuses a scores file.
- The stability reviewer keeps its scratch work in a directory it creates for the run, deletes that directory afterwards, and deletes nothing else.
- 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 <votes file> [<scores file>]` and `record-scoring <scores file> [<item ID>...]`, which append to `docs/comprehension-history.md` and refuse a second entry on what a seats file's first line reads; `record-scoring` refuses a run the plan does not call, and prints `Floor:` naming each mean under the floor). 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. 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`, which ignores case in a round's commit title, counts a repeated round number as a round of its own, and says to ask you before another round once a pass is at or past the cap), the scoring run's trigger (`needs-scoring-run <item ID>...`), and the vote count, means and history format (`record-ruling <votes file> [<scores file>]` and `record-scoring <scores file> [<item ID>...]`, which append to `docs/comprehension-history.md` and refuse a second entry on what a seats file's first line reads; `record-scoring` refuses a run the plan does not call, and prints `Floor:` naming each mean under the floor). 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. 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 on each dimension and overall: `Navigation same, Locality worse, Shape same, Self-sufficiency same, Overall better`. When their overall votes differ, the maintainability senior and Junior A vote too. A ruling needs a lead of two or more votes, else it is same. Each place a seat names opens with the dimensions it moves, such as `Locality, Shape: `, or the run fails, and a vote that no place opens with counts as same. A dimension falls when its worse votes lead by two. When a dimension falls in a better or same ruling, `record-ruling` asks for the four scoring seats and, given their scores file, counts the ruling as worse when that dimension's mean is under the floor. 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, a score under the floor blocks a merge only through a fallen dimension, and that block counts as a worse ruling. On those runs, 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.
+2 -2
View File
@@ -74,10 +74,10 @@ Install puts only `loop-claude` on `PATH`; call the others by their path, such a
- `reading-cost [--reset] [record]` appends a figure for each chunk `loop-claude` finished to a project's `docs/reading-cost.md`, and says whether the figures rise; `reading-cost --help` states the measure.
- `statusline.py` renders Claude Code's status line; `settings.json` → `statusLine` runs it.
`bin/` is the import root: each launcher puts it on `sys.path`, so a module imports another by its path under `bin/`, such as `from claude_code.entries import parse_entry`. Each tool's package holds its tests; `rank_todo.py` and `statusline.py` are tools of one file each, tested beside them. The other modules at `bin/`'s root, together with `claude_code/` and `transcript_archive/`, serve more than one tool: `claude_code/` reads and writes Claude Code's files and reads its output, and `transcript_archive/` writes and reads `loop-claude`'s archive. `test_env.py` serves the tests, and `repo_checks/` tests the repo itself.
Test on the host, with `uv` on `PATH` to fetch mypy and the Python version Install names (`docs/decisions.md` → `bin/`): `python3 -m unittest discover -s bin -p 'test_*.py'`
`bin/` is the import root: each launcher puts it on `sys.path`, so a module imports another by its path under `bin/`, such as `from claude_code.entries import parse_entry`. Each tool's package holds its tests; `rank_todo.py` and `statusline.py` are tools of one file each, tested beside them. The other non-test modules at `bin/`'s root, `claude_code/` and `transcript_archive/` serve more than one tool. `test_env.py` serves the tests, and `repo_checks/` tests the repo itself.
## Tracking a new file
`.gitignore` is an allowlist. Track a file by negating it and its parent directories, then confirm with `git check-ignore -v <path>`:
+6 -5
View File
@@ -2,7 +2,8 @@
usage: larv-review ruling-base | round-count | needs-scoring-run [<item ID>...] | record-ruling <votes file> [<scores file>] | record-scoring <scores file> [<item ID>...]
The comprehension check keeps a project from reading worse, two ways. In a paired ruling, seats read
The comprehension check keeps a project from reading worse, two ways. In a paired ruling, simulated
readers, the seats, read
the branch's head beside a base and vote better, same or worse, overall and on each dimension; a
worse ruling blocks the merge, which is the ratchet. In a scoring run, four seats score the project
from 1 to 10; a mean under the floor of {floor} blocks the merge, unless you decide to ship.
@@ -19,10 +20,10 @@ history, or whose last added paired ruling, by heading time, is better; a merge
one change against its first parent. With none, 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 counts, for each pass, the commits not yet on the default branch whose titles open
`Answer <pass> round <n>:`, in any case: the highest <n>, or the number of such commits where that
is more. It marks a pass at or past the cap of {cap} rounds, telling you to ask the human before
another round, and each name in such a title that is not a pass.
round-count prints each pass's round count among the commits not yet on the default branch whose
titles open `Answer <pass> round <n>:`, ignoring case. The count is the highest <n>, or the number of
such commits when that is more. At or past the cap of {cap} rounds, it says to ask the human before
another round. It also lists each name in such a title that is not a pass.
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
+1 -1
View File
@@ -8,7 +8,7 @@ from todo_table import Item, items, ITEMS_HEADER
def scoring_run_due(before: list[Item], after: list[Item], ships: list[int], landed: bool) -> list[str] | Failure:
"""Why the plan calls 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 its newest release tag.
A chunk that ships an item naming the floor is due one, so it can prove the floor met. So is a chunk that empties a release towards which work has landed, so no release ends unmeasured: it ships one of the release's items, or the release is the next one, the earliest before names, and landed holds. That covers a release whose last item moved to another release.
A chunk that ships an item naming the floor is due one, so it can prove the floor met. So is a chunk that empties a release after work has landed towards it, so no release ends unmeasured. Work has landed when the chunk ships one of the release's items, or when the release is the earliest one `before` names and `landed` holds. That covers a release whose last item moved to another release.
"""
plan = {item.id: item for item in before + after}
if unknown := sorted(set(ships) - set(plan)):
+1 -1
View File
@@ -84,7 +84,7 @@ def scored_seats(given: SeatsFile) -> ScoringRun | Failure:
def read_seats(path: pathlib.Path, paired: bool, refuse_recorded: bool = True) -> tuple[Heading, SeatsFile] | Failure:
"""The seats file, and the heading its record goes under, once each commit it names is in the checkout and, when refuse_recorded, before anything is printed, once the history holds no entry on what it reads."""
"""The seats file and the heading its record goes under. Fails when the file names a commit the checkout lacks, or, when refuse_recorded, when the history already holds an entry on what it reads; it runs before anything is printed."""
try:
given = seats_file(path.read_text(encoding="utf-8"))
except (OSError, UnicodeDecodeError) as failure:
+1 -1
View File
@@ -6,7 +6,7 @@ ROUND = re.compile(r"^Answer (.+?) round ([0-9]+):", re.IGNORECASE)
def round_counts(titles: list[str]) -> dict[str, int]:
"""Each pass's round count among the branch's `Answer <pass> round <n>:` commit titles: the highest <n>, or the number of such commits where that is more, so a repeated number still counts. A pass with none has 0, and a title naming no known pass adds its name. Case is ignored, so a mis-cased title still counts."""
"""Each pass's round count among the branch's `Answer <pass> round <n>:` commit titles: the highest <n>, or the number of such commits where that is more, so a repeated number still counts. A pass with none has 0, and a title naming no known pass adds its name. Case is ignored."""
highest: dict[str, int] = dict.fromkeys(PASSES, 0)
commits: dict[str, int] = dict.fromkeys(PASSES, 0)
for title in titles:
+4 -1
View File
@@ -1,4 +1,5 @@
import decimal
import itertools
import os
import pathlib
import subprocess
@@ -117,7 +118,7 @@ class History(unittest.TestCase):
def test_writes_the_sample_entry_its_parser_shows(self):
source = pathlib.Path(comprehension_history.__file__).read_text(encoding="utf-8").splitlines()
start = next(index for index, line in enumerate(source) if line.startswith("# ## "))
sample = [line.removeprefix("#").removeprefix(" ") for line in source[start:] if line.startswith("#")]
sample = [line.removeprefix("#").removeprefix(" ") for line in itertools.takewhile(lambda line: line.startswith("#"), source[start:])]
seat = Seat("Mid A", said("better", "worse"), ["Locality: `bin/x.py:12` `run`: three branches to hold at once"])
votes = {"Mid A": ["better", "worse", "same", "same", "better"]}
self.assertEqual(ruling_entry("2026-10-09T09:47:25Z, PR #232 at 324d650, against 12d6d75", [seat], votes, votes, "same", [], None), "\n".join(sample) + "\n")
@@ -268,6 +269,8 @@ class LarvReviewTool(unittest.TestCase):
self.commit("Answer stability round 3: d")
ran = self.run_tool("round-count")
self.assertIn("stability: 3, at the cap: ask the human before another round\n", ran.stdout)
self.commit("Answer stability round 4: e")
self.assertIn("stability: 4, past the cap: ask the human before another round\n", self.run_tool("round-count").stdout)
self.assertIn("prose: 1\n", ran.stdout)
self.assertIn("architecture: 0\n", ran.stdout)
+1 -1
View File
@@ -2,5 +2,5 @@ import pathlib
def project_key(checkout_root: str, home: pathlib.Path) -> str:
"""The checkout's path relative to ~/code, or to / outside it: what names a project's loop-claude session, its model and its archive folder."""
"""The checkout's path relative to ~/code, or to / outside it: what names a project's loop-claude session, its entry in the models file and its archive folder."""
return checkout_root.removeprefix(f"{home / 'code'}/").lstrip("/")
-1
View File
@@ -10,7 +10,6 @@ from claude_code.session import session_files
from utc_stamp import utc
# <project archive>/<chunk>/<sha256 of the transcript>.jsonl, its .outcomes.md beside it, and the session's other files under <chunk>/session/
def archive(project_archive: pathlib.Path, path: str, task: str, outcome: str, at: float) -> Failure | None:
try:
with open(path, "rb") as handle:
+2 -2
View File
@@ -52,8 +52,8 @@ lilleman decided to ship each of these under the floor on the day listed. Each l
- 2026-10-08, PR #225: 7.25, 6.75, 7.00, 6.88, 6.88. Above PR #224's run on every score but Shape, which held.
- 2026-10-08, PR #228: no scoring run; its last paired ruling, against 12d6d75, was worse, 2 votes to 0. lilleman shipped it below the ratchet: the seats blamed the new ratchet's own rules, since moved into the tested `bin/larv-review`.
- 2026-10-08, PR #229: no scoring run; its last paired ruling, against 12d6d75, was worse, 2 votes to 0. lilleman shipped it below the ratchet for PR #228's reason: the seats' decisive places were still PR #228's rules, since moved into `bin/larv-review`.
- 2026-10-09, PR #232: 7.13, 6.50, 6.63, 6.63, 6.88, at 324d650, whose ruling the fall made worse. Its last paired ruling, at 53014f8 against 12d6d75, split: Mid A better, the inherited architect worse, both with Locality worse. lilleman shipped it below the ratchet: after a restructure the seats still weigh PRs #229 to #231's code against the base, and their Locality places are filed under items 62 and 83.
- 2026-10-09, PR #234: 7.38, 6.50, 6.88, 6.50, 6.75, at b2a277b. Four architecture rounds each ruled better, 2 votes to 0, while the means moved within the panel's noise between runs. lilleman shipped it below the floor: every seat's remaining places sit in larv-review's rules, which need `skills/larv-review/SKILL.md` §3 open beside the code, a chunk of its own under item 62.
- 2026-10-09, PR #232: 7.13, 6.50, 6.63, 6.63, 6.88, at 324d650, whose ruling the fall made worse. Its last paired ruling, at 53014f8 against 12d6d75, split: Mid A better, the inherited architect worse, both with Locality worse. lilleman shipped it below the ratchet: after a restructure the seats still weigh PRs #229 to #231's code against the base, and their Locality places are filed under item 62; the `bin/` regrouping, item 83, shipped in PR #234.
- 2026-10-09, PR #234: 7.38, 6.50, 6.88, 6.50, 6.75, at b2a277b. Four architecture rounds each ruled better, 2 votes to 0, while the means moved within the panel's noise between runs. lilleman shipped it below the floor: most of every seat's remaining places sit in larv-review's rules, which cannot be followed without `skills/larv-review/SKILL.md` §3 open beside the code. Fixing that is a chunk of its own, under item 62.
## loop-claude: each project's model lives in `~/.claude/loop-claude-models.json`, which only loop-claude writes
+1 -1
View File
@@ -6,7 +6,7 @@ A scoring-run seat's prompt is the opening, the seat's background, the shared br
- `{main}`: the project's main checkout.
- `{forbidden}`: `todo.md, docs/decisions.md, docs/comprehension-history.md or docs/reading-cost.md (the plan, the decision log, past panels' records and past chunks' reading cost)`.
- `{git}`: `git -C {checkout} ls-files`, and for a paired seat also `git -C {base checkout} ls-files`, each in backticks.
- `{files}`: every tracked non-test file but those `{forbidden}` names, from `git -C {checkout} ls-files`, listed as one recursive glob per top-level source directory, plus each file a glob misses, naming the test files a glob would match as left out, such as `bin/**/*.py` except `test_*.py`, and the launchers `bin/larv-review`, `bin/loop-claude`, `bin/metric-bench` and `bin/reading-cost`.
- `{files}`: every tracked file in `git -C {checkout} ls-files`, except test files and those `{forbidden}` names. Give one recursive glob per top-level source directory, say which test files it leaves out, and list each file no glob matches. Example: `bin/**/*.py` except `test_*.py`, plus launchers such as `bin/loop-claude`.
- `{preloaded}`: the files the harness pre-loads into a seat, found per `SKILL.md` → "What makes the result trustworthy".
- `{anchors}` and `{dimensions}`: the six anchor bullets and the four dimension bullets in `SKILL.md` → "The score", verbatim, without bold and each on one line.
- `{language}`, `{kind}`, `{domain}`, `{domain docs}` and `{3am question}`: the project's `AGENTS.md` → "Scoring run".
+1 -1
View File
@@ -63,7 +63,7 @@ The README line covers the bench's transcripts in `workflow-bench/logs/` too (go
Raised by the principles audit of PR #215 against KISS, in `principles/technical-principles.md`, and goal 1.1: 0.1.0 waits on the floor, and the `comprehension floor:` entry in `docs/decisions.md` lists each decision to ship under it.
PR #234's last scoring run, at b2a277b, put Locality and Self-sufficiency at 6.50 and the overall at 6.75. Every seat named larv-review's rules, which cannot be followed without `skills/larv-review/SKILL.md` §3 open beside the code: "Round cap", "Re-entry", "Fresh" and "Suspended" point at each other; `bin/larv_review/record.py` `record_ruling` branches on split, worse, fell and a scores file, with its terms defined only in `larv-review --help` and the skill; the pass list lives in both `bin/larv_review/rounds.py` `PASSES` and the skill's table, which also counts the auto-reviewer; `bin/comprehension_history.py` is reader, writer and seat registry in one, parsed by regex for two tools. Also named: the judge's prompt assembled from `cycle/judge.py`, `cycle/prompts.py` and `project/records.py`; four ways to run git; `SeatsFile.read`, a noun.
PR #234's last scoring run, at b2a277b, put Locality and Self-sufficiency at 6.50 and the overall at 6.75. Every seat named larv-review's rules, which cannot be followed without `skills/larv-review/SKILL.md` §3 open beside the code: "Round cap", "Re-entry", "Fresh" and "Suspended" point at each other; `bin/larv_review/record.py` `record_ruling` branches on split, worse, fell and a scores file, with its terms defined only in `larv-review --help` and the skill; the pass list lives in both `bin/larv_review/rounds.py` `PASSES` and the skill's table, which also counts the auto-reviewer; `bin/comprehension_history.py` is reader, writer and seat registry in one, and parses the history by regex for two tools. Also named: the judge's prompt assembled from `cycle/judge.py`, `cycle/prompts.py` and `project/records.py`; git run four ways, in `bin/larv_review/git.py`, `bin/metric_bench/main.py`, `bin/reading_cost/main.py` and `bin/loop_claude/effects.py`; `SeatsFile.read`, a field named like a method.
### 21. Give `settings.json`'s model one writer, and sort its keys.