128 KiB
Decisions
bin/: an outcome is an entry of a .outcomes.md file in loop-claude's archive, a record is a document tools or people keep entries in, and a place is what a comprehension seat names
2026-10-23, larv-review, through PR #367. Serves code health: a reader can trust that one word names one thing in every tool. Before, "record" and "outcome" each named different things in three modules, and "place" in two. Each word kept the meaning it already had where renaming costs most:
- An outcome: the archive's file names end in
.outcomes.md, and the tools that read them find them by that suffix. score-outcomes'OutcomebecameResult, and rule-hook's becameChecked. The commandscore-outcomeskeeps its name, since renaming it would be a change of its own: files every project loads, such asrules/todo-items.md, name it, and so do decision titles. Its help and report keep the word its name uses. - A record: "judge's records" is a term in
~/.claude/CLAUDE.md→ "Vocabulary", and reading-cost's help calls its file a record. A single item in such a document is an entry; the route the archive keeps is a worker line (Route.worker_line). The verb "to record" keeps its plain meaning. - A place: the comprehension panel's term, also in the Vocabulary. reading-cost's
Reading.places, how often each file was read, becameReading.files.
Valid while the archive's file names, the Vocabulary and the panel keep these words.
bin/: the tools run on the host's Python, with no container, and so do their tests outside CI
2026-09-24, larv-review. Serves goals 1 and 2. The tools drive the host's claude CLI and read the host's session files, which a container cannot see; the tests run on the same host Python the tools meet. The tests also run in a container through ci.sh, on CI and to reproduce a CI failure, since they drive no claude (the entry tests: CI runs the suite through ci.sh). Valid while claude runs on the host.
bin/: the tools support only the latest stable Python, and the tests, written in plain unittest, run on it in four pytest-xdist workers
2026-10-28, lilleman, through todo item 245. Serves goal 1.5: the suite gates every chunk. The suite took 198 s, 102 s of which went to rerunning it on the oldest Python README Install named, 3.11. README Install now asks for the latest stable Python as python3, and mypy checks every tool under bin/ for the version Install names. README's Test line runs the tests in four pytest-xdist workers through uvx: 29 s on a 16-CPU machine. Four is one heavy slot's CPUs, CPUS_PER_SLOT in bin/machine_load/slots.py, so a gate under run-heavy loads only the slot it waits for. The line pins pytest and pytest-xdist, as test_types.py pins mypy, so every machine runs the gate the same way. It passes the path of python3, since uvx --python python3 picks a Python uv installed itself, which may be older. The tests use stdlib unittest alone, and pytest only runs them, so plain python3 -m unittest runs the same tests one at a time and another runner can replace pytest. Valid while every machine taking the checkout gets the latest stable Python soon after its release.
chunks: a chunk takes every unblocked item of its release that fires the same review passes, whatever its purpose, and an item above R 5 ships alone
2026-10-22, lilleman, through todo item 217. Serves goal 1.4: each review has a fixed cost, so more items per chunk cost less per item. Across the 165 finished chunks loop-claude archived up to that day, a chunk took a median of 1.30M tokens with one item and 1.33M with two, and three in four chunks shipped one item. The old rule also asked one PR title to state what the items achieve together; lilleman dropped it, since unrelated items that fire the same passes cost one review.
The cap is 5, bin/release_plan/todo_table.py's BUNDLE_MAX_R, from the same chunks: by the highest R among a chunk's items, the median was 0.9M to 1.5M tokens at R 1 to 5, and 2.7M at R 6, where the 90th percentile was 8.8M. A risky item that runs long re-runs review over every item bundled with it. R 5 is also the least R an I 4 item gets, so an item that could take everything down shares a chunk only where its L + E is 3 or less, and an irreversible I 5 item, at R 7 or more, never does. Valid while a review's cost is mostly fixed per chunk; revisit once 30 chunks have shipped bundles under it.
comprehension floor: every dimension and the overall at 7.0 or above is the target, and blocks no merge or release
2026-09-27, lilleman, restating the 2026-09-24 target and extending it to the overall. Serves goal 1. 2026-10-13, lilleman: the floor blocks nothing, and review: the comprehension check records … says why. Valid while the scoring run keeps its four seats.
deploy: ~/.claude holds only a release, which deploy-release moves it to; this repo is developed in ~/code/claude-config, where loop-claude runs its chunks like any project's
2026-10-29, lilleman. Serves goal 1.3 and goal 2. ~/.claude was this repo's development checkout, so every merge reached every session on the machine at once, its unfinished work included, while other machines took only tags. Now each machine takes only releases: what a release holds is what every session runs, and cutting one is the human's step that ships it. deploy-release automates README → Update. It refuses an uncommitted change to a tracked file that the new tag doesn't hold, such as a hook Claude Code wrote into settings.json, and a move that would drop commits no release holds; a model pick, which the clean filter drops, is no change. Valid while Claude Code reads its configuration from one directory per machine.
deploy: deploy-release --cut cuts a release through a pull request merged fast-forward only, then tags the merged commit and moves ~/.claude to it; the human runs it
2026-11-08, lilleman, todo item 271. Serves goal 1.5 and goal 2. Nobody can push to main on the remote, and it merges only by fast-forward, so a cut that commits on main and pushes no longer works. The tool cuts only the release chunk-preflight would call ready to cut, through bin/release_plan/release_standing.py, so the two never disagree on which release is next or whether it is ready; the version is that release's, never the tool's choice. It builds the cut commit in a worktree of its own, so the clone's checkout stays as it is. It finds the merged commit on main by its title, Cut release <version>, since GitHub's nearest merge, a rebase merge, may give the commit a new hash. It takes only a pull request from origin's own branch whose head is the commit that branch points at, and has the forge merge it only while its head is still that commit, so a fork's pull request from a branch of the same name, or a push after the checks passed, is never merged and deployed. Each step first checks whether an earlier run did it, so a rerun continues. Releases stay the human's, so the human runs it, and the forge credentials stay theirs. Valid while main takes changes only through a pull request.
larv-review: within a chunk lifting a project towards the comprehension floor, work on the project's lowest-scoring dimension comes first, and the floor doesn't block anything
2026-09-20, lilleman. Serves goal 1. Across six projects scored with the four seats, Locality or Self-sufficiency was the lowest dimension at every seat and Navigation at none, so a layout fix would not lift a project under the floor. Valid while the scoring run keeps those four seats.
2026-10-15, lilleman, set by PR #283 on 2026-10-16: an item that lifts the lowest dimension moves each goal it cites by 9, since the lowest dimension caps the overall and lifting it is worth the most to the floor. Within a chunk its work comes first; in the plan, lilleman answering that PR's review, such items compete with the others like any item and don't rank first. PR #257's scoring run found Shape lowest, at 6.25, and two items were to lift it: one, shipped by PR #367, gave "record", "outcome" and "place" one meaning each in bin/; the other, shipped by PR #432, grouped bin/'s root modules into packages named by purpose. Release 0.3.0's scoring runs found Locality lowest, at 5.75 and 5.88, so the 9 moved from those items to the ones lifting Locality.
2026-11-08, claude, item 230: the floor item that larv-review files (skills/larv-review/SKILL.md → "Floor item") keeps the move by 9 and competes like any item, though its R, likely above 5, makes it ship alone.
loop-claude: a claude that cannot start is a failed worker run, retried
2026-09-28, larv-review, declining a product-owner nit to exit at once when claude is missing. Serves goal 1. Claude Code's updater repoints ~/.local/bin/claude at each new version under running loops, and a start that meets it mid-update fails with the same error as a broken install; the retry costs two minutes on the second and saves an unattended loop on the first. Valid while Claude Code updates by repointing its link.
loop-claude: a judge decides each interrupt and each quoted answer from the transcript, the README's premises, AGENTS.md, docs/decisions.md, ~/.claude/CLAUDE.md, ~/.claude/rules/ and larv-review's standards, and holds a chunk open while an answer the human typed in it is recorded nowhere; it interrupts for a reserved choice those don't settle, or an ask that carries no recommendation
2026-09-21, lilleman. Serves goal 1. Asked to name the goal behind each choice, the worker cites a real goal for a choice that goal does not settle, and under-reports its own decisions; the judge's bar is whether the README's premises or the files in the title discriminate between the alternatives. Valid while the worker's self-report stays unreliable. Since 2026-11-08, below, that bar holds only for a reserved choice and an ask without a recommendation.
2026-10-03, lilleman. Serves goals 1.2 and 1.4. When the README's premises or those files answer the worker's question, the judge quotes the answer verbatim and the worker resumes with it, so an answer recorded there is not asked again. The judge then sees the quote as a [loop] line. The worker asking it again shows the quote did not settle it, and the judge sends it to the human. A backstop of three quoted answers per cycle bounds what the judge misses, such as a reworded repeat or a worker asking without end, so the worker cannot loop unattended: the fourth question that the README's premises or those files answer in one cycle goes to the human with the judge's quote. An interrupt does not reset the count, so every later question they answer in that cycle also goes to the human. Valid while the worker writes records only in a worktree, as CLAUDE.md → "Working with the codebase" has it, so the records the judge reads from the checkout root are merged ones.
2026-10-03, lilleman. Serves goal 1.2. The judge reads ~/.claude/CLAUDE.md, each file under ~/.claude/rules/ and each file under ~/.claude/skills/larv-review/standards/ whole. The worker follows them, so a question they answer should not reach the human. Reading whole is safe, because the judge may quote only words that appear in them, and a list of sections would need keeping current.
2026-10-03, lilleman. Serves goal 1.2. The judge rules a chunk finished only once every answer the human typed in it is recorded. A finished chunk's session is deleted, and its answers with it, so an answer recorded nowhere would be asked again in a later chunk. Claude settled two choices lilleman's ruling left open. First, an answer counts as recorded where the files the judge reads hold it, ~/.claude/CLAUDE.md included, or where the transcript shows the worker writing it into README.md's premises, AGENTS.md, docs/decisions.md, todo.md or a code comment. A worker's write to ~/.claude/CLAUDE.md, ~/.claude/rules/ or ~/.claude/skills/larv-review/standards/ does not count: the judge reads the live ~/.claude, which holds the write only once it merges and the checkout is pulled. The judge cannot read a code comment or todo.md. Yet CLAUDE.md → "Working loop", "Ask, don't guess" puts a standing choice made in one place in a comment there. And the human's approval of a release's items, which "Working loop" requires, is the set of rows todo.md names for that release. The judge also reads the records once a cycle from the main checkout. That checkout may not yet hold an answer the worker wrote and merged. A judge that refused any of these would hold the chunk open every cycle. Second, only an answer a later chunk could need must be recorded, so an approval such as "merge it" holds nothing open. The worker's resume prompt states the rule, so a worker whose chunk is held open knows it.
2026-10-17, lilleman, todo item 168. The human answers an interrupt on loop-claude's terminal, and the worker resumes headless with the answer in a -p prompt. The judge reads that answer as a [human] line, not a [loop] one, so it holds the chunk open until the answer is recorded, as it does for an answer typed in claude.
2026-11-08, lilleman, todo item 262. Serves goals 1 and 1.5. A worker takes its own recommendation on a choice no rule reserves for the human, and records it. CLAUDE.md → "Working loop", "Ask, don't guess" names the three choices always reserved, and keeps any other rule's ask for approval. The worker's account of which goal settles a choice still doesn't decide a reserved one. The judge no longer interrupts for an unreserved choice the worker took, or asked about with a recommendation; it answers such an ask by quoting that rule, which it may quote again for each new ask. 92 of the 255 interrupts in loop-claude's archive on 2026-11-08 carried the worker's recommendation, and a finished chunk with an interrupt took a median 7.1 h, against 0.44 h without one. Valid while the human reverses few of the choices workers take this way, goal 1.2's counter-signal.
loop-claude: every claude it or loop-inbox opens on a terminal has CLAUDE_CODE_SANDBOXED set, so Claude Code skips its trust dialog, and neither tool writes ~/.claude.json
2026-09-21, lilleman. Serves goal 1. claude --resume re-enters the worktree the worker last entered, recorded in the transcript's worktree-state entry, and Claude Code asks trust per path, so trusting the checkout alone would still land the human in the trust dialog.
2026-10-30, lilleman, todo item 6. Serves goal 1. Until then loop-claude marked each worktree trusted in ~/.claude.json, reading the file, changing it and writing it back. Claude Code owns and writes that file, so a write it made in between could be lost. Claude Code 2.1.314 treats every folder as trusted while CLAUDE_CODE_SANDBOXED is set, and doesn't persist that trust. A claude started in a new folder with the variable set showed no dialog, and Claude Code recorded the folder untrusted. hand_over sets the variable for every claude it opens on a terminal: for /talk, a release ready to cut and the routing calls. The variable tells Claude Code it runs inside a sandbox, which holds here: loop-claude runs only in the sandbox README → Install names (loop-claude: every claude it starts bypasses permissions inside its sandbox). Claude Code doesn't document the variable. Where a later version drops it, the trust dialog comes back on those claudes, and nothing is lost. Valid while Claude Code honours CLAUDE_CODE_SANDBOXED.
loop-claude: each project's model lives in ~/.claude/loop-claude-models.json, which only loop-claude writes
2026-09-26, lilleman. Serves goal 1. Claude Code rewrites the user settings' model whenever one is picked inside a session, so a loop reading settings runs whatever was picked last; ~/.claude/loop-claude-models.json has loop-claude as its one writer, and every claude it starts gets that model as --model. The file is per machine, outside the synced allowlist, since a tracked file the loop writes would dirty the checkout. 2026-10-02, lilleman: goal 2 shares the setup across machines, and a project's model is each machine's own choice, so a new machine asks once per project, which is not asking the same thing twice (goal 1.2). Valid while Claude Code keeps rewriting the settings' model from inside a session.
loop-claude: every claude it starts bypasses permissions inside its sandbox
2026-09-30, lilleman. Applies "Always grant explicit access to data": the sandbox loop-claude runs in is where access is granted, so the worker and the claude an interrupt opens run with bypassPermissions. The worker may read ~/.claude/.credentials.json: it holds Claude Code's own credentials, which claude reads to run anyway. Its one seam to production is the forge: what it pushes or merges can publish through CI. Valid while loop-claude runs only in the sandbox README → Install names.
loop-claude: one session per project, its id derived from the checkout's path relative to ~/code, or to / outside it
2026-09-21, lilleman; revised 2026-09-30 by lilleman. Serves goal 1. One fixed id per project keeps the session picker at one entry per project and makes any transcript under that id loop-claude's own to delete. A checkout outside ~/code mirroring a path inside it shares that id, and a second loop on it is not refused. Once todo.md item 5 lands, the id comes from the full path, so no two checkouts share one, and loop-claude refuses to start while another session on that id is active. Moving the checkout orphans its open sessions, archive folder and models entry: sessions stay in the picker until the human deletes them, migration code not being worth a one-human audience. Valid while claude takes --session-id and resumes by it.
loop-claude: the archive keeps the raw transcript, and a failed archive stops the loop
2026-09-28, lilleman. Serves goals 1 and 3: saving each transcript locally is the first step of backing it up, and it shows afterwards what an unattended run did. A copy of the .jsonl, deduplicated by content hash, with its outcomes beside it; a rendering drops tool results, and a second-resolution stamp names two states within one second as one file. A failed archive exits 1, since a loop that loses its record silently fails the backup goal. Valid while transcripts stay small enough to copy whole.
loop-claude: the worker's claude compacts its context before it fills a 200k window, at about 170k tokens, and CLAUDE.md → "Compact instructions" says what the summary keeps
2026-10-27, lilleman's yes to claude's evaluation through todo todo item 231. Serves goal 1.4; its counter-signal, review rounds and unfinished verdicts per chunk, is the check.
loop-claude hands each worker's claude CLAUDE_CODE_AUTO_COMPACT_WINDOW=200000 (bin/loop_claude/cycle/worker.py), and the session /talk opens gets it too. Claude Code compacts before a window fills: a 1M window at about 967k tokens, and in a probe on 2026-10-27 a 100k window at 65k and 80k, so a 200k window compacts at about 170k. The window is not set in settings.json, since the archive measured loop-claude's workers and interactive sessions are lilleman's. Subagents inherit the variable, which reaches every process of the session: 68 of the 994 subagent runs since 2026-10-21, 7%, passed 170k, 24 of them principles auditors, so about one in fourteen compacts once. Compacting subagents by choice would cost more than it saves, as below, but the variable cannot leave them out, and CLAUDE.md → "Compact instructions" has a reviewer keep the findings it has drafted. That section shapes the summary: in another probe that day, a session whose CLAUDE.md asked for its summary to end with a secret word got a summary ending with that word. Path-scoped rules leave the context at a compaction and return at the next matching read, and rule-hook holds each review launch to its rung whatever the summary keeps. CLAUDE_CODE_DISABLE_1M_CONTEXT=1, handed the same way, would compact at the same point but also cap the window at 200k, so a run that Claude Code stops compacting, as it does when one tool result refills the context each time, would hit the limit instead of going on.
Why 200k. Item 231 asked for the best means to lower what a chunk spends on context, in dollars, then hours, with no loss of quality. Measured from loop-claude's archive, the 90 chunks with messages after the routing figures' reset of 2026-10-21 cost $1,215 at the list prices read on 2026-10-26 (Opus 5.5: $4 per million input tokens, $5 and $8 for 5-minute and 1-hour cache writes, $0.20 for cache reads, $20 for output; no model but Haiku 5.5 charges more above 200k). That is 0.86 of what the chunks' cost-state entries sum to, since some chunks' subagent transcripts are not in the archive. Worker main threads cost $375 (31%): 1-hour cache writes $149, cache reads $153, output $74. Subagents cost $840: 5-minute cache writes $379, output $274, cache reads $187, with the principles auditors at $274 over 342 runs, the stability reviewers $179 and general-purpose subagents $192. A worker starts at 41k tokens of context and peaks at a median 167k, one in ten past 358k, the largest at 848k. The worker's messages above 200k were 32% of its messages and 55% of its cost.
What reads cost, and whether a tool cuts them, measured at lilleman's ask after those figures: no tool cut a reviewer's reading without losing a finding, except a scout, which kept the stability reviewers' findings but lost the auditors' 🔴 and slowed every round; so none of them ships here. lilleman chose on 2026-10-27: workers trial a reading rule, reviewers get no scout, and the principles audit keeps reading the project whole. Every fresh worker prompt now holds that rule (READING_RULE in bin/loop_claude/cycle/prompts.py), and todo.md item 260 keeps or drops it. Two measures of reading: the characters a thread read, 93M in all, about 27M tokens; and the new input tokens of the messages that took results in, charged to those results, which also count what arrives beside a result, such as the agent's own previous reply. By the second measure tool results caused $620 of the $1,215, and reads (Read, Bash reads, Grep, Glob and git's diff, show and log) $537 of that: the worker's reads $140 (Bash reads $115, Read $12) of its $190 of results, the principles auditors' $133 (Read $109, Grep $22) of $139, the stability reviewers' $97 (Bash reads $79) of $106, general-purpose subagents' $84 of $97, the prose reviewers' $32, the architects' $30 and the product-owner reviewers' $21. By the first measure the worker's reads are about $45. Precision is low everywhere: of the characters a principles auditor read, 13% were in a file its report names; a stability reviewer 8%; a prose reviewer 18%; an architect 11%; the worker 4% in a file it later edited. Reading is mostly to find things and to learn what a project holds. The worker's sed ranges are small, median 25 lines, one in ten over 80. Of the worker's read characters, 49% were of a file it had read earlier in the thread: 36% within three messages, paging through it, and 13% later, with the file unchanged, about $6 of the $45; a reviewer's later reads of an unchanged file it had read are 1 to 2%. rule-hook's repeat-read now blocks a read of lines already in context.
The trials: four stability rounds and five principles rounds archived on 2026-10-23, each holding 🔴 or 🟡 findings, replayed on the project's rung as review-replay replays them, with the reviewer's definition changed through --agents; and three worker-like tasks, a search, a rename and an explanation, run on fresh clones at the project's rung. The baseline, the reviewer as it is, found 4 of its own 6 archived findings in each pass, so a variant that finds 4 or 5 of 6 does what the same reviewer does twice. The options todo item 231 named, each simulated on the 90 chunks and, where lilleman asked, tried:
- Compaction of the worker. The saving and the compactions per chunk, by the point it compacts at: 150k saves $75 at 1.0 compactions; 167k to 180k, where a 200k window compacts, $77 to $78 at 0.8 to 0.7; 200k $78 at 0.5; 300k $54 at 0.2. $78 is 21% of the workers' $375 and 6% of all spend. Compaction also caps the 36 re-writes of a whole context after a gap longer than the cache's hour or a change of rung: they cost $61, up to 785k tokens each, and would cost about $34. Compacting subagents at 150k costs more than it saves, since a compaction reads the context once more and writes a summary, and subagents are short.
- A fresh context for the review phase, handed 60k tokens of facts, saves $39. A compaction at 170k saves that too, and loop-claude would need a second session per chunk.
- Read with an offset and a limit, or Grep, in place of
cat,sedandhead. Steering the tool would not change how much is read: the worker'ssedranges are small already, and only 13% of its Bash-read characters came from whole files. A rule on how much to read did change it: under "never read more than 80 lines of a file at once, nor take a tool output over 3,000 characters into your context", the three worker tasks read 45% to 60% fewer characters at the same or lower cost, every task done as well, and the rename was the one run of four that also kept the import names sorted. A stability reviewer under the same rule with anoutlinescript on PATH, which prints a file's symbols with their line ranges, read 4% less and found 2 of 6 findings, and the workers never ran the script. - Code-intelligence tooling: the
LSPtool, through a pyright plugin built from the marketplace manifest withpyright-langserveron PATH, answers a file's symbols, a definition or the references in a few hundred characters. Under a rule telling them to use it, the stability reviewers and the workers never called it; the auditors did, read as much or more, and missed the one 🔴, 0 of 1 against the baseline's 1 of 1. Each machine would also need a server per language (goal 2). Not worth an item. - A cap on tool results. Claude Code caps a Bash result at about 30k characters already. A PostToolUse hook capping it at 12k, which
updatedToolOutputallows, left the stability reviewers 3 of 6 findings, two lost in one round. Read results, 59.9M characters in subagents' threads with 58% of their characters in results over 12k, are out of such a hook's reach. Not worth an item. - A scout: Haiku 5.5 reading raw content, whole files or long output, and returning facts as path:line and the ranges worth reading, so the agent's own context holds the summary and the chosen lines. In session, as an agent under
agents/, its first request writes 37k tokens, $0.005, and a read of a 38KB file costs $0.008 in 8 seconds. As a slim headlessclaude -pwith its own system prompt, no setting sources and no dynamic sections, which keeps the subscription login, it starts at 6k tokens and $0.0003 in 3 to 5 seconds, its prefix cached across calls, and the same read costs $0.004 in 7 seconds; a direct API call andclaude --bareneed an API key, so they are out. Stability reviewers with the agent scout found 5 of 6 findings and read 29% fewer characters at 6% less cost and 14% more time; with the CLI scout 4 of 6, 38% fewer, 17% less and 39% more; the auditors with the agent scout 3 of 6, the 🔴 among the lost, at the same cost and twice the time. Workers offered the scout never called it. - What a reviewer reads: the auditors read the project whole by design. Of their 🔴 and 🟡 findings since the reset, 47% named a file the chunk edited and 51% another file, so reading only the change would drop half of them (
review: the principles audit runs only in the release review, and reads the project whole with one auditor checking the goals and every principles file that applies). - The base context: every thread starts with
~/.claude/CLAUDE.md(19k characters),~/.claude/AGENTS.md(11k, this repo's decisions, which Claude Code loads as user instructions into every project's sessions), the project'sAGENTS.md, and, for the worker and general-purpose subagents, the skill listing (18k) and the agent listing (12k). Subagents' first messages wrote $97 of it. Trimming the listings would save about $20, 2%, and is not worth an item:disableBundledSkillswould also drop/security-review, the security pass of record.
Quality. Under the 200k window, every figure's mean per chunk fell. Measured on 2026-11-04, the first 20 chunks whose worker started under it, from 2026-10-28, took a mean 4.0 review rounds past each pass's first against 5.8 for the 20 before them, from 2026-10-23 to 2026-10-26; 0.20 unfinished verdicts against 0.30; 1.15 🔴 against 1.90; 11.9 🟡 against 19.4; 0.11 misread findings against 0.25; $22 against $34; and 9.6 hours against 42. Only the median dollars went up, $15.17 against $11.72: the 20 before held four chunks of $94 to $167, and the 20 after none above $76. This decision weighs all spend, so the mean is the figure that counts. The two groups also differ in projects and routing, so how much of the fall the window caused is unknown. Before the window, 19 chunks compacted between 2026-10-10 and 2026-10-22, at the compaction points Claude Code set then, 214k to 972k tokens. Per 100 worker messages they took a median 3.6 review rounds past each pass's first against 4.0 for the 68 uncompacted chunks of 100 messages or more, and 13.9 🔴 and 🟡 findings against 16.6. 4 of 19 had an unfinished verdict against 3 of 68, each 8 to 10 hours after the compaction and followed by a finished verdict within minutes; in those four verdicts the judge quoted the worker's own passages and the human's typed answers, never a summary. One cause was possible and is closed here: Claude Code writes the summary as a user entry, which bin/claude_code/entries.py read as the human's words, so the judge would see a [human] line of thousands of words and /talk would count it as typed; it now reads as Claude Code's. Two summaries read whole kept the chunk's intent, files, errors and next step in 12k to 20k characters, and the worker resumed without re-reading.
Hours. A chunk ran a median 0.7 hours from its first message to its last, one in ten past 12 hours, mostly waiting for the human or a usage limit. No option here changes that: a compaction takes 51 to 83 seconds, under a minute per chunk at 0.7 each, and a smaller context saves seconds per turn at most. Waiting on subagents took 66% of a worker's active time, so the hours lever is launching a round's reviewers together: larv-review §3 → "Waves" now launches each wave's reviewers in one message.
Valid while cache reads cost a twentieth of input and Claude Code's compaction keeps the worker's task.
loop-inbox: a loop-claude lists itself while it runs, and its waiting question, as files per session under ~/.local/state/loop-claude/, and takes the first answer, from its terminal or from loop-inbox, that names that question
2026-10-28, lilleman, todo item 243. Serves goal 1. With several loops running, each asked on its own terminal, and the human searched the terminals for the ones that waited. loop-inbox lists every loop's interrupts, the routing calls included, oldest first, and the human answers each one there. A loop asking for its project's model, as on a project's first run, asks on its terminal only: the human has just started it there, and no worker session exists yet. bin/loop_state/waiting/ holds the protocol:
- An answer reaching the wrong loop is the worst failure. Each answer names the question it answers by a fresh id, so an answer meant for an earlier question, or sent as the terminal answered, never answers a later one.
/talkfrom loop-inbox waits for the loop to stop reading its terminal before claude opens, so only one claude holds the worker's session.- While claude is open for a question, as for a release ready to cut, the routing calls or a
/talk, loop-inbox lists the loop and where claude is open, but takes no answer for it. - loop-inbox runs the claude command the loop wrote,
bypassPermissionsincluded, so that claude runs in the same sandbox as the loop. Since loop-inbox runs a command read from a file, the folder is private to the user. - Files, read by polling, need no daemon and only the standard library, and a loop with no loop-inbox running is answered on its terminal as before.
- loop-inbox lists a question only while its loop holds the session's lock file with flock, and removes a question whose lock is free. The loop holds the lock for its whole run. The kernel frees the lock however the loop ends, killed included. A process id could not tell a running loop from a killed one: on 2026-10-29 this machine's kernel handed out its 32,768 ids again every 30 to 75 minutes, so a killed loop's question came back whenever another process got its id. The lock file stays once the loop ends, one per project: removing it while another process has it open could let loop-inbox lock a file no loop holds. PR #396.
- A loop also lists itself as running, with the items its chunk takes, in
<session>.running, under the same lock: one lock tells loop-inbox both that the loop runs and that its question stands. The judge names the items the worker took in, as an array of IDs in its reply'sitems_taken_in. PR #397.
A bench of three readers seated as the README's audience picked the name loop-inbox, 3–0.
Valid while every loop and loop-inbox run on one machine under one user's home.
machine load: a heavy command waits for one of the machine's heavy slots, one for every 4 CPUs, which every session shares, and loop-claude starts a worker only while at least a quarter of the machine's memory is available
2026-10-23, lilleman. Serves goal 1.5. On 2026-10-22 ai-sandbox, with 8 CPUs and 16 GiB, thrashed for hours: four to six loops ran mutation tests, full gates, docker builds and QEMU-booting e2e tests at once, and nothing told one loop how busy the machine was. lilleman chose both limits; no standard sets either, and GNU parallel's --memfree, which does the memory wait's job, has no default. A slot is a file lock, so a session that dies frees its slot. The memory wait reads /proc/meminfo only, and off Linux a worker starts at once. bin/machine_load/ holds the slots and the memory share, bin/run-heavy takes a slot, CLAUDE.md → "Working with the codebase" has every session use it, and loop-claude's worker waits for the share. rule-hook's rule run-heavy blocks a docker build, and a run of a mutation tool stability-reviewer names, outside run-heavy, in the forms its checked text in bin/rule_hook/rules.py lists. 2026-11-04, lilleman: other forms, such as uv run mutmut run or sudo docker build, pass until one becomes a problem. No program can tell a gate script from a light one, so only CLAUDE.md asks a session to run a gate under run-heavy. Valid while one machine runs several loops at once.
machine load: every container a session starts has a memory limit and a swap limit as large as its work needs; rule-hook's docker-run-memory blocks a docker run or docker create without them outside run-heavy, under which a container that lacks them gets the slot's share of three quarters of the memory; and no daemon-wide cap limits all containers together
2026-10-24, lilleman. Serves goal 1.5. On 2026-10-23 ai-sandbox, then with 8 CPUs and 7.6 GiB of memory, hung until a hard reset, although its one heavy command held a slot. Beside that mutation run, a reviewer's stress probes ran in docker run with no memory limit, each to 2 GiB. A limit makes a runaway container fail alone instead of taking the machine with it. A swap limit is needed too: without one, docker lets a container swap as much again as its memory limit, and swapping is how the machine hung. The session sizes both limits, since lilleman wants a project to run heavier work where it needs to. rule-hook reads only the docker run and docker create in a session's Bash commands. A container a script starts is out of its sight, and so is a compose service, whose limits live in its compose file. CLAUDE.md → "Working with the codebase" asks a session for limits there.
The heavy command in that hang started its container from the project's own script, out of rule-hook's sight. So run-heavy puts its own docker, bin/run_heavy/path_entry/docker, first on its command's PATH. That docker gives each docker run or docker create that lacks a limit the slot's share. The share is what a worker's quarter leaves: three quarters of MemTotal, split evenly across the slots. A container that sets one of the two limits keeps it, and gets the other as large, since docker refuses less swap than memory; an unlimited swap, --memory-swap -1, gives way. run-heavy cannot place the command in a cgroup instead: none is delegated to the user, and dockerd starts the containers outside the command's process tree. A compose service, and a docker named by its full path, keep no cap.
A daemon-wide cap would see every container: dockerd's cgroup-parent, given a memory limit. lilleman turned it down, since it is host config and would cap a project's heavy work too. Valid while sessions start their work in containers on a machine they share.
principles: about seven things per level, four or five where they act on each other, more where a reader finds them by name; crossing a limit asks for a grouping or a recorded reason
2026-10-22, lilleman asked for a rule of seven that holds at every level and is never a hard rule. Serves code health: a reader new to the project should take in each level at once. The numbers follow the sources below, since no single study sets them.
- Seven is Mark Seemann's figure in Code That Fits in Your Head (2021). He says the exact number matters less than having a limit the team agrees on (Tech Lead Journal #89). The 24 lines of 80 characters are his too (The 80/24 rule).
- Four or five for things that act on each other: working memory holds about four chunks once rehearsal and grouping are blocked (Cowan, "The magical number 4 in short-term memory", 2001). Sandi Metz's rules allow four parameters, and Fowler's long-parameter-list smell starts at three or four.
- More for things found by name: a reader recognises an item in a list, so a list's length is no memory limit (Nielsen Norman Group, Short-term memory and web usability). Menu studies find depth costs more than breadth, and broad levels of 16 to 64 items beat narrow ones when their labels are clear (Larson & Czerwinski, 1998; Dix et al., menu breadth).
- A split must save more than it costs: in an eye-tracking study, extracting methods cut reading time on hard tasks and raised it on simple ones (a 2026 preprint with 32 novices, arXiv 2602.18579). John Ousterhout's deep modules and John Carmack's case for inlined code argue the same against splitting by size.
- A grouping or a recorded reason, never a split at any cost: no study supports a fixed cut-off for function length, parameter count or nesting. Re-analysis of the cited data finds no optimal function length (Derek Jones, 2023),. So a limit holds only while the comprehension panel's readers find the code it flags hard, and
agents/systems-architect.md→ "Fits in a head" says how its reviewer rates a unit past one.
Valid while the comprehension panel measures how hard a project is to read.
reading cost and score-outcomes: each waits for 10 finished chunks before it shows a median
2026-10-16, lilleman, confirmed when asked. Serves goal 1.2: the answer is written once, so the same question is not asked again.
score-outcomes shows a score's medians only where 10 finished chunks that each shipped one item hold an outcome for that score (ENOUGH in bin/score_outcomes/results.py). The reading-cost trend waits for 10 chunks measured since its last reset: the last 5 against the 5 before them (2 * WINDOW in bin/reading_cost/figures.py). Both stay at 10.
Valid while no published standard sets either number, the reading-cost window stays 5, and until lilleman sets another.
reading cost: a rise is the last 5 chunks' median above the 5 before them, and files or refreshes one plan item
2026-10-08, lilleman. Serves goal 1.1: comprehension never falls, so any rise counts. Per-chunk figures are noisy: a flat trend rises about every other chunk. So a rise refreshes the item and never refiles it, and a chunk that sees no rise leaves the item as it is. The chunk that ships the item resets the trend, so later figures do not refile it for work that chunk already did (goal 1.4). A median, because one chunk that ran a panel of readers before its first commit measured 2.99M tokens against a typical 80k–370k, and a mean let it decide the trend alone. No published standard sets this threshold. Valid while figures arrive once per chunk.
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 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.
review: /security-review is the security pass of record, except where the full scan runs on the same change and replaces it
2026-09-20, lilleman. Serves goal 1.1. Its value is a tuned exclusion list and a ≥0.8 confidence floor, which a hand-written reviewer would reproduce worse. Valid while /security-review ships both.
2026-10-08, lilleman. Serves goal 1.4: run beside the full scan, /security-review started seconds apart from it each round and returned a near-identical report. Valid while the full scan covers what /security-review reports.
review: a fix for a 🔴 reruns the pass that found it, unless that pass is at its cap, and each pass whose row in larv-review §3's re-entry table the fix meets; from round 2 a pass reviews only the answers to its last round's findings and any other pass's fix that re-entered it; a fix for a 🟡, a 🟢, a ❓ or a prose finding reruns none
2026-10-08, lilleman. Serves goal 1.4. An audit of the four costliest archived chunks found nearly every finding that mattered in a pass's first round; when every fix, a nit's included, re-entered review, 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.
2026-10-13, lilleman through todo item 97. Serves goals 1.4 and 1.5. From round 2 a pass reviews only how the chunk answered its previous round, each fix and each dismissal with its reason, and reports only one that is plainly wrong or worse than the change it answered. A fix from another pass that re-enters it is still reviewed as a first round would review it, limited to its lines. Reviewing all that changed had a reviewer find new gaps in each round's fixes, so a pass ran to its cap. Valid while round-2 findings outside a round's answers keep changing nothing a user would notice.
2026-10-29, lilleman. Serves goals 1.4 and 1.5. A 🟡 fix no longer reruns its pass. One project's chunk on 2026-10-29, a README paragraph and plan rows, took 10 review rounds in 45 minutes, and three of its four second rounds answered only 🟡 findings, such as the wording of a question's options. Round 2 found 12 🔴 in about 200 runs since 2026-10-21, mostly in round 1's fixes of 🔴 findings, so a 🔴 fix still reruns its pass. A 🟡 fix that breaks something merges unreviewed by its pass; another pass whose row it meets for a 🔴 fix in the same round still reviews it. Valid while 🔴 findings in later chunks, fixing code a 🟡 fix wrote, stay rare.
review: a comment is prose in any file; a branch changing only Markdown no agent follows runs only the prose pass and, for README or docs an outside reader lands on, the product-owner pass; plan rows a chunk files from a finding, re-scores or moves get no review
2026-10-29, lilleman. Serves goals 1.4 and 1.5. One project's chunk on 2026-10-29 changed a README paragraph, todo.md and three lines of gate.yml, and the principles, security and stability passes all ran on it, each twice: 6 of the chunk's 10 rounds. A change to config is one that changes what runs, so a comment in it fires only the prose pass, as a comment in code already did. A branch that changes only Markdown no agent follows changes no code, config or tests, so no pass that reads those runs on it. A plan row a chunk files from a finding, re-scores or moves is read by the chunk that ships it, so reviewing it at filing reviewed it twice: that chunk spent a prose round of 4 minutes on its plan change. Markdown an agent follows, such as a skill, is config, since a change there changes what agents do. Valid while defects in prose-only chunks stay rare in later chunks' fixes.
review: a pass gets at most two rounds per chunk, and the release review's architecture and principles passes five, with no more and no ask for more; the fixes answering a pass's last round merge once the gate passes
2026-10-28, lilleman through todo item 246. Serves goals 1 and 1.4. One counter per pass per chunk, so no fix bounces between two passes without end. lilleman measured every repo's round titles since 2026-10-21. Round 1 ran 357 times and found 59 🔴. Round 2 ran about 200 times and found 12 🔴, mostly in round 1's fixes. Rounds 3 and later ran about 110 times and found no 🔴, at about $125 of review at list prices, and asks for a fourth or fifth round were 24 of the 59 interrupts. The cap had stood at three because a lower cap would ask the human more often; once nothing asks, that reason is gone. A rerun one rung up belongs to the round it reruns, so it doesn't count toward the cap: review: a reviewer or comprehension seat that rules the work below standard.
rule-hook's round-cap refuses a round commit that would take its pass past round 2, and no override waives it. It counts the pass's round commits on the branch as larv-review round-count does, so a third commit titled round 2 is refused too. The hook must not fetch, so it lists the branch's commits since the default branch as last fetched. It follows first parents, so the round commits that a merge of a newer default branch brought in don't count as this chunk's. It leaves out the commit an --amend replaces. Where git cannot list the branch's commits, within 5 seconds or because origin records no default branch, it counts the title's own number alone, so a slow or unset lookup doesn't block the commit.
Valid while the later fixes per finished chunk, which score-outcomes and the routing figures count, don't rise.
2026-10-29, lilleman: the release review's architecture and principles passes take five rounds, since they may refactor much of a project; the stability, security, overrides and prose passes on their fixes keep two.
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
2026-09-30, lilleman. Serves goal 1: a decision the chunk writes is the chunk's own and unreviewed, and an unattended run has no human to catch it. Valid while a pass is the only reader of a chunk before merge.
review: a project decision may opt every chunk out of the architect, the product-owner pass or the comprehension check, and a project opting out of the comprehension check voids code health
2026-10-11, lilleman. Serves goal 1.4. A research repo's PR, in a repo with no consumer for the product-owner pass and no product for the architect, spent rounds of both, and of the comprehension check, on a probe. The opt-out is the project's to make, and only an entry titled review opt-out: makes it, so a project without one is reviewed as before (goal 1.3). No opted-out reviewer works against a goal or a technical principle: the principles audit, which has no opt-out, still judges KISS and every other principle, so the entry names no plan item that ends it. 2026-10-13, lilleman: an opt-out of the comprehension check no longer ends with a chunk that ships an item naming the floor, since the floor blocks nothing. 2026-10-18, lilleman, answering the review of PR #324: a project that opts out of the comprehension check voids code health in its README too: without the check the goal has no signal, and, never measured, it would weigh four times its weight forever. rank_todo.py refuses the plan of such a project until its README voids it. Valid while the principles audit judges every chunk that changes code, config or tests, and while the architect's and the product-owner's findings matter only to a product with consumers.
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 compares with the commit measured before the first step. 2026-10-13, lilleman: the comprehension check blocks nothing now, so a suspension saves only the runs. Valid while such a decision names its items and the plan item that ends it.
review: a release review fixes its findings in the release it reviews, and files under that release only a finding that needs a human answer, adds a feature or outlasts its five rounds
2026-10-30, lilleman through todo item 258. Serves goal 1.1. fejkdata.dev's release review of 0.1.0 filed the architect's findings as items 28 to 36, in releases after 0.1.0, so the release the human was about to cut still held the drift the review had found. A release review's branch opens with an empty commit, so under larv-review §3 → "Findings" → "Outside the chunk" every finding lay outside its change and was filed. The review's whole point is to leave the release without the drift the release's small changes made, so the whole project is its chunk and the passes fix within their five rounds. Three kinds of finding are still filed, each under the release being reviewed, or under the earliest release rules/todo-items.md allows where that release's semver bump forbids it, such as a feature in a patch release: one whose fix needs a human answer, marked question; one whose fix adds a feature; and one whose fix the five rounds cannot finish. The release isn't ready to cut while one is open, so CLAUDE.md → "Working loop" calls a release finished only once its review has merged and it holds no item. Valid while a release review's rounds can fix what they find.
review: a reviewer or comprehension seat that rules the work below standard may ask to rerun once, one rung up, in the same round; the ruling that stands is an escalation trigger for the worker unless the fix changes only prose, and never for the judge
2026-10-15, lilleman asked for it through todo item 144, implemented by claude. Serves goal 1.1: a cheap reviewer that finds the work below standard can have a more capable one check that ruling, and work below standard gets a more capable rung to fix it, unless the fix changes only prose.
The work is below standard where systems-architect returns BLOCK, a reviewer reports a finding against larv-review's standards/quality.md, or record-ruling counts a comprehension seat's vote in a paired ruling as worse. That reviewer or seat may ask, and the worker then relaunches it on the rung loop-claude's prompt names, one above the rung it ran on. bin/loop_claude/cycle/prompts.py's reruns names it: the seats run on the project's rung, and the reviewers on the highest of the worker's rung and the one their item's E + I picks. Off the ladder, or for a reviewer or seat already on the top rung, the prompt names none, and its report stands.
A reviewer's relaunch gets the report that asked and confirms or dismisses each of its findings with a reason, so no finding goes unanswered; a seat's relaunch reads afresh, since a seat reports no findings. The relaunch's report stands in place of the one that asked, in the same round, so it adds no round, and a relaunch cannot ask again. So the round cap still bounds a pass, and one round launches a reviewer at most twice. The ruling that stands is the fourth escalation trigger in CLAUDE.md, except where the fix changes only prose: the worker fixes that on its own rung. lilleman ruled that on 2026-11-08 through todo item 276, after PR #432's two quality findings were false claims, one in a docstring and one in a sentence of this file. lilleman also ruled that no ruling raises the judge's rung, which routing: on a model judge-replay covered sets.
Valid while the ladder orders its rungs by competence.
review: a reviewer under agents/ marks a 🔴 or 🟡 [misread] where the implementer misread code that had already shipped, each round title counts the marked findings, and score-outcomes lists them per chunk
2026-10-23, claude. Serves code health (CLAUDE.md → "Shared goal"): its counter-signal, reviewers raising blockers because the implementer misunderstood the current system, had no count, since no tool recorded why a finding arose. The reviewer is the one that knows, so it marks the finding (skills/larv-review/review-findings.md → "Misread"). The worker counts the marked 🔴 and 🟡 findings in the round's commit title, Answer stability round 1: 1 🔴, 2 🟡 (1 misread); …, which score-outcomes already reads for the 🔴 and 🟡 counts, so the count needs no record of its own. rule-hook's round-title-counts refuses a round title without the count, or with more misread findings than findings, so a title that leaves the count out never reads as zero; titles from before the count read as unknown. Only the reviewers under agents/ mark findings. /security-review marks none, so its round titles count 0 misread, and the count is a floor. A bench of three readers seated as the audience chose [misread] right after the severity mark, which stays at a fixed place on a skimmed line, and the parenthesis (1 misread), which reads as a share of the 🔴 and 🟡 counts rather than a third kind of finding, each two to one. The other half of the counter-signal, defects that keep reappearing, is each chunk's later fixes, which score-outcomes lists after the misread findings. Valid while round titles are where score-outcomes reads a chunk's findings.
review: an ask no user answers leaves the PR unmerged
2026-09-30, claude. Serves goal 1: a BLOCK's restructure, Stage 0's questions and a goal conflict are the human's call, and an unmerged PR is what brings it to them; merging would make the call for them. Where an option reviews more — run the pass, fix a finding no goal lets the run decline — the run takes it; a ❓, or a fix changing a goal or a decision, is filed in todo.md, which reaches the human without holding the chunk. Valid while a human reads every unmerged PR an unattended run leaves.
review: each pass keeps a reviewer of its own
2026-11-09, lilleman asked for the trials. Serves goals 1.1 and 1.4. Merged reviewers were replayed on archived first rounds, beside the separate reviewers (reviewer-merge-trials/README.md). Each merge cost a third to a half less, and in each, one absorbed pass lost findings. Stability, product-owner and prose as one reviewer recovered 15 of 34 prose findings, against 22 and 23 for two separate runs. The architect and the principles auditor as one recovered 5 of 17 principles findings, against 10 for one separate run, and lost both principles 🔴. Stability and product-owner as one, run twice, recovered 4 and 5 of 16 product-owner findings, against 7 and 10 for two separate runs. Folding override-reviewer into stability had no data: no archived override round holds a 🔴 or 🟡. Valid until a new model joins the ladder or a reviewer's definition changes: replay the merge then, with the scripts in reviewer-merge-trials/.
review: each reviewer under agents/ writes its full report into the chunk's review folder under ~/.local/state/larv-review/ and returns the worker its verdict and one line per finding; rule-hook refuses its Edit and MultiEdit, and any Write outside ~/.local/state/larv-review/
2026-10-18, lilleman through todo item 73. Serves goal 1.4: a report the worker does not need line by line no longer fills its context. Goal 1.1 holds because the worker reads a finding's full entry before it answers a 🔴 or 🟡.
Each reviewer holds Write for its report. Claude Code passes a subagent's type to a PreToolUse hook as agent_type. So bin/rule_hook/reviewer_report.py refuses a reviewer's Edit and MultiEdit, and any Write outside ~/.local/state/larv-review/; no marker overrides it. A reviewer's Bash, as stability-reviewer holds, is not confined.
The folder is fixed, since loop-claude's headless sessions have no scratchpad, and it also holds any other file a session parks outside its checkout, such as the comprehension panel's base worktree or a build probe's output. It sits outside every checkout, so no project sees a report. It survives a reboot, unlike /tmp, so a resumed chunk still reads its earlier rounds. It is in the user's home, so no other local user plants a symlink that widens it. A report may quote a secret, so larv-review review-folder, which makes the chunk's folder, leaves ~/.local/state/larv-review readable by the user alone.
A chunk keeps its folder after the merge. review-replay hands a replayed reviewer a copy holding only the reports written after the chunk began and before the round did. So the replay reads the earlier rounds its prompt names, never the findings it is to find. The chunk's own reports stay as they were.
Claude Code's own subagent prompt tells a subagent to return findings rather than write report files. review-findings.md → "Report" overrides that, since the file is the worker's input; a prose-reviewer probed on 2026-10-18 wrote the file its prompt named. A general-purpose wrapper that launches the reviewer was not tried: Claude Code's documentation says a subagent cannot start another.
Before this change, reports took a median 19k tokens per chunk, 8% of the worker's peak context, and lines carrying a severity mark were 9–24% of a report (2026-10-08, over 68 archived transcripts). review-replay still counts each 🔴 and 🟡 by its line in the reviewer's reply, now a one-line summary. todo.md item 187 is to measure what the worker reads of the reports instead.
Valid while Claude Code passes agent_type to hooks inside a subagent. Without it, the rule refuses nothing, and a reviewer may write anywhere.
review: stability and product-owner report only a defect, a broken requirement of the plan or the goals, a breach of a technical principle, or for stability a hard place the change touches; each architect finding names a later change the PR makes harder; prose runs only on a chunk that changes prose
2026-10-13, lilleman through todo item 97, implemented by claude. Serves goals 1.4 and 1.5. Anthropic's Claude Code best practices: "A reviewer prompted to find gaps will usually report some, even when the work is sound… Chasing every finding leads to over-engineering." 320 of this repo's 876 commits answered a review round. So stability and product-owner drop a finding that is none of these, and stability leaves the style of comments to prose, which reads every comment a chunk touches. An architect finding that names no later change it makes harder cannot be checked, so it is dropped. The architecture pass and the comprehension check keep their whole-project view, which guards goal 1.1 as a project grows. Valid while the findings these rules drop keep changing nothing a user would notice.
2026-10-28, lilleman: prose findings stay, since Claude's prose needs them, though prose's 105 first rounds since 2026-10-21 raised 498 🟡 and only 3 🔴.
review: the comprehension check records how hard a project is to read and blocks no merge: a paired ruling against the last measured commit in the release review, and the four-seat scoring run, once when an item names the floor and twice on one head when a release's items run out
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 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 the scoring run too, so no release ends unmeasured, unless todo.md marks that release renamed in a ## Renamed section (bin/release_plan/todo_table.py → renames). Valid while seats reading both versions agree more often than two absolute runs do.
2026-10-13, lilleman. No published study validates simulated reader panels as a measure of how easy code is to understand, and no test of whether the panel's signal beats its noise has run. So no ruling, score or floor blocks a merge. The runs go on, so the history keeps the scores and the places the seats found hard, for later measurement. The architect, the stability reviewer and a session filing an item read the newest places: the newest scoring run's and each later ruling's places a seat voted worse. Those are the places a chunk can improve. The check runs once per chunk, on the branch as review left it. A chunk that leaves a touched place as hard says why in its PR summary, not in a decline's record, which would outlive the place.
The base is the last measured commit: the default branch's newest merged change that adds any ruling or scoring run. The human chose it 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. Reading the default branch one merged change at a time keeps the rule working for merge commits and squash merges alike. With worse rulings merging, a base left behind them would charge one chunk's ruling with earlier chunks' falls.
2026-10-17, lilleman. Serves goal 1.1. Nothing checked the 2026-10-08 validity condition. The history's successive scoring runs of one PR read changed code, not near-identical code, so they cannot stand for two absolute runs. So each release's scoring run is done twice on the same head, the second recorded under <PR> rerun at <commit>, and larv-review agreement compares two rates: how often Mid A and the inherited architect vote alike overall in paired rulings, and how often their overall scores move alike between two scoring runs on one commit. It gives no verdict until the history holds 10 such pairs of runs, as score-outcomes waits for 10 chunks before it shows a median. The human chose the second run's cost, four more seats per release (goal 1.4), over a weaker check on the old pairs.
review: the premises chunk's whole review is the human's approval
2026-09-20, lilleman. Serves goal 1.1. A reviewer's finding on that chunk could only be declined by citing the goals the chunk exists to write. Valid while every decline must name a goal or a technical principle.
review: the architecture and principles passes run only in the release review, a release's last chunk, which must land before the release is ready to cut; between releases the product-owner pass reviews changes to what consumers rely on
2026-10-29, lilleman. Serves goals 1.4 and 1.5, and code health. The principles audit read the whole project on every chunk that changed code, because small changes had let a project drift; it was the costliest reviewer after the worker, and it filed findings unrelated to the chunk. A per-chunk architecture trigger needs judgment about what a change carries, which a worker knows only after the work, and a planner or worker asking for the review would pile up agents. So both passes run once, over the whole project, in the release review: the chunk that runs once a release holds no item and changes are unreleased. They may refactor boldly, five rounds each, and their fixes take the stability, security, overrides and prose passes, two rounds each. The human sets how much drift a review must catch through how big a release is. Between releases, the product-owner pass reviews changes to what consumers rely on, such as routes, file formats and CLI flags, which the architecture trigger used to cover. chunk-preflight reports a release review due until a commit titled Release review of <release> follows the newest v* tag, and only then the release ready to cut. A project that deploys every merge, as this repo does, carries drift into production until its release review; lilleman means to move such projects onto releases. Valid while drift a release's chunks leave stays small enough for one review to fix.
review: the principles audit runs only in the release review, and reads the project whole with one auditor checking the goals and every principles file that applies
2026-10-16, lilleman, answering the question on the audit's trigger that the plan held. Serves goal 1.1: a principle that no chunk checks drifts, as the stability reviewer's own copy of the principles drifted from them, until it applied principles/technical-principles.md as written. It costs goal 1.4: a chunk that changes code, config or tests launches an auditor, and a code fix re-enters it. The human accepted that cost. The cost shows in tokens per finished chunk and in review rounds per chunk. Valid while the audit's findings are drift a chunk would otherwise merge, not the same whole-project findings repeated chunk after chunk: a repeat is a question on the audit's scope for the human.
2026-10-27, lilleman, answering the question PR #376 raised: the audit keeps reading the project whole. Since 2026-10-21, 342 auditor runs cost $274 at list prices, and of their 176 🔴 and 🟡 findings that named a file, 90 named one the chunk did not edit, which reading only the change would drop; lilleman keeps them.
2026-10-28, claude, through todo item 233. Serves goal 1.4. One auditor per round checks the README's goals with code health, and each principles file that applies. It reads the project once, where one auditor per goal set or file ran 3.8 times per chunk before.
A trial checked that it keeps goal 1.1. It replayed the 6 latest first rounds that launched two or more auditors, at most two per project, from this repo, log, visthus and adf-codec: 15 auditors, whose reports held 40 🔴 and 🟡 findings. Each round ran on the project's rung as review-replay replays it, once with its separate auditors and once with one auditor handed everything they checked, its new definition passed through --agents. A replayed reviewer finds a different part of its findings each time: the separate auditors found only 10 of their own 40 again. The one auditor found 12, among them 8 of those 10. So it finds as much as the separate auditors do. It missed two 🟡s on a missing or weak test, and found 4 findings they missed. No principles file keeps an auditor of its own. Asked whether those two misses should bring back separate auditors for the technical principles and for the goals with code health, lilleman chose to try the one auditor. Valid until the auditor's definition changes or a new model joins the ladder: replay the pass then, as this trial did.
2026-10-29, lilleman: it runs only in the release review. review: the architecture and principles passes run only in the release review… says why.
review: mutate-changes mutation-tests the lines a chunk changes before review, in place of measuring test coverage
2026-10-13, lilleman through todo item 108, implemented by claude; moved before review on 2026-11-11 through todo item 293. Serves goals 1.1 and 1.4. Coverage counts the lines a test runs, so a test without a meaningful assertion still raises it. A surviving mutant shows a test that would let behaviour break. Every mutant of an untested changed line survives, so mutation testing of the changed lines also shows what a coverage drop on them would. Coverage would also catch a deleted test; the stability reviewer sees one in the diff without it. Measuring coverage beside it would add cost without raising quality, so todo item 69 was dropped and principles/technical-principles.md replaced "Test coverage should not decline" with the mutant rule.
Since 2026-11-11 the worker runs bin/mutate-changes once before review, kills the survivors that change behaviour, and hands stability-reviewer the rest to judge. Until then, stability-reviewer ran the tools by hand in 133 of its 144 reports, and 52% of its findings were test gaps. One command finds the survivors the same way every time, and the reviewer spends its round on what remains.
The run is limited to the changed lines, so its cost grows with the chunk. The tools are widely deployed, each with its own way to limit a run to a diff: cargo-mutants --in-diff (https://mutants.rs/in-diff.html), Infection --git-diff-lines (https://infection.github.io/guide/command-line-options.html), Stryker's mutation ranges (https://stryker-mutator.io/docs/stryker-js/configuration/). mutmut has no such option, so mutate-changes mutates only the functions and methods the changed lines fall in, through mutmut's mutant-name patterns, and counts the mutants on changed lines.
The run has no time cap. Limiting it to the changed lines already bounds it by the chunk's size, and no published standard gives a cap to copy. Each run's wall time in the reviewer's report shows when the premise below fails.
Valid while a mutation run on a chunk's changed lines stays cheap beside the review itself.
routing: a chunk's worker runs on the rung its item's L picks, below the project's rung too; its reviewers run on the highest of the worker's rung, the project's and the one picked by the highest E + I among the chunk's items, unless a replay lowered their pass or the branch changes only Markdown no agent follows, which reviews on the project's rung; the seats and the security pass always on the project's
2026-10-14, lilleman. Serves goals 1.1 and 1.4.
Only chunks run below the project's rung can prove that a cheaper worker holds quality (goal 1.1). So on 2026-10-14 lilleman chose a trial on real chunks: a replay of past chunks would spend on work that never ships (goal 1.4). Review holds quality meanwhile. While the worker runs below the project's rung, loop-claude's prompt has it launch each comprehension seat and the security pass's subagent on the project's rung, and each reviewer there too unless the highest E + I among its items picks a higher rung or a replay lowered its pass, through the Agent tool's model and effort. The worker runs a full scan only from such a subagent, because the claude-security plugin's researchers and verifiers inherit the model that starts them. A subagent that cannot run the scan leaves it unavailable, so larv-review runs /security-review in its place. lilleman chose the project's rung, medium, knowing settings.json then ran every interactive session on Opus 5.5 at xhigh, so a routed worker ran below the effort an interactive session took.
While the worker runs above the project's rung, loop-claude's prompt has it launch the comprehension seats and the security pass's subagent on the project's rung too. So the seats score every chunk on one rung, and the security pass spends no more than the project chose. The prompt after each unfinished verdict repeats this, since a step-up may have taken the worker above the project's rung. The other reviewers never run below the worker's rung while it runs above the project's: a worker climbs because its chunk proved harder than its score said, which is when a cheaper reviewer is the bigger risk. A reviewer or seat that rules the work below standard may rerun one rung up: review: a reviewer or comprehension seat that rules the work below standard.
On 2026-10-16 lilleman routed the reviewers on their item's E + I as well, on either side of the project's rung, which may lift them above both the worker's rung and the project's: how far a defect would escape, and what it would break, set how hard review must look (goal 1.1). loop-claude names that rung in the worker's prompt. It hands the E + I to the worker's claude beside the project's rung and the worker's, so rule-hook works out each review's rung as the prompt does and holds each launch to it. A low E + I never steps a reviewer below the project's rung: only a replay lowers a pass, as routing: a review pass runs below the project's rung only on a rung that a replay of its rounds shows finding every 🔴 and 🟡 the project's rung finds… records. An item the worker takes in beyond the routed one counts too, since its E + I scores its defects as the routed item's scores theirs. The worker's prompt names the reviewers' rung each higher E + I picks, so the worker reviews a taken-in item on it in the same run. The judge reports the highest E + I the worker states for a taken-in item. From the next cycle loop-claude routes on that E + I, and archives it with the route so a rerun keeps it.
Valid until the trial on real chunks shows whether a worker below the project's rung holds quality.
2026-10-29, lilleman. Serves goals 1.4 and 1.5. A branch that changes only Markdown no agent follows reviews on the project's rung, whatever its items' E + I. E + I scores an item before its chunk starts, by the change the item asks for, so one project's item, filed to build a control on a CI runner, kept its E + I of 7 when the chunk found no control the repo could build and shipped a README paragraph: five reviewers read prose on Opus 5.5 at xhigh. rule-hook's reviewer-rung reads the branch's files, committed or not, against the default branch as last fetched. Markdown an agent follows counts as config: CLAUDE.md, AGENTS.md, workflow-bench/*-prompt.md and files under agents/, principles/, rules/ or skills/. On 2026-11-04 lilleman added the workflow bench's prompts, which an agent follows like a skill. bin/review_rules/review_passes.py holds the lists, and the worker's prompt renders them. Valid while a README or docs defect costs a reader no more than review on the project's rung lets through.
routing: a review pass runs below the project's rung only on a rung that a replay of its rounds shows finding every 🔴 and 🟡 the project's rung finds, and only where the E + I steps no review up and the worker runs no higher than the project's rung, then even below the worker's; no pass has such a rung
2026-10-15, lilleman proposed running the stability reviewer on the worker's rung, and the agent proposed the replay that gates it. On 2026-10-16 lilleman asked for the prose pass to run on the worker's rung or lower, and, answering PR #296, for every pass to drop below the project's rung only where a replay shows it may. Serves goal 1.4 without giving up goal 1.1: a cheaper reviewer saves money only where it misses nothing.
bin/review-replay <pass> <model> replays a pass's archived rounds on the code each reviewed. It replays them first on the project's rung, then on each rung below it, highest first, down to the ladder's lowest. It stops at the first rung that misses a finding the project's rung found again. A rung qualifies only where it and each rung above it find every such 🔴 and 🟡.
A qualifying rung applies only where the chunk's E + I steps no review up and the worker runs no higher than the project's rung; there the pass runs on that rung, even below the worker's. Otherwise the pass runs where every other pass does: the replay compared reviews on the project's rung only, never reviews on a rung an E + I stepped up, nor of a chunk whose worker climbed above the project's rung. No code lowers a pass while no rung qualifies: on 2026-11-04 lilleman had the release review of 0.6.0 delete that code, which no chunk could reach. The chunk that first qualifies a rung, todo.md item 196's, writes that code again in bin/model_routing/. It records the qualifying rung for each pass and project model, and names the lowered pass in the worker's prompt and in rule-hook's reviewer-rung.
The runs, each on the latest 10 rounds of Opus 5.5 projects that hold a 🔴 or 🟡:
- 2026-10-15, stability: 40 findings, 8 of the rounds from this repo. Opus 5.5 at medium, the project's rung, found 29 of them again. Sonnet 5.5 at high missed 13 of those 29, 2 of them 🔴. No rung qualifies.
- 2026-10-18, prose: 39 findings. The project's rung found 27 of them again. Sonnet 5.5 at high missed 12 of those 27. No rung qualifies.
- 2026-10-18, stability again, since that day's change to the reviewer prompts expired the first run: 29 findings. The project's rung found 20 of them again. Sonnet 5.5 at high missed 11 of those 20, 1 of them 🔴. No rung qualifies.
The prose pass went first: a missed prose finding breaks no behaviour, and a later change fixes it cheaply. Sonnet 5.5 missed 44 to 55% of what the project's rung found again, in the prose pass as in both stability runs. Nothing suggests the other passes' findings are easier to find. So the architecture, principles, overrides and product-owner passes are not replayed yet: a replay would spend money with little chance of a qualifying rung (goal 1.4). todo.md item 196 keeps their replays in the plan. Every pass runs where routing: a chunk's worker runs on the rung its item's L picks puts every reviewer.
Valid until a new model joins the ladder, which calls for a replay of every pass, or a pass's reviewer prompt changes, which calls for a replay of that pass.
routing: a worker delegates a task only where it needs just the task's conclusion, and each subagent runs on the rung its task's L picks from the project's rung, never below the project's rung when it files or scores todo.md items
2026-10-15, lilleman. Serves goals 1.1 and 1.4.
The worker delegates a task only when it needs just the task's conclusion: a search or read across many files, or work independent enough to run in parallel. Edits, and whatever it must check line by line, stay in its own thread, since it would read a delegated diff again to check it. Measured over archived worker transcripts, subagent reports cost a median 8% of the worker's peak context, and sed -n and grep output made up 41% of its Bash results, so delegated searches save the most context. It scores each delegated task's L as for an item, and bin/subagent-rung turns it into the Agent tool's model and effort, counted from the project's rung. The rule names both, because the Agent tool sets a subagent's effort only when instructions ask. CLAUDE.md states the rule, since it holds in every session. A subagent that files or scores todo.md items takes bin/subagent-rung --plan, which never prints a rung below the project's, the floor todo.md: only a session or subagent on the project's rung or above scores or reshapes the plan sets. A task that proves too hard for the worker's rung goes one rung up instead: routing: a worker hands a task one rung up.
Valid while delegated searches save more context than their reports cost.
routing: a worker hands a task one rung up on each escalation trigger, up to two rungs above the rung its item picks unless the human agrees, and opens the subagent's prompt with the trigger so the routing figures count it
2026-10-15, lilleman asked for it. Serves goals 1.1 and 1.4: a task too hard for a cheap rung gets a dearer one only once it proves hard, and only for the part that proved hard.
Four escalation triggers in CLAUDE.md → "Working with the codebase" mark a task too hard: a re-score of the item on the project's rung or above picks a higher rung, the same failing test or finding survives two fix attempts, a pass reports a 🔴 in round 2 or later, or a reviewer or seat rules the work below standard, unless the fix changes only prose. When one fires, the worker hands the hard part to a subagent one rung above its own, edits included, though the delegation rule keeps edits in the worker's thread: the escalation exists because the worker could not get them right. Each further trigger on that task climbs one more rung. Without lilleman's yes the climb stops two rungs above the rung the chunk started on: the rung its item picks, or the project's rung when no item routed it. A step-up between cycles raises the worker but not that limit: lilleman set the limit from the rung the chunk started on, so a worker that has stepped up may need a yes for its first escalation.
loop-claude's prompt names the rungs a trigger opens, so the worker computes no rung positions, and tells the worker to open each escalated subagent's prompt with Escalation trigger <n>:. bin/loop_claude/routing.py holds the limit and bin/model_routing/route.py the marker. The archive keeps the raw transcript, which holds the marked prompt, and bin/routing_figures/ counts the escalations by trigger in routing-figures.md, per starting rung for routed chunks and in total for every chunk.
Valid while the ladder orders its rungs by competence.
routing: a worker whose run ends asking for a higher rung, citing an escalation trigger the judge finds in the transcript, steps one rung up as the judge interrupts or quotes an answer, or next cycle, up to two rungs above the rung its item picks
2026-10-15, lilleman asked for it. Serves goals 1.1 and 1.4: when the hard part is the rest of the chunk, handing it to subagents piece by piece leaves the worker, which reads and checks each of their diffs, on a rung that proved too low. The worker climbs only once its run records a trigger.
loop-claude's prompt offers the step beside the escalated subagent of routing: a worker hands a task one rung up, as long as the limit leaves a rung that subagent may take without the human's yes. The worker then ends its run asking loop-claude for a higher rung and naming the trigger. The judge quotes the earlier passage where the trigger fired, such as a review round's commit title or the worker's report of the failing test, never a later mention of it and never the request itself. The quoted passage must sit after the worker's last step-up, which loop-claude checks, so one passage buys one step. The judge sees the worker's text and tool calls but no tool results, so the quote shows that the run recorded the trigger, not that a tool's output bears it out. loop-claude checks the quote word for word, as it checks a quoted answer, since stitched fragments can make up a trigger. Without such a quote, the rung holds. A misquote is no failure, since holding the rung is safe and three failures stop an unattended loop. The next cycle's prompt names the worker's rung, so the worker learns whether the step went through. When a quoted answer, or an interrupt the human answers on loop-claude's terminal, steps the worker up, the prompt that resumes it with the answer names the new rung, so the worker learns of the step sooner.
A run that asks for a higher rung may also ask a question. The judge then interrupts, or quotes the answer from README.md or the records, and either ruling carries the escalation quote too, checked the same way. loop-claude steps the rung as the ruling comes in, before the human is asked or the worker resumes with the quoted answer, since the work after the answer is work the stepped rung should do. An interrupt or a quoted answer is no unfinished verdict, so it adds to no count.
The judge may quote a different passage for the trigger that already stepped the rung, and loop-claude cannot tell from the quote alone whether the trigger is new. So it goes by where the quoted passage sits in the transcript. When an escalation steps the worker, the route marks how many transcript entries the session held: the mark. loop-claude then accepts an escalation quote only from the worker's own lines after the mark, never from its own prompts or the human's lines, which repeat earlier passages. The judge reads a [step] line at the mark saying the triggers before it are spent, so it quotes a passage the check accepts. The session's transcript only grows, so the mark holds across cycles. The trigger that bought a step, and any rewording of it before the mark, cannot buy another. A trigger that fires after the step steps the worker again, in the same cycle or a later one. One risk remains: a worker on the stepped rung may restate an old trigger after the mark, and the judge may quote that. The cap two rungs above the rung the item picks limits what this costs. Before the mark, once an interrupt or a quoted answer had taken an escalation, no later ruling of that cycle carried one, so a trigger that fired after the answer was lost. lilleman chose the mark on 2026-10-18 over two alternatives: lifting that rule when a worker run ended would have let one trigger buy two steps, and telling the worker its request was dropped would still have lost the step.
The step is one rung up from the rung the worker would otherwise hold: its own, or the rung an item the judge saw it take in picks, whichever is higher. It resets the count of unfinished verdicts, so the step every second one takes counts afresh; when both steps fall on one verdict, the worker steps once. It stops at the limit escalated subagents stop at, two rungs above the rung the chunk started on. Past that limit the rung holds: loop-claude takes no yes from the human between cycles, so a worker there asks the human for an escalated subagent instead. The judge keeps its rung, as routing: on a model judge-replay covered says.
The archive quotes the judge's passage under Escalation: in the unfinished verdict, the interrupt or the quoted answer. The step an unfinished verdict causes is archived after it. The step an interrupt or a quoted answer causes is archived with it, at once: the interrupt or answer names the rung the worker ran on until then, and a step-up archived beside it names the rung it runs on from then. So the routing figures charge each stretch to its own rung, and a loop that dies while the human answers resumes on the stepped rung. Each archived worker line names the mark once there is one, so a resumed loop keeps it. bin/routing_figures/ counts none of these steps as an escalation by trigger, which it counts only from subagent prompts.
Valid while the worker reports in its transcript the triggers that fired, and while a chunk's session transcript only grows.
routing: loop-claude measures review rounds and unfinished verdicts per rung every 20 cycles, and calls for a routing change when, of two rungs with 5 or more chunks each, the lower took more of either than the one above, or when 5 or more subagents of one type had reports longer than the tool results they read
2026-10-15, lilleman. Serves goals 1.2 and 1.4.
The cost of a cheaper worker shows as extra review rounds and unfinished verdicts. Every 20 cycles across the archive, loop-claude measures them in code, with no model run (goal 1.4), and interrupts lilleman with the calls not raised before, when chunks routed onto a rung took more of either than chunks routed onto the next rung up, each rung with 5 chunks or more. Five keeps one odd chunk from calling for a change (goal 1.2). It also calls when the reports of 5 or more subagents of one type were longer than the tool results they read, so a delegated search cost the worker more context than it saved. bin/routing_figures/ measures and words the calls. A loop on another project cannot commit here, so it writes the figures and the calls raised at the archive's root, and this repo's next chunk files the plan item, as AGENTS.md says. Off a terminal, a call is said on stderr and the loop goes on: it is about this setup, not the running project's chunk. A reset line in the calls file restarts the figures after a routing change, so they show whether the change worked.
Since 2026-10-16 the reviewers may run above the worker's rung, on the one the highest E + I among their chunk's items picks, so chunks whose worker ran on a lower rung may take more rounds from stronger reviewers, and a call could blame the worker's rung for them; todo.md item 171 groups the rounds by the reviewers' rung too. Valid while loop-claude's archive holds every finished chunk's review rounds and unfinished verdicts.
routing: on a model judge-replay covered, the judge runs on the rung a review would get from the highest E + I among its chunk's items, never below the project's rung
2026-10-15, lilleman's plan, settled by the replay below. Serves goals 1.2 and 1.4, under the ladder and steps of routing: one ladder.
On a model listed in JUDGE_REPLAYED in bin/loop_claude/routing.py, the judge runs on the rung a review would get from the highest E + I among its chunk's items: the routed item and those the worker takes in. It never runs below the project's rung, and keeps its rung when the worker steps up. Without an item, it runs on the project's rung. Each archived verdict names the judge's rung on a Judge: line.
On 2026-10-15, bin/judge-replay claude-opus-5-5 replayed the latest 15 archived verdicts of each kind from the Opus 5.5 projects, 39 in all. The reference judge, Opus 5.5 at the xhigh effort settings.json gave every judge before, reproduced 31 of them. The other 8 may rest on records or judge rules that have changed since; either way no rung is held to them. On the 31, Haiku 5.5 missed 7 at xhigh and 8 at max. That run tried each judge once. 4 of Haiku's misses, 1 at xhigh and 3 at max, misquoted the transcript, which the loop and judge-replay now retry; without them it missed 6 and 5. Sonnet 5.5 at high returned another kind on 3 interrupts, and Opus 5.5 at medium missed none. A missed interrupt lets the worker settle a decision that is lilleman's (goal 1.2), so the judge never runs below the project's rung.
Only Opus 5.5 was replayed, so the judge of a project on another model keeps the effort its settings give until judge-replay covers that model (goal 1.1). Every routed chunk on record had an item of R + C 9, so the replay could not show that the project's rung suffices for harder items, and the judge climbs with the routed item. Since 2026-10-16, lilleman's call, it climbs with the item's E + I, as a review does: the judge checks the worker's decisions as the reviewers check its code, and a decision the judge lets through reaches lilleman, as a defect that review lets through reaches the users (goal 1.2). It runs above the project's rung only on an E + I of 5 or more (goal 1.4). It counts a taken-in item from the next cycle on.
Valid while the archived verdicts show what a judge should return, and until a new model joins the ladder: replay then.
routing: one ladder of (model, effort) rungs, ordered by the Artificial Analysis Intelligence Index with Fable 5.1 at max on top; a task's L picks its worker's rung and its E + I its reviewers', by fixed steps counted from the cheapest rung of the project's model
2026-10-14, lilleman. Serves goal 1.4, and goal 1.3: one ladder, the same in every project, read by loop-claude and by the worker through bin/subagent-rung. The judge's rung is set by routing: on a model judge-replay covered. bin/model_routing/ladder.py holds the rungs and the steps.
The rungs, least competent first: Sonnet 5.5 at high; Opus 5.5 at medium, high, xhigh and max; Fable 5.1 at max. The 2026-10-29 note below took Haiku 5.5 off. They first were: Haiku 5.5 at low, medium, high, xhigh and max; Sonnet 5.5 at high; Opus 5.5 at medium, high, xhigh and max; Fable 5.1 at max. The order and the cut come from the Artificial Analysis Intelligence Index (https://artificialanalysis.ai/leaderboards/models, read 2026-10-14), which scores each model at each effort and gives a cost per task. A rung stays only where no cheaper rung scores as high, so a step up always buys more score (goal 1.4). That cut drops Sonnet 5.5 at low, medium, xhigh and max, Opus 5.5 at low, and every Fable 5.1 rung, and every tie in the index falls among the dropped rungs. lilleman put Fable 5.1 at max back on top: the index scores it under Opus 5.5 at high, but Anthropic's model catalog names Fable the most capable model, and for the hardest tasks lilleman wants the highest quality at any price.
A project's rung is its model's cheapest rung, which for Opus 5.5 is its default effort, medium. A model off the ladder routes nothing: claude runs it at the effort its settings give. A task's L steps its worker from the project's rung: 1 and 2 one down, 3 none, 4 one up. Its E + I steps its reviewers up from the project's rung: 4 or less none, 5 one up, 6 two up, 7 three up, 8 four up. A step past either end stops there. A worker errs more the more it changes and the newer that is, which L scores; review must look harder the further a defect would escape and the more it would break, which E + I scores (goals 1.1 and 1.4). Size raises L, so a large change runs its worker higher. The steps spread the values this repo's plan held when rescored on 2026-10-16, L 1 to 4 and E + I 2 to 7, so a worker on most items runs at or below the project's rung, and a review climbs only where a defect would escape far or break much. lilleman approved the steps on 2026-10-16 as a guess. score-outcomes reports how well L, E and I each order finished chunks by review rounds and 🔴 findings. A change to the ladder or the steps is lilleman's.
2026-10-21, lilleman, settling the routing calls stamped 2026-10-21T20:33:29Z: L 1 steps one rung down, not two as before, so an Opus 5.5 project runs no worker on Haiku 5.5. A delegated subagent takes the same steps, so an L 1 search moves off Haiku 5.5 too: lilleman chose one set of steps for chunk workers and subagents alike, so loop-claude, subagent-rung and rule-hook read one table (code health). No figure yet shows whether Sonnet 5.5 searches better than Haiku 5.5, so this costs more per search for a gain nobody has measured (goal 1.4). The calls came from loop-claude's routing figures, measured at cycle 165 over 46 chunks. Chunks started on Haiku 5.5 at max took a mean 7.8 review rounds past each pass's first, against 2.8 on Sonnet 5.5 at high, and 0.2 unfinished verdicts, against 0.1. The figures also called for moving workers off Sonnet 5.5 at high, whose chunks took 0.1 unfinished verdicts against 0.0 on Opus 5.5 at medium. lilleman kept L 2 on Sonnet 5.5, since that gap rests on one or two verdicts.
2026-10-23, lilleman: 15 chunks had shipped under today's steps. Over them, L's rank correlation with review rounds was +0.53. They held only 3 🔴 findings, too few to test E and I. 50 chunks hold about 10 at that rate, and a re-tune on fewer chunks would fit noise.
2026-10-29, lilleman: Haiku 5.5 is off the ladder, so no worker, subagent or review runs on it, and a Sonnet 5.5 project's L 1 and L 2 workers stay on Sonnet 5.5 at high. One project's chunk on 2026-10-29, a README paragraph and plan rows, ran on Haiku 5.5 at max for 2 h 17 min and wrote 3.1 million output tokens; the chunk before it, item 7, a merge gate with tests, took 29 minutes and 111k tokens on Sonnet 5.5 at high. The routing figures had shown the same before: chunks started on Haiku 5.5 at max took 7.8 review rounds past each pass's first against 2.8 on Sonnet 5.5 at high (goals 1.4 and 1.5). A review replay can now lower a pass only to Sonnet 5.5 at high, and on a Sonnet 5.5 project to no rung.
2026-10-31, lilleman kept the steps, so L 1 and L 2 workers on an Opus 5.5 project stay on Sonnet 5.5 at high. The routing figures measured at 2026-10-31T02:40:55Z, over 24 chunks finished since the 2026-10-29 reset, called for moving them off it: chunks started on Sonnet 5.5 at high took a mean 0.9 review rounds past each pass's first over 15 chunks, against 0.6 over 5 on Opus 5.5 at medium. The gap is 0.3 rounds on the fewest chunks a call allows, and Sonnet's chunks did better on the other figures: 0.1 unfinished verdicts against 0.4, and 0.0 later fixes against 0.4, at a lower cost (goal 1.4).
2026-11-08, lilleman kept the steps, starting the re-tune with 54 item-* branches merged since the steps took effect, 36 of them chunks that each shipped one item scored with L, E and I, in place of waiting for 50 such chunks. Mean review rounds past each pass's first rose with L: 1.57 at L 1, 2.15 at L 2, 2.75 at L 3 and 3.50 at L 4. E + I ordered neither rounds nor 🔴 findings between 3 and 5, and no chunk scored an E + I of 7 or more, so nothing supports changing the steps for E + I 6 to 8. L 1 and L 2 share the Sonnet 5.5 rung yet differ in 🔴 (1 of 7 chunks against 6 of 12), so a 🔴 follows the item more than the rung, and nothing moves L 2. todo.md item 273 re-tunes the E + I steps once 10 chunks score an E + I of 6 or more.
Valid while the index ranks these models, and while no newer model joins the catalog.
routing: the worker changes rung only as a chunk starts, after every second unfinished verdict, or when the judge reports a taken-in item that picks a higher rung or an escalation trigger the worker cites
2026-10-14, lilleman. Serves goal 1.4.
Because a model switch inside a session discards its prompt cache, the worker changes rung only as the chunk starts, after every second unfinished verdict, when the judge reports a taken-in item whose L picks a higher rung, or when the judge finds the escalation trigger a worker cites in asking for a higher rung (routing: a worker whose run ends asking for a higher rung). loop-claude routes on the first row of the next release in todo.md's table that does not wait: an item waits while it is marked question or a blocker of it is still in the table. Since todo.md holds no order but its table's (todo.md: one table), that row is the item the worker takes. An item the worker takes in beyond that row lifts the worker's rung once the judge reports it, after the first cycle.
Valid while a model switch inside a session discards its prompt cache.
rule-hook: a PreToolUse hook enforces each rule a program can check, a # rule-override <rule>: <reason> marker overrides any rule but those rule-hook --help marks as taking none, and larv-review's overrides pass rules on each override before merge
2026-10-12, lilleman. Serves goals 1.2 and 1.3. Anthropic's best-practices page calls CLAUDE.md advisory and hooks deterministic, so a rule that must hold every time moves into bin/rule-hook, and CLAUDE.md keeps it only where the hook cannot check it. A Claude Code hook ties the check to one vendor ("Prefer the vendor-neutral option", principles/technical-principles.md), which is the target itself here: this repo configures Claude Code. What the tie buys: the hook blocks before a write lands, Edit and Write calls included, in every project with no per-repo install; a git commit-msg hook sees only commits, and CI sees them only after the push. The hook checks each write, so the agent fixes the line it just wrote; checking the staged diff at commit time would also cover files a Bash command writes, at the cost of later feedback. The marker's spelling was picked by a panel of three fresh readers, two to one. Each override is logged in the checkout's git directory, which is never pushed (goal 4). The plan had loop-claude's judge to rule on overrides inside a loop; lilleman approved larv-review's overrides pass in every run, because it rules before merge and an outrageous override still reaches the human through its ask. 2026-10-16, lilleman, answering plan item 166: no marker overrides reviewer-rung. 2026-11-04, lilleman: the title points at rule-hook --help, which lists every rule no marker overrides from the code, so the title can't drift from it; the comment above each in bin/rule_hook/rules.py says why. Valid while a PreToolUse hook that exits 2 blocks the call and hands its stderr to the model, and while an agent commits through Claude Code's Bash tool.
rules/: CLAUDE.md holds the worker's rules that no file path can scope, and each topic's rules for the worker live in a rules/ file that Claude Code loads by its paths: frontmatter
2026-10-13, lilleman through todo item 95, implemented by claude. Serves goals 1.3 and 1.4. Every session loaded CLAUDE.md whole, about 4,200 words. Anthropic's memory docs (code.claude.com/docs/en/memory) say a longer file "reduce[s] adherence", and IFScale (arxiv.org/abs/2507.11538) measures adherence falling as the instruction count grows. A rule goes in CLAUDE.md when no file path marks the moment it is needed: the working loop, prose that chat follows, commits, and API spec text, which may sit in code. Every other topic gets a file under rules/ whose paths: name the files that topic is about.
A session that writes a file has read one first, since Edit needs a Read, except for a new file written before any read; the "Topic rules" line says to read the rule file first there. 2026-10-13, todo item 104: the rules a reviewer applies and the worker need not load, those for comments and READMEs among them, moved out of rules/, per the worker: decision.
Claude Code's user-level rules tie this repo to Claude Code, which "Prefer the vendor-neutral option" (principles/technical-principles.md) allows here because this repo configures Claude Code itself. The tie buys topic rules that load without a pointer the session must follow.
Valid while Claude Code loads ~/.claude/rules/*.md in every project, a path-scoped one when a session reads, writes or edits a matching file, or reads one with a single-file Bash command such as cat, and after a write only once the write is done. On 2026-10-13 a smoke test confirmed both triggers: a rule in ~/.claude/rules/ with paths: ["**/smoke-target.txt"] held a secret word. claude -p in a project under /tmp printed the word after reading the target with the Read tool, and after creating it with the Write tool. A control run that opened no file printed none. Per the docs, a path-scoped rule leaves the context at compaction and returns at the next matching read.
settings.json: Claude Code runs in auto mode with the dangerous-mode prompt skipped
2026-10-04, lilleman, answering the principles audit of PR #215. Serves goal 1: this setup is meant to run in a sandbox and to work autonomously, so tool access is granted by the sandbox, as "Always grant explicit access to data" in principles/technical-principles.md asks. Valid while every machine taking this checkout is such a sandbox.
settings.json: each machine owns its model, and git's clean filter bin/settings_filter.py keeps it, and Claude Code's key order, out of every commit
2026-10-21, lilleman. Serves goal 2: Claude Code rewrites "model" in settings.json on every /model and plugin install, so a tracked model let one machine's pick override every other's. lilleman chose a model per machine over one synced in env.ANTHROPIC_MODEL, which would override a /model pick from the next session on. A model per machine is simpler, and loop-claude picks each project's model in ~/.claude/loop-claude-models.json anyway. The filter also sorts the keys, since each write puts them back in Claude Code's order. The cost: a move or pull that changes settings.json drops the machine's model. The effort keys, effortLevel and modelSettings, stay synced: the routing decision on a chunk's worker rung relies on the effort settings.json gives every interactive session. Valid while Claude Code writes the model it picks into settings.json.
tests: CI runs the suite through ci.sh on every pull request, in a pinned Python container, and main's branch protection holds a merge until it passes
2026-11-09, larv-review, through todo item 12. Serves goal 1.1: a merge no longer rests on the worker's word. larv-review's gate was the local run alone, which it skips when the last stability round left the suite green, so an unattended chunk could merge on the worker's own report. gitea.larvit.se's runners labelled docker-host run .gitea/workflows/ci.yml, which runs ci.sh on the committed HEAD in a pinned Python container; the script's header says how. A run takes about 3 minutes.
The protection lives in Gitea's settings, outside the repo: rule main, required status check CI / tests (pull_request). A pull request has no status until CI queues its run, so deploy-release --cut waits for each check the protection requires rather than reading no status as no checks, for 30 minutes at most. CI runs no rule-hook check, so a rule-override in the PR body has nothing to override. Whoever adds a rule check to CI must also let it read the PR body's rule-override. Valid while gitea.larvit.se runs a runner labelled docker-host.
tests: each test earns its keep as the technical principles' test bullet says, and the worker takes a test's expected values from its item, never from the code
2026-10-16, lilleman asked for research on what makes tests valuable, then for these changes; claude drafted them. Serves goal 1.1, since a test that cannot catch a bug, or breaks without one, lowers quality and costs review rounds.
An audit of 196 tests sampled across eight projects found about 61% clearly valuable. Of all 196, 15% pinned wording that is not the contract, such as whole prompt sentences; 9% copied or policed the implementation, such as scanning the source with ast; 6% ran on real time or heavy resources; and 6% asserted something no bug could break, such as a list's length. The bullet follows these sources:
- A valuable test fails when behaviour breaks, passes after a refactor, asserts state over interactions and keeps its expected outcome narrow: Software Engineering at Google, chapters 11, 12 and 14; Fowler, "The Practical Test Pyramid"; Beck, "Test Desiderata"; Khorikov, Unit Testing: Principles, Practices, and Patterns, chapter 4.
- A test that never failed on its assertion may be tautological: Seemann, blog.ploeh.dk, 2019-10-14.
- Tests whose expected values come from the code's current output pass on a bug and fail on its fix: Charoosaei et al., arXiv 2610.11835, a preprint; Mathews & Nagappan, arXiv 2412.14137.
- Agents add mocks to tests more often than people do: Hora & Robbes, MSR 2026, arXiv 2602.00409.
- Coverage barely predicts fault detection: Inozemtseva & Holmes, ICSE 2014. Surviving mutants do predict real faults: Just et al., FSE 2014; Google's mutation testing in code review, arXiv 2102.11378.
The decision worker: a chunk's worker writes the simplest change… has the worker read a principle only where something names it. A reviewer sees only the finished test, so cannot tell whether a literal in it was copied from the code's output. So the rule on expected values also stands in CLAUDE.md → "Working loop", "Implement the simplest change that solves the item, and ship it with /larv-review", and the stability reviewer holds a change to the whole bullet.
Valid while the worker writes the tests that larv-review's reviewers hold to the principles.
the repo may name bender, bender-infra and ai-sandbox
2026-10-04, lilleman, answering the principles audit of PR #215. Serves goal 4, which keeps credentials, transcripts and memory files off the remote; the names of the host, its infrastructure project and the sandbox VM are none of those. Valid while the repo names them without their addresses or credentials.
todo.md: one table of items, scored by the formula it states, held to its bar and ranked by bin/rank_todo.py, which ranks each blocker above the items it blocks; each achieve goal weighs by its position, code health first and four times as heavy while the comprehension panel's overall is under 7.0 or unmeasured, then README.md's goals, and a maintain goal weighs 0.5 per point of the confidence an item's test, gate leg or probe adds to it; the table's order is the plan's only order
2026-10-02, lilleman. Serves goal 1: findings were filed faster than chunks closed them, so the plan grew without telling what mattered. Each item is scored as ~/.claude/rules/todo-items.md says; this repo's formula counts value highest and size least. The format is mandatory in every project, as the premises are (goal 1.3); the formula and bar are each project's own. A script ranks the table so a re-rank after each addition or edit is deterministic and cheap. Valid while one human sets the bar and reads the ranking, and while the items marked principle stay few enough to rank.
2026-10-02, lilleman, on the bar. An item under the bar is not kept, and an Exempt cell keeps a row past the bar where a rule needs it kept. Since 2026-10-16 the bar is 0.1, lilleman's call answering the review of PR #283: on one-decimal scores it drops an item scoring under 0.05, in practice one that moves no goal, and item 149 revisits it.
2026-10-02, lilleman, on re-raising findings. A finding under the bar is recorded nowhere, so a later review may raise it again, and the run rescores it. That costs one scoring; a ledger of dropped findings would regrow the list the bar caps. larv-review's "Round cap" → "Done" counts a finding named under the bar as settled, so one raised again holds no pass open.
2026-10-02, lilleman, on the gate check. rank_todo.py --check is part of larv-review's gate, since only a check keeps the stored Score from going stale.
2026-10-02, lilleman, on the principle exemption. A 🟡 against a technical principle is exempt as principle, because its audience value scores low and the bar would drop every one. A 🟢 against a principle is scored like any other finding.
2026-10-15, lilleman: the scores follow a researched method, built by todo.md items 149 and 151 after PR #283 shipped the ranking, PR #296 the risk scores and PR #298 the anchors each project names for each level in docs/score-anchors.md; the evidence is in docs/scoring-and-goals-research.md. R is L + E + I − 2: the chance the change holds a defect, set first by its size; the chance the defect escapes tests, review and monitoring; and the worst impact dimension, each about ×10 per level. I5, irreversible, holds R at 7 or more, and I4 at 5 or more, since a severe enough consequence outranks how unlikely it is. R stays out of the ranking and sets how carefully an item is done; an item that lowers risk scores it as value. A task's L and E + I pick its rungs in place of R (2026-10-16, lilleman), as routing: one ladder records. There is no C column: what it scored beyond size, spread and novelty, which L already holds, is complexity, and that adds almost nothing once size is accounted for. There is no A column either, since the Audience says whose value the goals serve. Each README goal is maintain, which vetoes an item that breaks it, or achieve, with a signal, a counter-signal and a one-line reason, as this README's Goals mark them. Two parts are not built yet and hold once their items ship: each release fills by priority up to a capacity it states (item 149), and each project keeps 10 to 20 settled decisions to test its goals against (item 151).
2026-10-16, PR #283: items rank by Score = 100 * V / (2**S + F). The 100 lets a score read to one decimal. 2**S is the cost. V sums, over the goals an item's Moves cell names, each goal's weight times how far the item moves it, 1 to 10. A Moves column holds 1.1 by 8, 1.2 by 5. An item names a maintain goal only as a defect restoring it, or by the confidence a test, gate leg or probe adds to it, as the defect paragraph below and the 2026-11-09 paragraph after it say.
2026-10-18, lilleman: rank_todo.py derives the goal weights from README.md. Each achieve goal, in reading order, weighs 0.97 times the one before it, and the weights sum to 1; GOAL_STEP sets the 0.97. lilleman wanted goals to weigh almost the same, since under the sum-reciprocal weight the goal ranked k of n achieve goals weighed (1/k) / (1 + 1/2 + … + 1/n), so the last of twelve goals weighed a twelfth of the first. The step departs from docs/scoring-and-goals-research.md, where sum-reciprocal weights came closest to the weights people gave.
2026-11-08, item 158, replacing lilleman's F of 8 from PR #283. Serves goal 1.4: this repo's plan sets F, the cost every chunk pays whatever its size, to 32, which is 2**5, one S 5 change. F is the fixed cost divided by the cost of one unit of 2**S. The fit is least squares over the 10 chunks in this repo's loop-claude archive that shipped an item, counting only those score-outcomes finds with an S. A chunk's cost is the new input tokens (input plus cache creation) and the output tokens of its worker and subagents, leaving out cache reads and judge runs. It comes to about 399k tokens fixed plus 10.9k per unit of 2**S, so F is about 36 (R² 0.24); output tokens alone give 24 (R² 0.35). 32 sits between them. The 10 chunks' (S, thousand tokens) are (1, 405), (2, 446), (2, 442), (2, 368), (2, 294), (2, 130), (3, 1027), (4, 733), (5, 754) and (5, 599). The fit holds loosely: it covers S 1 to 5 and no larger chunk, 10 points scatter widely, and a chunk that shipped several items counts whole against the S of the item its first route names. Lines changed explain little of the tokens (R² 0.07), so the fit uses S, not lines. Hours do not fit: the worker's active time, each gap capped at 10 minutes, has a median of 0.29 hours whatever S (R² 0.01), so hours don't change F. The formula charges each item the whole F, though a chunk that bundles tiny items pays it once, so such an item ranks lower than its real cost warrants. rank_todo.py --help keeps 8 in its example, which shows a valid file's shape, not this plan's F.
2026-10-16, PR #283: a panel of three readers seated as lilleman picked the spelling. Two put a Moves column holding 1.1 by 8, 1.2 by 5 first, and one put 1.1: 8 first. Two chose 2**S, since a Python reader takes ^ for XOR. All three chose one decimal of 100 * V / 2**S over three significant digits or a log. The columns L, E and I sit right before R, which rank_todo.py writes from them: of three readers seated as lilleman, two ranked that order first, since a reader meets each level before the R it builds and R sits beside S, and the third ranked it second, after an order with S before the levels.
2026-10-16, PR #283: a table in the old shape, with C, A, G and Goals columns in place of L, E, I and Moves, still ranks by the formula and weights it states, and ranking it says to reshape it, so no other project's commits stop. Reshaping it is that project's only work until done, as CLAUDE.md → "Working loop" says. The old shape's ranking is valid until todo.md item 156.
2026-10-16, lilleman, answering the review of PR #283. An item that restores a maintain goal the project breaks today is a defect: exempt as defect. Its Moves name that maintain goal and how much of it is broken, and the goal weighs as the heaviest achieve goal, since a broken maintain goal outranks any achieve goal. Every defect ranks by its score, so a trivial one waits behind valuable work. Only questions and then security findings rank first in their release: a question's answer may change other items, and a question waits for the human anyway, so ranking it first delays no chunk. An item names the most specific goal it moves, and a parent only for a move none of its sub-goals covers, so a sub-goal's move does not count twice; rank_todo.py refuses a goal named beside its own sub-goal. Each project reshapes its own todo.md; CLAUDE.md → "Working loop" makes the reshape the only work until done, as it makes writing missing premises. An item that makes this project easier to read moves code health, as the 2026-10-18 paragraph below says, and goal 1.4, since reading cost is measured in tokens per chunk.
2026-10-18, lilleman. Serves goal 1.1: every project shares one achieve goal, code health, which CLAUDE.md → "Shared goal" states once and which replaces each project's own readability goal. It ranks first among a project's achieve goals, since lilleman rates it very important while the comprehension panel's overall is under 7.0. While that overall is under 7.0, or no scoring run has measured the project, it weighs four times its weight at 7.0 or above, as UNDER_FLOOR sets. The overall is the mean of the overall means of every scoring run on the newest scored commit in docs/comprehension-history.md, as newest_commit_runs finds them. Two runs of one head measure it twice, and the newest alone would let their noise flip the weight: 7.13 and 6.88 on one head of another project would have. The review of PR #324 raised this choice. Weighing code health four times as much leaves the other achieve goals' weights as they are. So crossing 7.0 changes only the scores of the items that move code health, and of the defects, since a broken maintain goal weighs as the heaviest achieve goal. larv-review record-scoring re-ranks todo.md after it appends a run. A project that opts out of the comprehension check voids the goal, as review: a project decision may opt every chunk out … records. A README voids the goal with **Void:** code health, since <reason>. under ## Goals, and an item's Moves cell names it as in code health by 6. A panel of three readers seated as lilleman picked both 3-0: code health over code, health, C and 0, and the bold Void: line over a sentence under ## Goals or a line under ## Audience. score-outcomes counts the counter-signal's misread findings per chunk, as review: a reviewer under … records. Valid while the comprehension panel's overall is how a project measures how hard it is to read.
2026-10-15, lilleman. Serves goal 1.4: loop-claude routes a chunk's first cycle on the item the chunk takes (routing: a chunk's worker runs on the rung its item's L picks). An item lists the items that must be done before it starts in a Blocked by column, and rank_todo.py ranks each blocker above every item it blocks. The table's order is todo.md's only order: rank_todo.py fails on text beside the table under ## Items, since a prose order there, "Release 0.3.0 takes items 125, 114 and 124 first", contradicted the table and loop-claude could not read it. A decision that wants an order sets the scores instead. An item waits while it is marked question or a blocker of it is still in the table, whatever the rows' order, so a release's first row that does not wait is the item a chunk takes. A blocker the table no longer holds was finished or deleted, and is dropped, so the cell shows what still blocks. A panel of three readers seated as lilleman picked the spelling: two ranked "Blocked by" first, as the cell lists only what still blocks, and all three chose bare IDs such as 12, 14 in a column right after Release, read before the tagline and kept apart from the scores. rank_todo.py adds the column to a table without it. The tools read cells by column name, so a later column leaves a reader on an older release working; rank_todo.py, which writes every column, fails on one it does not know rather than drop it.
2026-10-18, PR #312. Serves goals 1.5 and 1.1: adf-codec renamed its next release, 0.2.1, to 0.3.0, and chunk-preflight then called 0.2.1 finished and stopped the loop on every cycle. A change that moves a release's last items elsewhere reads the same whether it renamed the release or deferred its leftovers, so the plan says which: a ## Renamed section holds one line - 0.2.1 renamed to 0.3.0 per rename, which bin/release_plan/todo_table.py's renames reads. chunk-preflight, loop-claude and larv-review's scoring-run trigger skip a marked release; they read only the first version. A release whose items moved unmarked reads as finished: the loop stops, says so and names the fix, and the trigger calls a scoring run once work has landed. So a forgotten mark costs one interrupt and never lets a release end unmeasured. rank_todo.py fails on a line of another shape and on an item filed under a marked release, and a newest plan whose marks do not parse leaves the next release unknown. A line goes once a tag at or past its release is cut. Only a rename is marked, since an unmarked move is the deferral. A panel of three readers seated as lilleman picked the spelling 3-0 over - 0.2.1 → 0.3.0 under ## Releases and a Renamed 0.2.1 = 0.3.0 line under ## Scoring: plain words need no special character to type. Valid while a rename is the only move of a release's items that the tools must tell from finishing it.
2026-11-09, lilleman. Serves goal 1.1: a test, gate leg or probe that guards a maintain goal proves the output holds it, and an item that adds one scored V 0 and ranked last. adf-codec's item 170 bundles the package with four bundlers to back its goal 8, runs on any JavaScript engine, and scored 0.0 beside items that move an achieve goal by 2. Such an item now names the maintain goal in Moves, by how much more confident the project becomes that the goal holds, 1 to 10, judged against the confidence it already has; rules/todo-items.md holds the scale. The goal weighs 0.5 per point of that move, MAINTAIN_WEIGHT in bin/release_plan/ranking.py. A defect that restores a broken maintain goal weighs it as the heaviest achieve goal, or 0.5 where that is lighter, since a broken goal outranks any achieve goal and any confidence gain; a maintain goal still vetoes an item that breaks it. The 0.5 comes from 150 distinct item and Moves pairs in 40 random todo.md commits from 2026-09-24 to 2026-11-09. The V their scores imply has quartiles 1.4, 2.6 and 4.5, and the median item earns 0.49 per point it moves a goal. At 0.5, a move of 10 is worth 5.0, about the third quartile; a move of 5 is worth 2.5, the median; a move of 1 is worth 0.5, under the tenth percentile, so only a cheap item ships. Valid while the achieve goals' weights and the formula's F keep the typical item's V near that distribution; a change to either revisits the 0.5. 2026-11-10, lilleman: the 0.5 does not change with the number of achieve goals. fejkdata has 11 achieve goals, code health included, and each weighs at most 0.105 per point, or 0.42 for code health while its comprehension overall is under 7.0, so a maintain goal's 0.5 outweighs each of them. Revisit the 0.5 when that becomes a problem, such as maintain items ranking above achieve items the human would take first.
todo.md: only a session or subagent on the project's rung or above scores or reshapes the plan; one below it drafts new items and changes to filed ones for a subagent at or above that rung to apply and score, and removes finished ones
2026-10-15, lilleman. Serves goal 1.1: a cheaper rung writes worse scores, and a wrong score routes a chunk onto the wrong rung, ranks the plan wrong and drops an item under the bar that should stay. Below the project's rung, a session or subagent may not score an item, move it between releases, split a milestone, delete an item under the bar, or rewrite a filed item. It drafts each new item, and each change to a filed item, such as a refresh a rule asks for. Before the next commit, one subagent on the project's rung or above applies and scores the drafts. One launch covers all of a chunk's drafts (goal 1.4). A security finding gets that subagent at once, since it is filed the moment it is found. Removing a finished item closes work and plans none, so any rung does it. Scoring a delegated task's L runs on any rung too: a launch on the project's rung to score each delegation would cost more than the cheaper task saves (goal 1.4).
Three places carry the rule. rules/todo-items.md states it and loads with todo.md. CLAUDE.md's delegation rule launches the scoring subagent on the rung bin/subagent-rung --plan prints: the one the task's L picks, never below the project's, so a hard scoring task still climbs. bin/loop_claude/cycle/prompts.py's review_launches names the same command to a worker below the project's rung, never a fixed rung, which would disagree with --plan on a scoring task of L 4. Valid while a worker or subagent may run below the project's rung.
worker: a chunk's worker writes the simplest change that solves its item, test first wherever a test can check the change, and reads a technical principle only where the item, a finding or its own record names it; larv-review's reviewers hold the change to the principles and to the standards in skills/larv-review/standards/
2026-10-13, lilleman through todo item 104, implemented by claude. Serves goals 1.4 and 1.5. Like red, green, refactor: the worker makes the item work, and the review passes raise it to the bar. A loop-claude worker loaded CLAUDE.md and every file under rules/, 4,247 words, and CLAUDE.md told it to read technical-principles.md too, 2,426 words more. The reviewers read the principles anyway, and a finding against one names it.
The worker keeps what it needs to write its own work. Each project's decision titles stay in its AGENTS.md, since a worker that misses a decision builds the wrong behaviour. A core of "Prose" stays in CLAUDE.md, since no reviewer reads the worker's chat. lilleman chose both on 2026-10-13. The rules for writing Goals and Audience, todo.md items and decisions stay in rules/, since writing those is the worker's job. bin/rule-hook stays: it blocks what a program can check, at no context cost. "Quality", the rules for comments and READMEs, and the examples behind "Prose" moved to skills/larv-review/standards/, which no path loads. loop-claude's judge and the prose reviewer read them, and the stability reviewer reads "Quality". They sit beside larv-review, whose passes apply them; principles/ stays where it is, since the principles auditor reads it per file.
A finding against a principle names it, so the worker reads only that one when it fixes or declines the finding. The worker still writes a failing test first wherever a test can check the change, since no reviewer can make a test come first. On 2026-10-13 lilleman widened it from code changes to anything there is to test. A chunk that changes no code, config or test, such as one that only plans, meets no principles review; the chunk that implements its items does. The prose reviewer checks that a doc sorts a list whose order carries no meaning.
The item also cut the rule that a session proposes new rules for CLAUDE.md and rules/ and restructures them after each change: changes to these rules go through this repo's chunks and their reviews, like any other change.
Valid while review rounds per pass do not rise. A principle found late, such as functional core, can cost a rewrite within a pass's two rounds. Checked 2026-11-09 over the five chunks that ran two or more passes on each side of this decision's merge: rounds per pass fell from 2.26 to 1.52, so the decision holds. Reading cost, the new input tokens before a chunk's first commit, rose in the five chunks that finished nearest each side of the merge, from a median 56,802 to 136,132; their ranges, 46k to 172k and 50k to 140k, overlap. Those workers opened or searched todo.md 31 times against 11 before, and docs/decisions.md 20 times against 8.
workflow-bench/: the remote may show the bench cases' names and commit SHAs
2026-10-02, lilleman. Serves goal 4, which keeps credentials, transcripts and memory files off the remote; a private project's name and commit ids are none of those. Valid while the bench names only cases and commits, never their code or results.