Answer architecture round 1: rule against the last measured commit, launch the third and fourth seats together, name the floor's chunk by the plan, skip the whole check in the bench, and correct the history's writer and the paired brief

This commit is contained in:
2026-10-08 20:36:25 +02:00
parent 9ae7b07620
commit 26826685e2
7 changed files with 13 additions and 13 deletions
+1 -1
View File
@@ -12,7 +12,7 @@ Decisions live in `docs/decisions.md`:
- loop-claude: each project's model lives in `~/.claude/loop-claude-models.json`, which only loop-claude writes
- review: a pass gets at most three rounds per chunk; instead of a fourth, the run asks the human
- review: a fix for a 🔴 or 🟡 reruns the pass that found it and each pass whose trigger names fixes like it; a fix for a 🟢, a ❓ or a prose finding reruns none
- review: the ratchet is a paired ruling, two to four seats until one ruling leads by two votes; the four-seat scoring run checks the floor only on each release's last item
- review: the ratchet is a paired ruling against the last measured commit, settled by two agreeing seats or a lead of two votes among four; the four-seat scoring run checks the floor only on each release's last item
- review: a project decision may suspend the comprehension check for the plan items it names
- 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
- loop-claude: the archive keeps the raw transcript, and a failed archive stops the loop
+1 -1
View File
@@ -2,7 +2,7 @@
## Unreleased
- larv-review's ratchet is a paired ruling. Mid A and the inherited architect each read the project at the merge base and at the PR head, and vote whether it reads better, the same or worse. While no ruling holds two votes more than every other, the maintainability senior and then Junior A vote too; four seats without such a lead rule same. A worse ruling blocks the merge as a fall in scores did. The four-seat scoring run, and with it the comprehension floor, runs only on the chunk that ships its release's last item. `docs/comprehension-history.md` keeps each ruling with its votes and the places each seat named.
- larv-review's ratchet is a paired ruling. Mid A and the inherited architect each read the project at the PR head and at the commit the default branch's last comprehension record read, and vote whether it reads better, the same or worse. When they 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 as a fall in scores did. The four-seat scoring run, and with it the comprehension floor, runs only on the chunk that ships its release's last item. `docs/comprehension-history.md` keeps each ruling with its votes and the places each seat named.
- 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.
+1 -1
View File
@@ -37,7 +37,7 @@ How work proceeds in any repo, unless the repo's `AGENTS.md` says otherwise. The
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 (`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.
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"): a score under the comprehension floor, scored before each release, blocks a merge. **Comprehension never falls:** when readers comparing the chunk with the default branch rule that it reads worse, improve what they named and rule again. After three such rounds, stop and ask the human.
2. **True to the technical principles** (`~/.claude/principles/technical-principles.md`). The `comprehension-panel` skill measures KISS (`larv-review` §3 → "Architecture"): a score under the comprehension floor, scored before each release, blocks a merge. **Comprehension never falls:** when readers comparing the chunk with the last measured commit rule that it reads worse, improve what they named and rule again. After three such rounds, stop and ask the human.
3. **Plainly written**, per "Prose".
## Prose
+4 -4
View File
@@ -63,13 +63,13 @@ lilleman decided to ship each of these under the floor on the day listed. Each l
2026-10-08, lilleman, replacing the 2026-09-30 rule that every fix, a nit's included, re-enters review. Serves goal 1.4. An audit of the four costliest archived chunks (2026-10-08) found nearly every finding that mattered in a pass's first round; later rounds mostly re-checked the last fix, reworded what an earlier round wrote, or contradicted another round on the same line. A round 2 caught real bugs only where a fix changed behaviour, so stability still reruns on every fix that does, and security on every fix that opens an untrusted-input boundary or touches authn/authz, secrets or crypto. Valid while round-2 reviews of nit and prose fixes keep changing nothing a user would notice.
## review: the ratchet is a paired ruling, two to four seats until one ruling leads by two votes; the four-seat scoring run checks the floor only on each release's last item
## review: the ratchet is a paired ruling against the last measured commit, settled by two agreeing seats or a lead of two votes among four; the four-seat scoring run checks the floor only on each release's last item
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. 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 commit the last ruling or scoring run on the default branch read. The human chose it 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. 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, for the same reason. 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 reads from the commit measured before the first. 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
@@ -119,7 +119,7 @@ lilleman decided to ship each of these under the floor on the day listed. Each l
## reading cost: larv-review measures each finished chunk from loop-claude's archive and appends the figure to `docs/reading-cost.md` in the next chunk's PR
2026-10-08, lilleman. Serves goal 1.1: comprehension measured from real work, at no model cost (goal 1.4). loop-claude archives from the main checkout, outside any PR, so a tracked file it wrote there would dirty that checkout. So `bin/reading-cost` measures each finished chunk `docs/reading-cost.md` lacks from the archive, in the next chunk's worktree. A PR that never merges then loses no figure, and loop-claude needs no change. The figures keep a file of their own, so `docs/comprehension-history.md` keeps one writer, the scoring run. Serves goal 4 by naming only files git tracks, and token counts. Rejected: loop-claude opening a PR of its own, one more PR per chunk and a tie to the forge; the worker measuring its own transcript before merging, which misses the chunk's tail. The figure counts new input tokens, uncached and cache-written, because workers read mostly through Bash and subagents, where parsed paths alone miss what they read. Valid while loop-claude archives every finished chunk with its subagents' transcripts.
2026-10-08, lilleman. Serves goal 1.1: comprehension measured from real work, at no model cost (goal 1.4). loop-claude archives from the main checkout, outside any PR, so a tracked file it wrote there would dirty that checkout. So `bin/reading-cost` measures each finished chunk `docs/reading-cost.md` lacks from the archive, in the next chunk's worktree. A PR that never merges then loses no figure, and loop-claude needs no change. The figures keep a file of their own, so `docs/comprehension-history.md` keeps one writer, the comprehension check. Serves goal 4 by naming only files git tracks, and token counts. Rejected: loop-claude opening a PR of its own, one more PR per chunk and a tie to the forge; the worker measuring its own transcript before merging, which misses the chunk's tail. The figure counts new input tokens, uncached and cache-written, because workers read mostly through Bash and subagents, where parsed paths alone miss what they read. Valid while loop-claude archives every finished chunk with its subagents' transcripts.
## reading cost: a rise is the last 5 chunks' median above the 5 before them, and files or refreshes one plan item
+2 -2
View File
@@ -76,11 +76,11 @@ In the opening, Bash also allows `git -C {base checkout} ls-files`.
```
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.
Depth 1, the whole project in both versions: read README.md, AGENTS.md and CLAUDE.md (the charter), then every non-test tracked file. A file the newer version does not change is the same in both, so read it once, at {checkout}: {files}. These files differ; read each in every version that holds it:
Depth 1, the whole project in both versions: read README.md, AGENTS.md and CLAUDE.md (the charter), then every non-test tracked file at {checkout}: {files}. These files differ between the versions; read each at {base checkout} too, where it exists there:
{changed}
Do NOT open todo.md, docs/decisions.md, docs/comprehension-history.md or docs/reading-cost.md (the plan, the decision log, past panels' rulings and past chunks' reading cost), nor any review output. You may open a test file when the code does not answer a question; say when you did.
Your harness pre-loads these files into your context before your first tool call, from a THIRD version (main): {preloaded}. Treat the two worktrees' own copies as the ones under review. A pre-loaded AGENTS.md may list decision titles; do not use them as evidence.
Your harness pre-loads these files into your context before your first tool call, from main, which may match either version or neither: {preloaded}. Treat the two worktrees' own copies as the ones under review. A pre-loaded AGENTS.md may list decision titles; do not use them as evidence.
No running anything, no builds, no tests, no edits of any kind.
+3 -3
View File
@@ -88,8 +88,8 @@ Then the principles audit: one principles-auditor for the README's goals, and on
Then the comprehension check. Simulated readers each read the whole project, not the diff. Launch them per `~/.claude/skills/comprehension-panel/SKILL.md` → "The scoring run" and "The paired ruling".
- **Paired ruling**, in every architecture pass. Mid A and the inherited architect each read the project at the merge base of this branch and the default branch, and at this branch's head, and vote whether it reads better, the same or worse at the head. A ruling is settled once it holds two votes more than every other ruling. Until then add the maintainability senior, then Junior A. Four seats without a settled ruling rule same.
- **Scoring run**, only when the chunk ships its release's last item. 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.
- **Paired ruling**, in every architecture pass. Mid A and the inherited architect each read the project at a base commit and at this branch's head, and vote whether it reads better, the same or worse at the head. The base is the commit the last entry of the history (below) on the default branch read, so the ruling covers every chunk since then. Where that history holds no entry, or its commit is not an ancestor of the head, the base is `git merge-base origin/<default branch> HEAD` after a `git fetch`, or `<default branch>` with no remote. Two votes that agree settle the ruling. Otherwise the maintainability senior and Junior A vote too, launched together: a ruling holding two votes more than every other ruling settles it, and four votes without such a lead rule same.
- **Scoring run**, only when the chunk ships its release's last item, leaving `todo.md` with no item for that release. 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:
@@ -102,7 +102,7 @@ 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, appended and never edited. Each opens with a `## <UTC time, ISO 8601>, <PR or branch> at <commit>` heading naming when the seats finished and the commit they read; a paired ruling's heading ends `, against <merge base>`. A paired ruling holds a `Ruling: <better, same or worse>` line, a table of each seat's vote, and under each seat, labelled `<seat>, decided by:`, its places. A scoring run holds a table of each seat's five scores, with a last row holding the four seats' mean of each, and under each seat, labelled `<seat>, hardest first:` or, for the architect, `<seat>, would restructure first:`, its places. A place is `path:line` and the unit's name. 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, appended and never edited. Each opens with a `## <UTC time, ISO 8601>, <PR or branch> at <commit>` heading naming when the seats finished and the commit they read; a paired ruling's heading ends `, against <base>`. A paired ruling holds a `Ruling: <better, same or worse>` line, a table of each seat's vote, and under each seat, labelled `<seat>, decided by:`, its places. A scoring run holds a table of each seat's five scores, with a last row holding the four seats' mean of each, and under each seat, labelled `<seat>, hardest first:` or, for the architect, `<seat>, would restructure first:`, its places. A place is `path:line` and the unit's name. 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: 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.
+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 floor's scoring run; say so in the report.
- Skip the comprehension check, both the paired ruling and the scoring run; 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.