Answer stability, product-owner, prose and architecture round 3: count only a commit's last history entry toward the base, merge the default branch in before each ruling, judge the scoring run's trigger on the plan as the chunk leaves it, count a vote naming no place as same, say in the changelog what a worse ruling and the floor do to the owner, and correct item 29

This commit is contained in:
2026-10-08 20:50:19 +02:00
parent 51949a06dd
commit dbe7bd3abd
7 changed files with 21 additions and 20 deletions
+3 -3
View File
@@ -2,14 +2,14 @@
## Unreleased
- larv-review's comprehension check. In each architecture pass a paired ruling decides the ratchet: Mid A and the inherited architect read the project at the PR head and at the last measured commit, and vote whether it reads better, the same or worse. The last measured commit is the default branch's newest that added a scoring run or a ruling of better to `docs/comprehension-history.md`. When the two disagree, the maintainability senior and Junior A vote too; a ruling settles on a lead of two votes, and four seats without one rule same. A worse ruling blocks the merge until fixed; after three rounds larv-review asks you, and an unattended run leaves the PR unmerged with the question. The four-seat scoring run checks the comprehension floor when a chunk leaves a release with no plan items, or ships an item naming the floor. 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 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 that added a scoring run or a ruling of better to `docs/comprehension-history.md`. 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. 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.
- larv-review runs one security pass on each change: the full scan alone when it runs, else `/security-review`.
- larv-review runs the new `bin/reading-cost`, which measures each chunk `loop-claude` finished from its archive: the new input tokens the worker and its subagents took in before the worker's first commit, and the files git tracks that they read most. It appends each figure the project's `docs/reading-cost.md` lacks. Once 10 chunks are measured, and the last 5 chunks' median is above the 5 before them, larv-review files one plan item naming the files read most, or refreshes it. The chunk that ships it runs `reading-cost --reset`, so the trend counts only chunks that finished after it.
- larv-review appends every paired ruling and scoring run to the project's `docs/comprehension-history.md`: the commit the seats read, each seat's vote or scores, and the places each seat named. The `comprehension floor:` entry in `docs/decisions.md` keeps only the decisions to ship under the floor; a project's next scoring run moves the last scores the entry still holds into the history. The seats do not read the history.
- larv-review appends every paired ruling and scoring run to the project's `docs/comprehension-history.md`: the commit the seats read, a ruling's base, each seat's vote or scores, and the places each seat named. The PR summary gives each ruling with its base and votes. The `comprehension floor:` entry in `docs/decisions.md` keeps only the decisions to ship under the floor; a project's next scoring run moves the last scores the entry still holds into the history. The seats do not read the history.
- The README's goals put quality with the fewest interrupts first, as goal 1; sharing the setup, backups and leaking nothing follow as goals 2–4.
- larv-review reruns the comprehension check before merge when any commit since its last run changes more than `docs/decisions.md`, `docs/comprehension-history.md`, `docs/reading-cost.md`, `todo.md` or `CHANGELOG.md`, so the recorded result is the merged commit's. A result that blocks the merge is never filed in `todo.md`. A rerun counts toward the three-round cap only when it reports a block that no decision of yours covers.
- larv-review skips the comprehension check for a chunk whose plan items a project decision names. The decision also names the later item whose check ends the suspension. Neither the ratchet nor the floor can block a skipped chunk, and its summary cites the decision. A chunk that meets the scoring run's trigger is always measured.
- larv-review skips the comprehension check for a chunk whose plan items a project decision names. The decision also names the later item whose check ends the suspension. A skipped chunk cannot be blocked for reading worse or for the floor, and its summary cites the decision. A chunk that ships or removes a release's last plan item, or ships an item naming the floor, still gets the scoring run.
- README → Install and Update give the commands that check the latest tag out into `~/.claude`: on a new machine, whether or not Claude Code has already created the directory, and on one already on an older tag.
- A session commits changes Claude Code made to `settings.json` only once their diff holds no credential, and asks you to move any credential out of the file first.
- A technical principle, "Sane defaults, where a default serves better than an explicit ask". A default suits a value most callers want, does no harm when wrong, and can be seen and changed. It lives at the program's edge, such as a CLI; a library still asks for data, the clock and randomness.
+2 -2
View File
@@ -34,10 +34,10 @@ How work proceeds in any repo, unless the repo's `AGENTS.md` says otherwise. The
## Quality
Quality is proven by review. Every change is reviewed as a diff. The whole project is measured when a change carries an architectural decision, and before each release, because a project can drift from the principles one clean diff at a time. A project decision may suspend only the comprehension check, the comprehension panel's runs (`larv-review` §3 → "Architecture" → "Suspended"). `larv-review` §3 says which review runs when. Quality has three parts. When two pull against each other, the earlier one wins.
Quality is proven by review. Every change is reviewed as a diff. The whole project is measured when a change carries an architectural decision, and before each release, because a project can drift from the principles one clean diff at a time. `larv-review` §3 says which review runs when. Quality has three parts. When two pull against each other, the earlier one wins.
1. **Correct.** The work does what the goals and the plan say, and tests prove it.
2. **True to the technical principles** (`~/.claude/principles/technical-principles.md`). The `comprehension-panel` skill measures KISS (`larv-review` §3 → "Architecture"). **Comprehension never falls:** when readers comparing the chunk with the last commit the panel measured rule that it reads worse, improve what they named and rule again. After three such rounds, stop and ask the human. Before each release, a score under the comprehension floor blocks a merge.
2. **True to the technical principles** (`~/.claude/principles/technical-principles.md`). The `comprehension-panel` skill measures KISS in `larv-review`'s comprehension check (§3 → "Architecture"), which a project decision may suspend, unlike any other review. **Comprehension never falls:** when readers comparing the chunk with the last commit the panel scored or ruled better rule that it reads worse, improve what they named and rule again. After three such rounds, stop and ask the human. At a release's end, or for an item naming it, a score under the comprehension floor blocks a merge.
3. **Plainly written**, per "Prose".
## Prose
+3 -3
View File
@@ -48,7 +48,7 @@ lilleman decided to ship each of these under the floor on the day listed. Each l
- 2026-10-03, PR #202: 7.5, 7.0, 7.0, 6.75, 7.0.
- 2026-10-03, PR #208: 7.5, 7.0, 7.13, 6.63, 6.88.
- 2026-10-04, PR #215: 7.38, 6.63, 7.0, 6.88, 6.88.
- 2026-10-08, PR #224: 7.00, 6.50, 7.00, 6.50, 6.75. lilleman shipped it below the ratchet as well: its 20 lines of skill prose left the code as it was, so the fall is the panel's noise between runs, which the paired ruling no longer meets.
- 2026-10-08, PR #224: 7.00, 6.50, 7.00, 6.50, 6.75. lilleman shipped it below the ratchet as well: its 20 lines of skill prose left the code as it was, so the fall is the panel's noise between runs, which the paired ruling cancels.
- 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.
## loop-claude: each project's model lives in `~/.claude/loop-claude-models.json`, which only loop-claude writes
@@ -65,11 +65,11 @@ lilleman decided to ship each of these under the floor on the day listed. Each l
## review: a paired ruling against the last measured commit decides the ratchet; the four-seat scoring run checks the floor when a release's items run out or an item names the floor
2026-10-08, lilleman. Serves goals 1.1 and 1.4. Two independent four-seat runs moved up to 0.4 on near-identical code, so a fall within that noise forced rounds that changed nothing (PR #224). A seat reading both versions judges the difference on the same material, so the noise the versions share cancels. No conventional significance level lets a sign test settle with four votes, so the human chose a lead of two votes over every other ruling, same included. Two seats that agree settle it, so a PR that leaves the reading as it was costs two seats. A third seat alone can never settle it, so the third and fourth launch together. The base is the default branch's newest commit that added a scoring run or a ruling of better to the history. The human chose the last measured commit on the architect's finding that a merge base lets chunks without an architecture pass, and a suspended restructure's steps, fall unseen one at a time. A ruling of same leaves the base where it was, or a run of small falls each ruled same would add up unseen. Taking the commit from the default branch keeps the rule working where a project squash-merges, which drops the branch's own commits. The scoring run also runs on a chunk shipping an item that names the floor, so the chunk that lifts a project to the floor can prove it. Valid while seats reading both versions agree more often than two absolute runs do.
2026-10-08, lilleman. Serves goals 1.1 and 1.4. Two independent four-seat runs moved up to 0.4 on near-identical code, so a fall within that noise forced rounds that changed nothing (PR #224). A seat reading both versions judges the difference on the same material, so the noise the versions share cancels. No conventional significance level lets a sign test settle with four votes, so the human chose a lead of two votes over every other ruling, same included. Two seats that agree settle it, so a PR that leaves the reading as it was costs two seats. A third seat alone can never settle it, so the third and fourth launch together. The base is the default branch's newest commit that added a scoring run or a ruling of better to the history. The human chose the last measured commit on the architect's finding that with a merge base as the base, chunks without an architecture pass, and a suspended restructure's steps, could each lower comprehension unseen. A ruling of same leaves the base where it was, or a run of small falls each ruled same would add up unseen. A scoring run moves it too: otherwise a project never ruled better would compare against its first ruling forever, and a release's floor check is where the human sees the absolute level. Taking the commit from the default branch keeps the rule working where a project squash-merges, which drops the branch's own commits. The scoring run also runs on a chunk shipping an item that names the floor, so the chunk that lifts a project to the floor can prove it. A chunk that removes a release's last item without shipping it runs it too, so no release ends unmeasured. Valid while seats reading both versions agree more often than two absolute runs do.
## review: a project decision may suspend the comprehension check for the plan items it names
2026-10-04, lilleman. Serves goal 1.4. In a restructure, each step's scoring run measures code the next step deletes. It costs a run and, below the floor, blocks the step, yet says nothing about what the restructure buys. The scoring run after the last step measures that. 2026-10-08: the paired ruling replaced the scoring run in most chunks, and the suspension covers it too; the ruling after the last step reads from the commit measured before the first. Valid while such a decision names its items and the plan item that ends it.
2026-10-04, lilleman. Serves goal 1.4. In a restructure, each step's scoring run measures code the next step deletes. It costs a run and, below the floor, blocks the step, yet says nothing about what the restructure buys. The scoring run after the last step measures that. 2026-10-08: the paired ruling replaced the scoring run in most chunks, and the suspension covers it too; the ruling after the last step compares with the commit measured before the first step. Valid while such a decision names its items and the plan item that ends it.
## review: a pass skips only on a precedent: a decision, or a plan item crediting the pass, that the repo held before the chunk began
+2 -2
View File
@@ -1,6 +1,6 @@
# The comprehension seats' prompts
A scoring-run seat's prompt is the opening, the seat's background, the shared brief, and the report for its kind of seat, in that order; a paired seat's is "Paired ruling" below. Copy the text verbatim and replace each `{placeholder}`:
A scoring-run seat's prompt is the opening, the seat's background, the shared brief, and the report for its kind of seat, in that order. Copy the text verbatim and replace each `{placeholder}`:
- `{checkout}` and `{branch}`: the worktree the seats read, and its branch.
- `{main}`: the project's main checkout.
@@ -71,7 +71,7 @@ Report: the verbatim map; where it was wrong and how costly each correction was;
A paired seat's prompt is the opening, the seat's background, and the paired brief below. Its placeholders besides those above:
- `{base}` and `{head}`: the commits of the older and the newer version; `{base checkout}`: the worktree holding `{base}`.
- `{changed}`: `git -C {checkout} diff --name-status {base} {head}`, less those `{forbidden}` names.
- `{changed}`: the output of `git -C {checkout} diff --name-status {base} {head}`, less the files `{forbidden}` names.
```
Target: two versions of one project. The older, commit {base}, is checked out at {base checkout}; the newer, commit {head}, at {checkout}. Read ONLY there — never {main}, which is a different version.
+6 -5
View File
@@ -32,7 +32,7 @@ A pass is one kind of review, a row of the table, named by its first column. Its
| Pass | Reviewer | Trigger |
|------|----------|----------------------------------------|
| Architecture | systems-architect, then principles-auditor and the comprehension check | leaves its release with no plan items, or ships an item naming the comprehension floor; or carries an architectural decision: a new, restructured or moved component, module, service or boundary; a new dependency or first use of an infrastructure pattern (queue, cron, cache, websocket, …); a new or changed external contract (routes, request/response shapes, events, webhooks, published file formats, CLI flags and exit codes); a schema change beyond an additive column; a fix, only where it carries an architectural decision |
| Architecture | systems-architect, then principles-auditor and the comprehension check | ships or removes the last plan item of a release that has work landed towards it, or ships an item naming the comprehension floor; or carries an architectural decision: a new, restructured or moved component, module, service or boundary; a new dependency or first use of an infrastructure pattern (queue, cron, cache, websocket, …); a new or changed external contract (routes, request/response shapes, events, webhooks, published file formats, CLI flags and exit codes); a schema change beyond an additive column; a fix, only where it carries an architectural decision |
| Full scan | the `claude-security` plugin at high effort: `/claude-security scan this branch's changes at high` | touches authn/authz, secrets or crypto, opens an untrusted-input boundary, or adds an external surface |
| Security | `/security-review` | changes code or config, unless the full scan runs on the same change; a fix, only where it opens an untrusted-input boundary or touches authn/authz, secrets or crypto, and the full scan does not rerun on it |
| Stability | stability-reviewer | changes code, config or tests; a fix, only where it changes behaviour: what the code or its tests do |
@@ -90,11 +90,12 @@ Then the comprehension check: simulated readers, launched per `~/.claude/skills/
**Paired ruling**, in every architecture pass. Each seat votes whether the project reads better, the same or worse at this branch's head than at the base.
- **Base.** The last measured commit: the newest commit on `origin/<default branch>`, after a `git fetch`, whose change to the history (below) adds a scoring run or a `Ruling: better` line. Find it with `git log -p origin/<default branch> -- docs/comprehension-history.md`; with no remote, use `<default branch>`. A ruling of same leaves the base where it was, so small falls add up until one is seen. No such commit → the base the history's first paired ruling names; no ruling either → the merge base of the head and the default branch. A base that is not an ancestor of the head → merge the default branch into this branch first, so the seats see only this branch's change on top of it.
- **Base.** The last measured commit: the newest commit on `origin/<default branch>`, after a `git fetch`, whose change to the history (below) ends with a scoring run or a `Ruling: better` entry. Find it with `git log -p origin/<default branch> -- docs/comprehension-history.md`; with no remote, use `<default branch>`. No such commit → the base the first paired ruling in that history names; no ruling either → the merge base of the head and the default branch.
- **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. When their votes differ, the maintainability senior and Junior A vote too, launched together.
- **Ruling.** The ruling that leads every other ruling by two votes; without one, same.
- **Ruling.** The vote that leads each other vote by two or more; without one, same. A better or worse vote that names no place counts as same.
**Scoring run**, when the chunk leaves `todo.md` with no item for a release that has work landed towards it, or ships an item whose tagline names the comprehension floor. 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. A seat's overall may not exceed its lowest dimension by more than 1. Each score is the mean of the four seats, to two decimals.
**Scoring run**, when the chunk ships or removes the last plan item of a release that has work landed towards it, or ships an item naming the comprehension floor. 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. A seat's overall may not exceed its lowest dimension by more than 1. Each score is the mean of the four seats, to two decimals.
The chunk does not merge while either holds:
@@ -112,7 +113,7 @@ Two files of the project keep the records:
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: a heading of the date or time the entry gives and whatever it names the run by, its commit included where named, and a table with the mean alone. The rest of the entry stays.
Put each ruling with its votes, and each run's five scores, in the summary, and append them to the history on this branch. 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`).
Put each ruling with its base and votes, and each run's five scores, in the summary, and append them to the history on this branch. 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`).
**Fresh.** Where the chunk ran a comprehension check, the architecture pass is done only once its last paired ruling, and its last scoring run where it ran one, read the commit to merge. They may predate commits that change only `docs/decisions.md`, `docs/comprehension-history.md`, `docs/reading-cost.md`, `todo.md` or `CHANGELOG.md`. Any other commit after them, a prose fix included, because the seats read the docs, calls for a rescore: the comprehension check again, once every other pass is done, the auto-reviewer included. A rescore reporting a 🔴 that no decision to ship answers is an architecture round. Any other rescore is not a round: append only its results to the history, in a commit titled `Rescore: …`. A `Rescore:` commit re-enters no pass: push it and wait for the forge's checks (§4 step 3), not for an auto-review.
+4 -4
View File
@@ -36,7 +36,7 @@
| 80 | 0.1.0 | | **State in README → Install that every machine taking this checkout must be a sandbox, as `settings.json`'s auto mode assumes.** | 1 | 1 | 5 | 5 | 4 | 16.8 |
| 83 | 0.1.0 | | **Group `bin/` by tool, so each tool's modules and tests sit together.** | 3 | 4 | 4 | 6 | 1.1 | 15.9 |
| 5 | 0.1.0 | decision | **Key a project on its checkout's full path, and refuse to start while another session uses that key.** | 5 | 5 | 5 | 6 | 1.1 | 15.6 |
| 84 | 0.1.0 | | **Check, at each release's scoring run, that seats in a paired ruling agree more often than two absolute runs do, as the paired-ruling decision assumes.** | 2 | 2 | 4 | 5 | 1.4 | 15.1 |
| 84 | 0.1.0 | | **Check, at each release's scoring run, that seats in a paired ruling agree more often than two scoring runs on near-identical code do, as the paired-ruling decision assumes.** | 2 | 2 | 4 | 5 | 1.4 | 15.1 |
| 67 | 0.1.0 | principle | **Point stability-reviewer at the technical principles in place of its own restatement of them.** | 2 | 3 | 4 | 5 | 1.3 | 14.9 |
| 66 | 0.1.0 | principle | **Hold systems-architect's method thresholds only while the comprehension panel finds the flagged code hard.** | 3 | 3 | 4 | 5 | 1.1 | 14.2 |
| 69 | 0.1.0 | principle | **Measure test coverage, so a chunk that lowers it is seen.** | 3 | 4 | 4 | 5 | 1.1 | 13.9 |
@@ -120,9 +120,9 @@ The key names the project's session, archive folder and models entry. `project_k
`bin/reading-cost` keys the archive by the main checkout, the parent of git's common dir, since it runs in a chunk's worktree; `loop-claude` keys it by `--show-toplevel`, so a loop started inside a worktree archives where `reading-cost` never looks. Derive both keys one way.
### 84. Check, at each release's scoring run, that seats in a paired ruling agree more often than two absolute runs do, as the paired-ruling decision assumes.
### 84. Check, at each release's scoring run, that seats in a paired ruling agree more often than two scoring runs on near-identical code do, as the paired-ruling decision assumes.
Raised by the principles audit of PR #228: the `review: a paired ruling …` entry in `docs/decisions.md` is valid only while that holds, and `docs/comprehension-history.md` keeps every vote, yet nothing reads the agreement rate. A release has one scoring run, so the absolute runs to compare with are those already in the history on near-identical code, such as PR #224's and PR #225's, or a second run made for the check.
Raised by the principles audit of PR #228: the `review: a paired ruling …` entry in `docs/decisions.md` is valid only while that holds, and `docs/comprehension-history.md` keeps every vote, yet nothing reads the agreement rate. Scoring runs on near-identical code are rare now, so compare with those already in the history, such as PR #224's and PR #225's, or make a second run for the check.
### 67. Point stability-reviewer at the technical principles in place of its own restatement of them.
@@ -138,7 +138,7 @@ KISS, in `principles/technical-principles.md`, which keeps a limit only while re
### 29. Make the contributor a standing member of every project's audience, unless its `## Audience` says maintainability does not matter.
State that in `CLAUDE.md`'s goals-and-audience rule, and have larv-review's comprehension floor name the contributor as the reader it serves. The floor then gates every chunk while the contributor stands, and a project that drops them skips it.
State that in `CLAUDE.md`'s goals-and-audience rule, and have larv-review's comprehension floor name the contributor as the reader it serves. The comprehension check then runs on every chunk while the contributor stands, and a project that drops them skips it.
### 68. Test `workflow-bench/compare.py`'s blinding and `bench.py`'s run plan.
+1 -1
View File
@@ -16,7 +16,7 @@ Report: write it to `{report}`.
- Launch every agent in the foreground (`run_in_background: false`): background agents die when this headless turn ends.
- No remote and no forge: skip the PR, CI, the external auto-reviewer and the merge; review locally.
- Do not run the repo's test suites. A targeted probe is fine, in the repo's own container tooling.
- Skip the comprehension check, both the paired ruling and the scoring run; say so in the report.
- Skip the comprehension check; say so in the report.
- No human is reachable. Where the process names a no-human branch, take it; where it names none, take your recommendation and list the question in the report.
- Commit each round's fixes on `chunk`, messages prefixed `{case} - review: `. Touch nothing outside this repository except the report.