Files
claude-config/docs/decisions.md
T

236 KiB
Raw Blame History

Project principles

Each project principle states one rule that the decisions below apply; their entries hold the specifics and the evidence. The numbers name the principles, and don't rank them.

  1. Cut cost only where a measurement of archived chunks shows quality holds. Chunk bundling, the round cap, which fixes rerun a pass, a reviewer of its own for each pass, the review a branch changing only Markdown no agent follows gets, the passes kept for the release review, review opt-outs, the security pass, compaction and the routing ladder all apply it.
  2. A measurement files or ranks work, and never blocks a merge. The comprehension floor and check, and a reading-cost rise, apply it. A merge waits on a scoring run the plan calls for only until the run is recorded, whatever it scores.
  3. Each file has one writer. ~/.claude/loop-claude-models.json is written only by save_model, which the entry points, loop-claude and do-epic, both call. ~/.claude.json is Claude Code's, and ~/.claude moves only through deploy-release. The exception is ~/.claude/settings.json, which Claude Code writes from any session. Git's clean filter bin/settings_filter.py keeps each machine's model and Claude Code's key order out of every commit, and README.md → "Update" carries its other changes into this repo.
  4. A rule a program can check is enforced by a program, and reviewers rule on the rest. rule-hook and its overrides, docker-run-memory, the refused writes of reviewers under agents/, and CI with main's branch protection apply it.
  5. A chunk can't vouch for itself. What a chunk writes is approved by a review pass, by the human, or by a precedent the repo held before the chunk began. So an unanswered ask leaves the PR unmerged, the human approves the premises chunk and runs deploy-release --cut, and the judge holds a chunk open while an answer the human typed isn't recorded anywhere.
  6. An unattended run never waits on a prompt, and a lasting failure stops it. Every claude loop-claude starts bypasses permissions inside its sandbox, each claude it opens on a terminal has CLAUDE_CODE_SANDBOXED set, and interactive sessions run in auto mode with the dangerous-mode prompt skipped. A failed archive stops the loop, while a claude that cannot start, as during an update, is retried.
  7. One word names one thing, and one rule has one home. In 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. CLAUDE.md holds only the rules no path can scope, and each rules/ file loads by its paths:.

Decisions no project principle covers

  • archives: gzip each transcript in loop-claude's archive and each file in the review folders 30 days after it last changed, keeping all of them
  • bin/: a test parametrizes its cases with subTest, since pytest's parametrize doesn't reach a unittest TestCase
  • bin/: the tools run on the host's Python, with no container, and so do their tests outside CI
  • bin/: the tools send no OTLP traces, logs or metrics, and loop-claude's archive holds the trace of each cycle
  • bin/: the tools support only the latest stable Python, and the tests, written in plain unittest, run on it in four pytest-xdist workers
  • chunk-pr: the chunks of a project merge one at a time on a machine, each finishing its plan items in its turn, and a pull request that waits for an approval leaves the queue while it waits
  • Claude Code in a home of its own: a CLAUDE_CONFIG_DIR home loads CLAUDE.md, rules, agents, skills, hooks and plugins, and CLAUDE_CODE_OAUTH_TOKEN signs in there, but never under --bare
  • deploy: this repo keeps no AGENTS.md, since ~/.claude is its checkout; its principles and decision titles head docs/decisions.md, its working rules follow them there, and its .claude/settings.json excludes every .claude/CLAUDE.md, so a session in the clone loads only the clone's CLAUDE.md
  • do-epic: drives one Jira epic whose items span repos, or have none, ranked by the epic's goals, then code health, then each repo's goals, and closes the epic only once the human confirms every goal
  • epic-branch: an epic's chunks branch off and merge into a working branch its project's config names, without a person, and a person merges that branch into the default branch in one pull request
  • loop-claude: each verdict records the claude-config release and commit that ran it, the raw tokens each thread spent by model and kind since the previous outcome that recorded a spend, and the human's typed answer the judge quotes as reversing a choice the worker took on its own recommendation
  • loop-claude: each chunk runs in its own tmux window, of one tmux session per project, up to parallel-chunks at once, and needs tmux 3.2; its claude session is named after its window, its id derived from that name; a chunk's commit in the config's folder takes only the file it changed
  • 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
  • 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
  • project config: a record may name a Confluence Cloud page as confluence: and its address, the loop reads and writes it as markdown, and a write never overwrites a save made since the loop's read
  • project config: a tool that reads a file's commits says where it does not support that file, and the work goes on
  • project config: language names the prose's language by its English name, and commit-title, pull-request-title and branch are brace templates over {id} and {summary}
  • project config: plan may name a Jira Cloud epic as jira: and its address, the plan is its open child issues in backlog order, and an issue's number is the item's ID
  • project config: the loop shows a Jira description and a Confluence page as adf-codec's portable markdown, and a save whose text is the text a read showed leaves the document as Jira or Confluence holds it
  • project config: tooling-on-host = true lets a project with no container setup run its language runtime, package manager, tests and task runner on the host
  • 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
  • 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
  • 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
  • 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
  • review: the worker mutation-tests a chunk's changed lines before each stability round, in place of measuring test coverage
  • review: the worker runs the project's tests and static analysis and checks the docs for each changed name before each stability round, and hands stability-reviewer the commit
  • review: agents of one type launch in one message, not one a message before the others
  • 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
  • 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
  • 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
  • routing: loop-claude reads the items a chunk takes from the worker's latest Chunk items: line and scores them by todo.md as the default branch held it when the cycle started; the judge reports the escalation and whether a release is ready to cut
  • routing: the worker changes rung only as a chunk starts, after every second unfinished verdict, when it names a chunk item that picks a higher rung, or when it cites an escalation trigger the judge finds
  • 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
  • the repo may name bender, bender-infra and ai-sandbox
  • todo.md: an item of the next release predicts the files and parts it will touch under Touches: in its detail; chunk-preflight takes, in the plan's order, the items that overlap none taken before them as the chunks that may run at once, and the optional touch-predictions record keeps each chunk's prediction beside what it touched
  • 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 the project's readability floor or unmeasured, then the goals file'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
  • 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
  • todo.md: tools and agents read and change the plan as it stands only through bin/plan_store and todo-item; a tool that reads what a past commit held, ranks the file or checks its rank still parses todo.md
  • 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 project's review standards
  • workflow-bench/: the remote may show the bench cases' names and commit SHAs

Working rules

Routing calls: file them in the plan. A routing call is a change to the routing ladder, its steps or the delegation rule that loop-claude's figures call for. loop-claude puts each call to the human once, and appends it to routing-calls-raised.md, at the root of its archive ($LOOP_CLAUDE_TRANSCRIPTS, default ~/.claude/loop-claude-transcripts). Each line of that file is a call or a Reset, with a stamp. A call is new when it is stamped after the latest Reset and after the latest stamp that todo.md or docs/decisions.md → routing: cites.

When there are new calls, file one todo.md item to settle them, or refresh the item already filed. Its detail quotes the new calls with their stamps. It also quotes the routed-chunks table of routing-figures.md, which sits in the same folder, and none of that file's other tables, since they name other projects.

Settling a call is the human's. The chunk that settles the calls cites, in docs/decisions.md → routing:, the latest stamp it settled, whatever the human decided, so the calls are not filed again. Once a chunk that changes the ladder, its steps or the delegation rule has merged, append - <UTC time> Reset to routing-calls-raised.md. The figures then count only chunks finished after the reset, and a call settled before it may be raised again.

Decisions

archives: gzip each transcript in loop-claude's archive and each file in the review folders 30 days after it last changed, keeping all of them

2026-11-17, the worker of todo item 306. Serves goal 3, backing up the transcripts, and goal 1, whose measures read them: the routing figures, reading-cost, score-outcomes and both replays rest on the whole archive, so nothing is pruned. On 2026-11-17 the archive held 7.9 GB and ~/.local/state/larv-review 1.1 GB, both growing with every chunk.

  • What. compress-archives, run daily from the crontab line in README.md → "Install", gzips each file that last changed over 30 days ago, but for a lock, *.lock: a lock is held by its name and never written, so its age doesn't say that it is out of use. The gzip is <name>.gz, beside the plain name, with the same times. In the archive it takes only the transcripts, *.jsonl, which held 7.8 GB of the 7.9 GB; the outcomes files stay plain, since loop-claude appends to them every cycle. In the review folders it takes every file, since the probes' build output fills most of them.
  • Last changed. A file's age is the later of its mtime and its ctime. A copy or an unpacked archive keeps old mtimes, but its ctime is when it landed, so a tree a chunk or a replay unpacks today stays plain while they use it.
  • Safely. It writes the gzip, reads it back, syncs it to disk, and only then removes the plain file. It removes it only where the gzip read back the same bytes and the plain file didn't change while it was compressed. At the first failure it stops and exits 1, keeping that file plain, as a failed archive stops loop-claude.
  • Readers. The tools that read old files in either folder, the archive's readers and review-replay, read a file by its plain name through bin/text_files/compressed.py. A plain file beside its gzip wins, since it was written later. A session file that grows after its copy was compressed lands plain beside the gzip, which holds a prefix of it, so the next run's gzip doesn't lose anything. A report rewritten whole after it was gzipped also lands plain beside its gzip, and the next run's gzip replaces the older one, as rewriting the plain file replaced the older bytes before.
  • Why gzip. Python 3.14's compression.zstd needs a Python built with libzstd, and this machine's lacks _zstd; gzip is in every build (goal 2). On 400 archived transcripts older than 30 days, gzip shrank their 609 MB to 23%, at about 29 MB a second.
  • Why 30 days. A chunk's files stop changing once it merges, and chunks run for hours or days. Since every reader reads both forms, the threshold sets only how long a file stays plain.
  • Backup. Both folders sit under $HOME, on the filesystem that holds ~/code and ~/.claude (ai-sandbox's /dev/vda3 on 2026-11-17), so backing that volume up, as item 1 waits for, covers both. README.md → "Install" names them, since the review folders lie outside ~/.claude.
  • One writer. Project principle 3 holds: the tool that writes a plain file stays its only writer, and compress-archives is the only writer of its gzip.

Valid while every tool that reads old files in the two folders reads through text_files/compressed.py.

bin/: a test parametrizes its cases with subTest, since pytest's parametrize doesn't reach a unittest TestCase

2026-11-12, lilleman, from the release review of 0.9.0. Applies principles/technical-principles.md → "Most code should have automated tests", whose "parametrize the cases" asks for one reported result per case. The tests are plain unittest, run by pytest, and pytest's parametrize doesn't work on a TestCase method; subTest is the unittest mechanism that does: each case reports and fails on its own, with its parameters named. A test that loops over its cases itself, outside subTest, or holds a branch, is still a breach. Valid while the tests stay in plain unittest.

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' Outcome became Result, and rule-hook's became Checked. The command score-outcomes keeps its name, since renaming it would be a change of its own: files every project loads, such as rules/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, became Reading.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 send no OTLP traces, logs or metrics, and loop-claude's archive holds the trace of each cycle

2026-11-16, lilleman, from the release review of 0.11.0. The tools send no traces, logs or metrics over OTLP, the OpenTelemetry protocol, to any collector. That applies the last sub-bullet of principles/technical-principles.md → "All critical flows should have good traces": a tool that runs only on its user's own machine keeps its trace there. lilleman ruled that the tools never send to a collector, and the release review of 0.12.0 wrote the sub-bullet from that ruling. Serves goal 4: the tools run on the human's own machines, beside client code and transcripts, and whatever goes to a collector leaves the machine. loop-claude's archive holds the trace of each cycle instead: its transcripts and its .outcomes.md entry, from the worker's first run to the judge's verdict. Valid while goal 4 holds.

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.

chunk-pr: the chunks of a project merge one at a time on a machine, each finishing its plan items in its turn, and a pull request that waits for an approval leaves the queue while it waits

2026-11-15, lilleman's call of 2026-11-13 in item 374, which split item 361. Serves goals 1.5 and 1.4: with several chunks open, every chunk removed its item from todo.md and added a bullet to CHANGELOG.md in its branch, so each merge left the others a conflict, a gate rerun and often a review round. chunk-pr merge --finish <ID> now makes those edits in the chunk's turn, on top of every chunk merged before. The worker's choices follow. The first differs from the call, and the rest settle what it left open:

  • A merge of the default branch, where the call said rebase. A rebase rewrites commits the pull request already shows. The forge then drops the approval and the review threads' places. rule-hook counts a pass's rounds by the branch's commit titles, and a rebase gives each of those commits a new hash. chunk-pr sync already merges, and the turn reuses it.
  • The queue is a file in the git folder the checkout's worktrees share, held with flock for the turn (bin/chunk_pr/main.py → QUEUE). Every chunk of the project on the machine finds it without a config or a key. Two machines don't share it: there the second chunk merges without the first one's changes in its head, unless the branch protection requires an up-to-date branch. A turn lasts as long as its checks, which chunk-pr waits 30 minutes for on Gitea. So a merge waits 30 minutes for its turn, then fails naming the pull request that held the queue last, whose number the holder writes into the file.
  • The turn holds the queue through the checks, so what merges is what the checks ran on. A project without forge checks waits the minute chunk-pr --help names.
  • The wait for an approval is outside the turn. The first turn pushes the finished branch, so the approver reads what merges. Once approved, the pull request takes a new turn. Where the default branch moved meanwhile, that turn merges it in, and a branch protection that dismisses approvals on a push asks the approver again. A finish that fails is pushed with whatever the turn merged in, so the pull request's head stays the commit checked out. larv-review scoring-run-owed runs after the finish is committed, since it counts as shipped the items the committed plan no longer holds.
  • A reviewer's comment ends the wait, in place of the loop watching for one. chunk-pr merge runs in the worker's own session, so its failure is what resumes the worker, which answers and runs it again. A comment that waits is a review thread nobody resolved whose last comment someone other than the pull request's author wrote: the worker answers as that author, so an answered thread waits for the reviewer again. A comment outside a thread doesn't end the wait, since bots write those too. An approved pull request with such a thread stays unmerged too: a client's reviewer who approves and asks for one more thing gets an answer first.
  • A paired ruling runs again once the default branch has moved past it, on the last measured commit as before: review: the comprehension check records … says why the base stays. chunk-pr merge stops while the default branch holds commits the branch's last commit of a ruling doesn't, whoever merged them in: the turn, chunk-pr sync or the worker after a conflict. What the ruling says never stops the merge (project principle 2). A scoring run reads no base, so it stays.
  • An item the plan doesn't hold is named on merge's last line, not refused. chunk-pr cannot tell an item an earlier run finished from a mistyped ID, so the reader does. Such a run still commits the plan and the changelog, since the earlier run may have stopped between todo-item finish and its commit. chunk-pr checks that an ID is a number before its turn, and leaves every other rule of todo-item finish to that tool.

Valid while a chunk's worker runs chunk-pr merge itself, and one machine runs a project's loops.

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/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.

Claude Code in a home of its own: a CLAUDE_CONFIG_DIR home loads CLAUDE.md, rules, agents, skills, hooks and plugins, and CLAUDE_CODE_OAUTH_TOKEN signs in there, but never under --bare

2026-11-20, lilleman's standalone-install plan. Serves goal 2, so the setup installs without taking over the human's ~/.claude, and goal 4: a home of its own keeps the loop's transcripts and token apart from the human's. The plan therefore runs every claude the loop starts in a home of its own, and doesn't load the setup with --plugin-dir, --settings and --append-system-prompt-file over the human's home. The probes ran on Claude Code 2.1.330, on throwaway homes, never the human's. A mock Messages API at ANTHROPIC_BASE_URL recorded each request and answered the first with a tool call that reads a file, so the system prompt and the tool results show what loaded, with no real token. Valid for Claude Code 2.1.330; repeat the probes when its version changes.

  • Loads from $CLAUDE_CONFIG_DIR: CLAUDE.md (in the system prompt), rules/*.md (one with paths: entered the context after the model read a matching file, not before), agents/, skills/, the hooks of settings.json (a SessionStart hook ran) and plugins. claude plugin marketplace add and claude plugin install write to <home>/plugins, and the installed plugin's skill is listed. .claude.json lands in the home too, so the human's ~/.claude.json stays theirs.
  • Signs in by CLAUDE_CODE_OAUTH_TOKEN: the request carried Authorization: Bearer <token> with the oauth-2025-04-20 beta, and claude auth status said loggedIn: true, authMethod: oauth_token. The home didn't hold a credentials file. Without the variable the home is loggedIn: false. Not tested: that Anthropic accepts a real token, since claude setup-token needs the human's browser sign-in. The authentication docs say the token lasts one year and can only make model requests; neither is tested, and the first real run shows whether it signs in.
  • --bare can't use that token. With CLAUDE_CODE_OAUTH_TOKEN, it says Not logged in · Please run /login and doesn't send a request. With ANTHROPIC_API_KEY it signs in, but doesn't load anything from the home (CLAUDE.md, rules, agents or skills) and offers only Bash, Edit and Read. So a container that signs in by a long-lived token runs without --bare; its fresh home is empty, so nothing of the human's loads there either. The project's CLAUDE.md loads from the working folder, and its AGENTS.md only where the project has no CLAUDE.md.
  • Transcripts land in <home>/projects/<working folder's path, with each / as ->/<session id>.jsonl. --no-session-persistence doesn't write one, only an empty memory folder, so a bench that uses it reads the run from --output-format stream-json.
  • The model catalog sits in <home>/cache/model-catalog/ on the human's machine, as bin/loop_state/paths.py expects. The throwaway homes didn't write one, since the mock was the only server they reached. Not tested: whether a long-lived-token session writes it. Where it doesn't, bin/chunk_driver/project/model_choice.py prints no model catalog cached and takes a typed model name.

comprehension floor: every dimension and the overall at the project's readability floor or above is the target, and no score blocks a 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 doesn't block anything, and review: the comprehension check records … says why. Valid while the scoring run keeps its four seats. 2026-11-12, lilleman, through todo item 358: a project's config sets this floor as readability-floor, its readability floor, since legacy code scores low. It is 7.0 where left out, and the signal stays that the score rises. Readers seated as the person who writes the config picked the key, 2 of 3.

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: this repo keeps no AGENTS.md, since ~/.claude is its checkout; its principles and decision titles head docs/decisions.md, its working rules follow them there, and its .claude/settings.json excludes every .claude/CLAUDE.md, so a session in the clone loads only the clone's CLAUDE.md

2026-11-11, lilleman through item 314. Serves goal 1.4. Claude Code loaded ~/.claude/AGENTS.md into every other project's sessions, and each 1,000 tokens every thread starts with cost $68.60 of the $9,154 spent from 2026-09-30 to 2026-11-11: the 14.4 KB file cost about 2.1% of spend, and put this repo's rules in front of other projects. Other projects keep the name AGENTS.md, so the setup stays portable to other harnesses. The working rules sit there too, rather than in .claude/rules/, since loop-claude's judge reads the decision log and no project's .claude/rules/. In the clone, the release's ~/.claude/CLAUDE.md and the clone's both loaded, about 0.9% of spend; the exclude drops the release's, so a chunk runs under the rules it is changing. A session working in ~/.claude itself loads no CLAUDE.md, since there both are the same file; none works there, as the entry above says.

Valid while ~/.claude is a checkout of this repo.

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.

do-epic: drives one Jira epic whose items span repos, or have none, ranked by the epic's goals, then code health, then each repo's goals, and closes the epic only once the human confirms every goal

2026-11-18, lilleman's answers to claude's questions while planning release 0.12.0. Serves goal 1, so development scales past one repo, and goal 1.6, since the epic stays in the client's Jira. Valid while Jira is the only backend; another backend goes behind the same interface.

  • What it is. do-epic <EPIC-KEY> is a sibling of loop-claude, built on the same cycle, judge, interrupt, tmux and routing packages, not a copy (goal 1.3). It runs one tmux session per epic.
  • Machine settings. ~/.claude-projects/do-epic/ holds config.toml (the Jira site, env-file, the folder repos are cloned into, the default language, and the model for a no-repo item) and repo-rule.md. repo-rule.md is a prose instruction that says how to tell an item's repo. It is the same for every epic on the machine. On the first machine, an item's label that equals a repo's name names that repo. A [label-repos] table in config.toml maps a team's own label to a repo, so do-epic reads that label as a pick without a claude call.
  • The epic's description is its record. It holds ## Goals, ## Audience, ## Scoring (formula and bar), ## Decisions and a language line. do-epic writes all of it, but it changes Goals or Audience only after the human approves in an interrupt.
  • Items live only in the epic. A repo's own plan never mirrors them. Where repo-rule.md leaves an item's repo unclear, do-epic asks. An item without a repo is either Claude's work, done without a PR, or a human task; where the item doesn't say which, do-epic asks.
  • One item, several repos. do-epic splits such an item when it plans it, into one Jira sub-task per repo, each labelled for its repo. The parent tracks the whole change. A person's issue is split too, with a comment for the team. An item a person filed a sub-task under counts as split already: do-epic works it through the team's own sub-tasks and doesn't file any of its own. It plans no such sub-task, so one without a label waits for the team's. It moves such an item itself (lilleman's call of 2026-11-20), since every issue the item blocks waits until the item moves, and the team's automation sees a pull request only on the sub-task that carries it. Once every sub-task is done, the item moves to done. Once every sub-task has landed, each done or in one of jira-unblocking-statuses, the item moves by the transition jira-sub-tasks-landed-transition names, which must lead to one of those statuses. A move that is not made is said, and the run goes on.
  • Ranking. Score, then Blocked by, in one weight chain: the epic's achieve goals, then code health, then the repo's goals. Where the epic and a repo disagree, the epic wins. do-epic re-ranks the issues it filed in Jira's backlog to match. A person's issue keeps its rank there: goal 1.6 has the loop plug in without changing what the owners keep. On 2026-11-20 the human chose that the order the issues start in is do-epic's, while the board's order stays the team's: do-epic starts the open issues by score. Where two or more may start, it scores each of them that holds no scores, a person's included but not a human's task, and tells the team the scores in a comment. It never overwrites scores an issue holds. An issue that cannot be scored starts after those that can, in the backlog's order; where no order of score can be made at all, such as without the epic's formula, every issue starts in the backlog's order and do-epic says why.
  • Releases. An epic item has no release. It ships into its repo's unreleased work: where the repo publishes something others consume, a bullet under CHANGELOG.md → ## Unreleased, or nothing where the repo's plan is in Jira. The issue is no item of the repo's plan, so the chunk's worker writes the bullet in its branch and runs chunk-pr merge without --finish.
  • Repos. A repo's name is its main checkout's folder name, and a project config names that checkout. A missing checkout is cloned from the host of the epic's other repos; where unsure, do-epic asks. Unsure means the other repos don't all sit under one host and owner (the same host spelt as https and as ssh counts as two), an origin can't be read or isn't an https, ssh or scp-style address, the folder to clone into holds something else, or the clone fails. A repo no config names is cloned into the clone folder, and the human is asked to write its config. Each chunk uses its repo's model, routing, and language for commits and PRs. Jira text is in the epic's language, or else the machine's default.
  • Running. The epic caps the chunks running at once, and each repo's parallel-chunks still applies. do-epic and loop-claude never run chunks in the same repo at once. The cap is a line of the epic's description, **Max parallel chunks:** 2, and 1 without it, as parallel-chunks is. A repo's parallel-chunks counts the chunks of every epic in its checkout. Each window is named for its issue's key, and a tmux window option, @chunk-root, names the folder its chunk works in, which is how loop-claude sees do-epic's chunks in a checkout. do-epic and loop-claude each hold the checkout's starting lock from checking the checkout's chunks to starting a window there. A chunk without a repo works in ~/.local/state/do-epic/<EPIC-KEY>/. do-epic archives its cycles under ~/.claude/do-epic-transcripts/, not in loop-claude's archive, whose readers parse loop-claude's prompts. An open issue runs once a label records its repo; until do-epic picks repos itself, an issue without one waits, and do-epic <EPIC-KEY> says so.
  • Long gates. A chunk whose PR waits on a gate, such as a human approval, parks. It keeps its worktree, PR and session, and its state is in a file that survives a reboot. A parked chunk takes no running slot, and the items it blocks wait. do-epic polls the forge and resumes the chunk's session when the gate passes or a reviewer comments. It fixes reasonable feedback, replies to the rest, and changes the setup so review would have caught it. do-epic <key> --status and the tmux window names show what each chunk waits on. A gate is a pull request's pending checks or, on GitHub, the approval its branch protection requires; a draft waits on neither, since its worker has yet to mark it ready. On Gitea a draft is a pull request whose title opens with WIP: or [WIP], Gitea's default WORK_IN_PROGRESS_PREFIXES. Changes a reviewer requested resume the chunk only while that review was made on the pull request's head commit and the pull request's author has not commented or replied after it; once the worker pushed or replied, the chunk parks on a new review, since GitHub keeps the decision until the reviewer reviews again. The chunk's window reads the forge once a minute, which no forge's rate limit notices. A chunk resumes only into a free slot, under the limits a starting chunk meets, and stays parked until then. do-epic <key> starts a parked chunk's window again whatever the limits, since the chunk stays parked. do-epic sets CHUNK_PR_PARKS=1 for each worker, so chunk-pr merge fails at once where the pull request awaits an approval, and the worker's run doesn't hold a slot while the pull request waits. In a repo whose config sets merge = "human", the merge itself is a gate: chunk-pr merge leaves the pull request ready, the chunk parks on your merge once nothing else holds the pull request, and it resumes when the forge no longer reports the pull request open, to clean up and finish. It resumes too once the pull request conflicts with its base branch, or is behind it where GitHub's branch protection requires an up-to-date branch, so the person finds a pull request they can merge. The worker then runs chunk-pr merge again, which levels the branch, waits for the checks and leaves the pull request ready. A chunk whose cycle ends on such a pull request is not handed on: its worker is told after each cycle until the pull request merges into its base. While GitHub still computes whether the pull request merges, the chunk stays parked until the next read. Gitea also reports a pull request as not mergeable for the seconds it checks for conflicts. A read in those seconds resumes the chunk for a run that doesn't change anything, which costs less than reading every gate twice to tell the two apart. The judge may rule such a chunk finished while its pull request is open, since its worker ends each run there. So do-epic reads a gate it could not read again before it hands the chunk on, and tells the worker once to remove a worktree whose pull request is no longer open.
  • Human tasks. do-epic leaves a human task's issue as the team filed it. The task gets a window of its own while it is open, no issue blocks it, and it blocks another open issue. The window DMs the human once, through the notifier of the first repo whose project config names one (the repos of the issues it holds up come first, then those of the epic's other issues; where none does, the window says so), shows as parked (awaits a human's task) so that it doesn't take a running slot, and polls the epic every minute until the task no longer holds up an open issue. Then the issues it held up may start. A window that starts again, as after a reboot, DMs again.
  • Findings. A finding about the epic's goals is filed in the epic. A finding about a repo's goals follows that repo's rules. Where unsure which, do-epic asks. A set of new items toward an epic goal needs the human's approval before work starts; a finding filed during a chunk doesn't.
  • Finishing. When the epic holds no open item: release-review passes on each repo the epic changed, then the items they file, then the human confirms each achieve goal and that no maintain goal has a defect. For a goal that isn't met, do-epic proposes items for approval. Then a summary comment on the epic, and closing the epic in Jira, as the very last step.
  • Tests. Black-box tests run against a fake Jira backend. An opt-in e2e test runs as its own command against a sandbox epic on a real Jira site.

epic-branch: an epic's chunks branch off and merge into a working branch its project's config names, without a person, and a person merges that branch into the default branch in one pull request

2026-11-20, lilleman's call. Serves goals 1 and 1.6: a team may rule that only a person merges into its default branch. Such a team was asked to merge once per chunk, and reviewed an epic as many small pull requests. With epic-branch set, the loop asks once per epic, and the team keeps its rule. Valid while that rule covers only a team's default and protected branches.

  • The setting. epic-branch in a project's config is a template with {epic} for the epic's key, such as "{epic}". Left out, everything works as before. Under chunk-preflight the key is that of the Jira epic plan names, so a plan kept in a file has no working branch. Under do-epic it is the key of the epic do-epic drives.
  • A chunk's base is recorded in git. git config branch.<chunk's branch>.chunk-base <epic's working branch>, in the checkout's shared config (git_repo.CHUNK_BASE). git_repo.default_ref answers origin/<epic's working branch> on such a branch, so each tool that measures a chunk against its base reads the chunk's own commits. Deleting the branch removes the record.
  • The branch stays level by a merge commit, made without a checkout. epic_branch.levelled makes the branch on origin off the default branch, or merges the default branch into it with git merge-tree --write-tree, which needs git 2.38 or later, and git commit-tree, and pushes without force. It asks origin itself whether it has the branch, with git ls-remote, since a fetch keeps a checkout's origin/<branch> after origin deleted the branch. So a chunk that starts after the epic's branch merged and was deleted gets a fresh branch off the default branch, never the commits the deleted one held. chunk-preflight runs it before it makes a chunk's worktree, do-epic as a chunk's window starts, and chunk-pr open-epic before it opens the epic's pull request. open-epic refuses where origin has no such branch, since a branch made there would be a stray one. A conflict stops the chunk and asks a person to merge by hand: a resolution picks between two teams' changes, which is theirs to pick.
  • The chunk merges without a person. chunk-pr merge into an epic's working branch ignores merge = "human" and wait-for-approval, and do-epic parks no such chunk on a person's merge. lilleman's call: the team's rule against merging without a go-ahead covers the default branch and protected branches. The pull request from the epic's working branch into the default branch is opened ready and never merged by the loop. do-epic's finishing chunk opens it with chunk-pr open-epic; under loop-claude the human runs that command.
  • The forge's base must agree with the recorded one. The record says whether a person merges, and the forge says where the pull request lands, so the two must not differ. chunk-pr ready and merge, and do-epic's gate, read the pull request's base from the forge (forge.pulls.other_base). They fail, naming both branches, where it differs from the recorded base, or from the default branch where the checkout records none. A person then changes the pull request's base on the forge, or the record. chunk-preflight and do-epic record the base for a chunk they continue too, since the setting sends every chunk of the epic into the working branch. So a pull request that was open into the default branch when the setting was turned on fails this check until a person changes its base or merges it. do-epic parks a chunk, and moves its issue, by the base it recorded as the chunk's window started, never by the config alone.
  • A review is asked for by a comment. An auto-reviewer may review on its own only pull requests into the default branch. review-request-comment holds the comment that asks it, which chunk-pr ready and chunk-pr push post on a pull request into an epic's working branch. The worker waits for the review as for any auto-reviewer.
  • do-epic moves the issue itself. A team's automation fires only for pull requests into the default branch. jira-pull-request-open-status names the status of an issue whose chunk parks with its pull request open, and jira-pull-request-merged-status the one once it has merged. The first move is made as the chunk parks, since that is where do-epic learns of the pull request; one that opens and merges within a single run of the worker skips it. Where the workflow then offers no way straight to the merged status, do-epic moves the issue through the open status first. Each setting names a status, and do-epic takes whichever transition leads there.
  • An issue at the merged status counts as done for the epic's end. The release reviews and the finishing chunk come before a person merges the epic's working branch, and Jira counts the issues done only after. So finish.landed reads such an issue as done, wherever do-epic's config names the status. Without the setting, the finishing waits for Jira as before.
  • The epic's other repos. Where a chunk's tests run other repos of the epic, its worker runs each at its branch of the same name where it has one, else at its default branch, and its summary names each repo that ran at the default branch. A team's shared test harness needs an option to pick the branch; that is the team's change.

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 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 in the project's review standards, the folder its config sets as 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 the project's review standards does not count: the judge reads those files where they are kept, not in the chunk's worktree, so they hold the write only once it merges and reaches there. 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" doesn't hold anything 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 opens on a terminal has CLAUDE_CODE_SANDBOXED set, so Claude Code skips its trust dialog and doesn't write ~/.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 and do-epic write, through one locked function

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 one writer: save_model in bin/chunk_driver/project/model_choice.py. The entry points, loop-claude and do-epic, both call it, and it holds a lock from its read to its write. Every claude they start 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: each chunk runs in its own tmux window, of one tmux session per project, up to parallel-chunks at once, and needs tmux 3.2; its claude session is named after its window, its id derived from that name; a chunk's commit in the config's folder takes only the file it changed

2026-09-21, lilleman; revised 2026-09-30 by lilleman. Serves goal 1. Ids derived from names keep the session picker at one entry per running loop and make any transcript under those ids 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.

2026-11-15, lilleman's call of 2026-11-13 in item 372, which split item 361: loops of one project, each on its own chunk, run side by side without touching each other's state. The worker's choices, for what the call left open:

  • The archive and the route needed no change. The archive keys each chunk by its own transcript's first line, and a rerun's route comes from the latest verdict on that transcript, so both follow the session. The routing figures are measured across all projects, under their own lock.
  • git's own lock serializes the config folder's commits, in place of the file lock the item asked for. git commit holds .git/index.lock, so of two commits at once the second fails, and the worker tries again. A wrapper lock would only make it wait, and a command spelled flock … git commit would pass rule-hook unchecked, since it reads only a command that starts with git. What two chunks could still break is one committing the file the other staged, so each commits only its own file, as git commit -m <title> -- <file> (CLAUDE.md → "Git, commits, and PRs").

2026-11-16, lilleman's second call of 2026-11-13 splitting item 361: lilleman knows tmux and prefers it. Each chunk runs in its own window of one tmux session per project, loop-<key>, up to the number the config's parallel-chunks sets, 1 by default. tmux runs even at 1, so every project runs the same workflow (goal 1.3). A window waiting for the human ends its name in ? and rings the bell, and the DM names <session>:<window>. The worker's choices, for what the call left open (bin/agent_cycle/tmux.py, bin/loop_claude/loop/chunk_windows.py):

  • The window, in place of item 372's lock-file slot, names the claude session, as A <key> loop-claude item-372. The loop-claude the human runs starts the windows and attaches; each window runs loop-claude --chunk <window>, so a loop knows its chunk before it names its claude session, and a rerun still resumes the chunk left open.
  • A finishing chunk starts the next; only the human restarts a stopped one. As its chunk finishes, a window's loop starts each chunk that may start then and exits, so its window closes. remain-on-exit failed keeps the window of a loop that stopped any other way, Ctrl-C included, with its last lines, and its chunk keeps its items. A finishing chunk never restarts it, since the human may have stopped it on purpose; the next loop-claude <task> starts it again before any other chunk. One flock under ~/.local/state/loop-claude/<key>/ serializes the starts, so two chunks finishing together don't start one chunk twice.
  • The other chunks' items are told, not locked. A fresh worker is told the items each other chunk holds, running or stopped: its window's item and those on its latest Chunk items: line. A chunk starts beside the others only where its item's Touches: prediction overlaps none of those items' predictions, since the plan's next item, which chunk-preflight's pick checks against, may already have merged.
  • The tmux session names its checkout. Two checkouts whose keys differ only in a character other than a letter, a digit, _ or - map to one session name, so the session's @loop-root option names the checkout that made it, and another checkout's loop-claude refuses it.
  • tmux 3.2 is the oldest that has every command and option used. tmux's CHANGES dates the newest two to "CHANGES FROM 3.1c TO 3.2": new-session -e, and the remain-on-exit value that keeps only a failed program's pane.
  • A loop started before this release isn't moved into a window. One that reloads into this release starts its project's windows afresh, and leaves its chunk's open claude session, named for its slot, in the session picker. Carrying a slot's session into a window is not worth the code for a one-human audience, so the changelog asks the human to finish or stop every running loop before taking the release.

Valid while claude takes --session-id and resumes by it, and the human runs loop-claude where tmux is installed.

loop-claude: the archive keeps the raw transcript and each judge run, a failed archive stops the loop, and a replay keeps its runs and report in a replays/ folder of the archive

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. The judge's runs are archived too, as judge/<sha256>.json in the chunk's folder: the prompt it read and its json reply. Together they are its whole transcript, since it runs with no tools and one turn. A run is kept whole and deduplicated by hash, and the outcome of the verdict, interrupt or rejected reply it produced names it on a Judge run: line. Keeping it whole costs little: a prompt is at most JUDGE_PROMPT_CHARS, 400,000 characters. Measured 2026-11-17, the archive's 911 judge lines come to at most 0.36 GB of prompts, against 3.5 GB in its 1,211 transcript copies, the largest 23.4 MB. The judge is still priced from its Judge cost: line, which is claude's own total for the run, and the Spent block counts the live reply's tokens; the archived reply keeps its usage for a later reader, and nothing reads it back. judge-replay replays a verdict on its archived prompt where there is one. Valid while transcripts, and the judge's prompts, stay small enough to copy whole; archives: gzip each transcript in loop-claude's archive and each file in the review folders 30 days after it last changed, keeping all of them keeps the copies small on disk.

2026-11-17, lilleman, todo item 304. Serves goals 1.4 and 3. judge-replay and review-replay each decide which rung a review pass or the judge may run on, so their runs stay checkable and re-priceable once a decision is questioned. They keep their runs in replays/<tool>-<arguments>-<UTC stamp>/ in the archive's root:

  • One <sha256>.jsonl file per run, whether it failed or not. It starts with a header line holding claude's arguments, working directory, prompt, exit code and stderr, and goes on with claude's stream-json output as printed, whose last line is the reply the replay read. A reviewer's tool calls are in it.
  • result.md, the report the tool printed.
  • A run that repeats another word for word is kept once. A folder that can't be written is reported on stderr and doesn't stop the replay.

claude_reply reads stream-json for every caller, so the judge's runs are streams too; the archive's JudgeRun stays as it was, since a judge has no tools and one turn. Valid while transcripts stay small enough to copy whole.

loop-claude: each verdict records the claude-config release and commit that ran it, the raw tokens each thread spent by model and kind since the previous outcome that recorded a spend, and the human's typed answer the judge quotes as reversing a choice the worker took on its own recommendation

2026-11-12, lilleman, todo item 305. Serves goals 1, 1.2 and 1.4. A change to the setup can be judged only by comparing chunks run before it with chunks run after, so each verdict, interrupt and quoted answer in loop-claude's archive records three things beside its judge lines.

  • Config: <release> (<commit>): git describe and the commit of ~/.claude, so outcomes group by the setup that produced them. Where git can't tell, it records unknown and why, on one line.
  • A Spent since block: the raw tokens each thread spent, by model and by kind (input, cache write 5m, cache write 1h, cache read, output), then the list prices in force, from bin/model_routing/prices.py. The threads are the worker's main thread, each subagent by its agent type and description, and the judge run that ruled. Each message counts once, by its id. The stretch runs from the previous outcome that recorded a spend, so what a /talk or a stopped run spent between rulings is counted once. It keeps tokens, since prices change. The prices recorded beside them give what the stretch cost when it ran. Claude Code doesn't report thinking apart from output, so it is left in output. The judge's tokens come from its json reply's usage, which the archived judge run holds too.
  • A Reversed: quote: the human's typed answer that overrides a choice the worker took on its own recommendation and recorded. The judge quotes the latest such [human] line; loop-claude keeps the whole typed answer that holds the quote verbatim, and drops a quote no typed answer holds. score-outcomes counts the distinct answers per finished chunk. That count is goal 1.2's counter-signal, and the 2026-11-08 entry of loop-claude: a judge decides each interrupt… is valid only while it stays low. It counts only chunks that record a Config line, since earlier judges didn't look for reversals.

Valid while score-outcomes reads the reversals from the archive.

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/agent_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/chunk_driver/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, sed and head. Steering the tool would not change how much is read: the worker's sed ranges 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 an outline script 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 LSP tool, through a pyright plugin built from the marketplace manifest with pyright-langserver on 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 updatedToolOutput allows, 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 headless claude -p with 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 and claude --bare need 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 loaded as user instructions into every project's sessions until 2026-11-11, when they moved out of ~/.claude), the project's AGENTS.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: disableBundledSkills would 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-claude: the worker's claude saves a Bash result of more than 6,000 characters to a file, and rule-hook refuses a Read of a session transcript

2026-11-18, claude, as the plan item that asked for the ceiling set out. Applies project principle 1; serves goal 1.4.

loop-claude hands each worker's claude BASH_MAX_OUTPUT_LENGTH=6000 (worker_environment in bin/agent_cycle/run.py, the value in bin/claude_code/output_limits.py). Claude Code then saves a longer Bash result to a file under ~/.claude/projects/<project>/<session>/tool-results/ and hands the model the path and the first 2,000 characters, which a probe on 2026-11-17 confirmed. A subagent inherits the variable, so every reviewer the worker launches gets it too. The archive held 7,870 Bash results over 3,000 characters in workers (about $305 of carried context) and about $145 more in stability reviewers; a ceiling of 6,000 characters would have removed $228 of the workers', 10,000 characters $122.

rule-hook's transcript-read rule refuses a Read of a .jsonl file under ~/.claude/projects: a session transcript holds every tool result of its session, and the archive's Reads of old ones cost $46. It doesn't refuse a Read of tool-results/*.txt, which the ceiling hands the model, and it checks no Grep or Bash command. It can't be overridden, since a Read carries no text for a marker.

The check, review-replay stability claude-opus-5-5 --bash-ceiling on 2026-11-18: 10 archived stability rounds holding 25 🔴 and 🟡 findings, replayed three times as archived and once under the ceiling. The three as archived found 17, 15 and 17 findings, and missed 1, 3 and 2 of those that both of the other two found. Under the ceiling the replay found 18, and missed 0 of the 14 that both of the first two found, so it passes (0 is no more than 3). Its archive is replays/review-replay-stability-claude-opus-5-5-bash-ceiling-20261118T095822Z. The decision of 2026-10-27 found that a 12k cap on a reviewer's tool output cost stability reviewers a finding, 3 of 6 against 4 of 6. That cap left no file to read, and the three replays as archived here measure the noise of an unchanged reviewer.

Only the stability pass was replayed, since the archive's long Bash results are the workers' and the stability reviewers'. --read-limit runs the same replay for the Read limit (CLAUDE_CODE_FILE_READ_MAX_OUTPUT_TOKENS); its hand-over waits for the replays of the other passes, which the plan holds as an item.

Valid while Claude Code saves a Bash result over the ceiling to a file and hands the model its path.

loop: a step whose result a program can check, or whose trigger is a condition, moves from prose into do-release's code, and the model keeps each step that needs the meaning of what it reads, returning output that code checks

2026-11-20, lilleman, in the session that planned the standalone install. Serves goals 1.1 and 1.4, and applies project principle 4 to the flow of a chunk. Prose that tells an agent to run a step leaves the agent to remember it, in order, every time, and rule-hook then guards a flow nobody owns. todo.md items 487 and 498 move larv-review's passes and the chunk's lifecycle into do-release, and item 488 cuts the prose they replace. A model step stays coarse, such as implementing an item, since many small calls each reread the context and raise reading cost.

Valid while tokens, 🔴 and 🟡 findings and interrupts per chunk don't rise against the chunks before the change; todo.md item 497 measures it.

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-16, lilleman: rule-hook checks a run through uv run, poetry run, sudo and doas too, such as uv run mutmut run and sudo docker build, since project principle 4 has a program enforce a rule it can check. The 2026-11-04 note had let such forms pass until one became 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 code health and goal 1.4, whose counter-signal is a rising reading cost: 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 code health and goal 1.4, whose counter-signal is reading cost: measured from real work, at no model cost. 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 ❓ or a prose finding doesn't rerun any pass, and a fix for a 🟡 reruns the pass that raised it only when the fix weakens, skips or guards a test; the stability pass doesn't rerun on a round's fixes where every 🔴 and 🟡 of that round asked only that a named mutant be killed or a named failing test pass, and the tests and the mutation command run clean on the fixes

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 change only what a user wouldn't 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 change only what a user wouldn't 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.

2026-11-12, lilleman through todo item 308. Serves goal 1.4. Since the worker runs the mutation command before each stability round, a finding that asks only that a named mutant be killed or a named failing test pass has an answer a run can check. The archive from 2026-09-30 to 2026-11-12 holds 326 stability reports of round 2 or later, from 13 projects, and 81 of those reports open with BLOCK (stability-skip-count/). For each of the 326, the 🔴 and 🟡 lines of the report before it were matched on mutant and test-failure wording. Every such line matched in 5 of those earlier reports. Read by hand, 1 of the 5 asked only that a failing test pass, and the round 2 after each of the 5 approved. So none of the 81 BLOCKs fell in a round this skips. The skip needs every 🟡 to be of that kind too: in one chunk on 2026-11-12, round 1's only 🔴 was a red suite, and round 2 blocked on a 🟡 whose answer was wrong, which no test or mutant showed. A fix may not edit the named failing test, since a test made to pass that way doesn't show anything. Fixes from such a round still rerun every other pass whose row they meet. Valid while code that such a skipped round's fixes wrote is rarely what a later chunk's 🔴 findings fix.

2026-11-18, lilleman through todo item 399. Serves goals 1.1 and 1.4. The 2026-10-29 entry's validity condition broke once. In a client project's pull request, stability round 1 raised a 🟡: an end-to-end payroll test passes on a used database. It proposed asserting the created row counts. The answer commit added that assertion behind a test.skip that runs when every count is zero. A broken payroll also creates zero rows, so a regression became a skip. The gate and the mutation run don't catch it, since a skipped test counts as passing; only the forge's auto-reviewer did. So a 🟡 fix that removes or loosens an assertion, changes an expected value, or skips, deletes or guards a test or assertion reruns the pass that raised it, as a 🔴 fix does. A 🟡 fix that only kills a named mutant or makes a named failing test pass doesn't, since the tests and the mutation command check it, and a skipped test kills no mutant. Every other 🟡 fix keeps the 2026-10-29 rule: the 2026-10-08 audit found that reruns of fixes to minor findings mostly re-checked wording. The rerun reviews only the answers, and the cap of two rounds still ends the pass. Valid while fixes of this kind are a small share of 🟡 fixes, so the extra round stays cheap.

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 doesn't block anything. 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 doesn't say anything 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 doesn't block anything now, so a suspension saves only the runs. Valid while such a decision names its items and the plan item that ends it.

project config: a record may name a Confluence Cloud page as confluence: and its address, the loop reads and writes it as markdown, and a write never overwrites a save made since the loop's read

2026-11-15, larv-review, on lilleman's calls of 2026-11-12. Serves goal 1.6: a client's team keeps its records in its own wiki. Valid while one record fits one page, and while each worktree opens its own copy of a record, as loop-claude's side-by-side chunks need.

  • A bench of readers picked the spelling. Three fresh readers, seated as the person who writes a client's config.toml, each picked decisions = "confluence:https://<site>/wiki/spaces/<space>/pages/<page ID>", pasted from the browser with or without the title at its end, over the bare address, a page ID beside a confluence-site key, and a table. Each named the match with jira:. Any of the five records may name a page; the goals file, the plan, the working rules and the principles may not.
  • decisions and comprehension-history may name a page only where plan names a Jira epic. rule-hook ranks a plan kept as a file before tool calls, inside its 30-second limit, and ranking reads those two records. A Confluence read and two adf-codec container runs would hold up every guarded tool call, and fail it while Confluence is down. load refuses goals in Jira beside a plan in a file for the same reason.
  • A write sends the version number it writes over, plus one, and Confluence refuses it with 409 where someone saved the page since. The store then fails, saying to ask the human, and doesn't write the page; the loop never overwrites a teammate's edit on its own (lilleman, 2026-11-12). A write handed no version replaces the page as it stands, as the record contract asks.
  • A store keeps no version: its caller hands each write the version it writes over. lilleman chose this on 2026-11-16, when 0.11.0's release review found the version kept as the store's hidden state, which made a write rest on whichever read came before it. project-record keeps the version open read in a file beside its copy, ~/.local/state/project-record/<key>/<worktree>/<record>.version, since save runs in a later process, and each save keeps the version it left for the next. Every other tool writes over the version its own read gave, so a read by another tool, such as larv-review's, never moves the version an edit in project-record rests on. The folder <worktree> is named for the worktree that ran open, and open removes the folders of worktrees git no longer lists, so a chunk's copy doesn't outlive its worktree.
  • The page holds ADF, which adf-codec converts both ways, so a teammate reads the record as Confluence renders it. Where adf-codec cannot convert the markdown, the write fails with adf-codec's error. A node markdown cannot hold reads as text: a mention as its name, a macro as _(<macro> not included)_. So the next write replaces it with that text, and a record page should hold only what markdown can.

project config: a tool that reads a file's commits says where it does not support that file, and the work goes on

2026-11-13, larv-review. Serves goal 1.6: a client's plan and records live in the config's folder, and the loop still runs there. A file the config puts outside the checkout has no commit in the project's history, so a tool that needs the file's commits cannot do its job for it. No such tool blocks the loop or a merge, and each says what it leaves undone:

  • score-outcomes and loop-claude's routing figures read what each chunk shipped from the commits of todo.md, and leave docs/comprehension-history.md and docs/reading-cost.md out of a chunk's work. They count a project only where the three are at those paths in the checkout (bin/branch_chunks/read.py, unsupported). score-outcomes exits 1 with the reason; the routing figures list the project under "Default branches unread".
  • larv-review cannot count the scoring runs a branch recorded, or find a paired ruling's base, in a comprehension history outside the checkout. Nor can it read a plan outside the checkout as the chunk found it, so it cannot tell which items the chunk shipped. In each case scoring-run-owed says so, and the merge goes on; needs-scoring-run and record-scoring say so for an item such a plan no longer holds.
  • rule-hook cannot tell whether a plan outside the checkout changed, so it checks that plan's ranking on every call.
  • A file outside the checkout is read as it stands, never as the default branch held it: release standing, chunk-preflight and loop-claude's routing read such a plan or changelog from disk.
  • chunk-preflight and loop-claude's routing learn that a release's items are all done from the plan's commits. A plan outside the checkout no longer names such a release, so the release after it reads as next, and only the last release of all gets a release review called due and is called ready to cut. Both tools say so on every run, and that the release reviews and the cuts are the human's to call (bin/release_plan/release_standing.py, UNSEEN_RELEASES).

Messages keep each file's usual name, such as todo.md, as its label, since the config keeps the names. Revisit at 0.23.0, which plans the support for score-outcomes, the routing figures, the release standing and the owed scoring run.

project config: language names the prose's language by its English name, and commit-title, pull-request-title and branch are brace templates over {id} and {summary}

2026-11-14, larv-review. Serves goal 1.6: a client's team reads its docs, Jira text, commits and pull requests in its own language and format. Valid while one language and one template per title serve a project.

  • A bench of readers picked the spelling. Three fresh readers, seated as the person who writes a client's config.toml, each picked brace templates, these four keys and the language's English name ("Swedish") over %-codes, regular expressions and language codes.
  • {id} is the ID of the chunk's first plan item, todo.md's number while the plan is todo.md, and {summary} the title a project without templates would have. A title template holds {summary} once and may hold {id}; branch holds {id} and no {summary}. A title template keeps text between {id} and {summary}, so a title splits one way, and has no space at its start or end and no control character. Any other brace is a fault project-config names: no template needs a literal brace, so there is no escape to learn.
  • A tool reads a title as its summary: by commit-title, then by pull-request-title, then whole. A tool that looks for a round title or a Drop item title looks in the summary (bin/project_config/templates.py, Titles). The pull request's template is tried because a squash merge titles the commit as the pull request. A title that fits neither is its own summary, so history from before a template was set still reads.
  • A title must fit its template only on a branch that fits branch. There rule-hook's commit-title rule refuses a commit that doesn't fit, and chunk-pr a pull request title. A chunk without a plan item, such as a release review, has no ID to fill {id}; its branch doesn't fit, and its titles are the summary alone.
  • A config with a fault stops the work. rule-hook refuses every commit while the project's config cannot be read, and the tools that read titles fail naming the fault: a title read by the wrong template would miscount rounds in silence.
  • The worktree is named after the branch, <checkout>-<branch> with each / written -, so feature/{id} gets one folder beside the checkout.
  • The language covers what the project's readers read: docs, comments, tickets, and the summary a title carries. CLAUDE.md → "Prose" lists what stays English.
  • deploy-release titles its commit Cut release <version> whatever the template, since a release has no plan item to give {id}, and the tool finds that commit again by its exact title. It reads its clone's other titles whole, as no project's config names the clone.

project config: plan may name a Jira Cloud epic as jira: and its address, the plan is its open child issues in backlog order, and an issue's number is the item's ID

2026-11-14, larv-review, on lilleman's calls of 2026-11-12 and 2026-11-14. Serves goal 1.6: a client's team keeps planning in its own Jira. Valid while a client's plan fits one epic in one Jira project.

  • One epic is one project's plan, and Jira's backlog rank orders it. The team sets the rank, so the loop's score doesn't break ties and the loop never reranks an issue once filed (lilleman, 2026-11-12). An item is an open child issue; one in a done status category is finished.
  • A bench of readers picked the spelling. Three fresh readers, seated as the person who writes a client's config.toml, each picked plan = "jira:https://<site>/browse/<key>" over the bare address, a jira:<key> beside a jira-site key, and a [plan] table. Each also picked one pair of env-file keys, ATLASSIAN_EMAIL and ATLASSIAN_API_TOKEN, for Jira and Confluence over a pair for each, since one account's token opens both.
  • An item's ID stays a whole number: the issue's number in the epic's Jira project. About 30 modules read an ID as an int, and the branch and title templates already spell a ticket's name, as ABC-{id}. So the store refuses a child issue from another Jira project, and counts a blocker only among the plan's own items (bin/plan_store/jira_epic.py).
  • The scores sit in one issue property, plan-item, which needs no Jira admin (lilleman, 2026-11-12). An issue without it reads as an item nobody scored.
  • The release is the earliest Fix Version named as a semver version, and an issue with none fails the read, naming it.
  • The loop files an item under the epic as a Task unless the config names another type, and marks it as its own (lilleman's calls of 2026-11-12). "Filed by": "loop" in the plan-item property tells such an issue from one a person filed, whose summary and description the loop never edits. Task is an issue type every Jira Software project template has, so it is the default; a project without it, such as TW, names another type in its project config's jira-finding-type. Where the project lacks the type set, the filing fails before anything is filed, naming the types the project has. The issue takes the project's Fix Version named as the release, with a leading v or without, and the store refuses an item whose release the project has no Fix Version for, before it files anything. A security finding also gets the label security, and its text never holds a secret's value. Jira takes a blocker's link only after the issue exists, so the store first checks that each blocker is an open child. A link Jira still refuses leaves the issue filed: the write counts as landed, with a note naming the link to make by hand. A failed create says the issue may exist all the same, since a lost answer doesn't tell.
  • The config states the formula and the bar, and the store ranks a new issue among the loop's own (lilleman, 2026-11-12 and 2026-11-15). A plan in Jira has no ## Scoring, so a config whose plan names an epic must set jira-score-formula and jira-score-bar. It fails to load without them, or with a formula that doesn't parse, since no setting a config needs has a default. A bench of readers picked the spelling: three fresh readers, seated as the person who writes a client's config.toml, each picked those keys over jira-score and jira-bar, score-formula and score-bar, and bare score and bar. The prefix matches the other Jira-only settings, "formula" says the value is no score, and "score-bar" says what the bar applies to. The store scores the item as rank_todo.py scores a row, with the goal weights from the goals file, the decision log and the comprehension history. It refuses an item under the bar that isn't exempt, or one whose Moves names a goal the goals file lacks, before it files anything. Then it ranks the issue just before the first issue the loop filed that ranks after it. A person's issues don't count, so the team's rank of each stays as it is. The order is todo.md's within a release: a question first, then a security finding, then the higher score, with a tie after the older issue. Questions go first because rank_todo.py ranks them ahead of security findings, since an answer may change other items (the loop's choice, 2026-11-16). Release doesn't count, since lilleman's call ranks by score among the loop's issues. A rank Jira refuses, or an issue of the loop's that no longer scores, leaves the new issue filed and last, with a note to rank it by hand.
  • The store edits and moves only an issue the loop filed, and of an issue a person filed it sets only the scores (lilleman's calls of 2026-11-12). On its own issue it sets the summary, description, scores and Fix Version in one request, so Jira takes all of an edit or none, and it keeps the label security in step with Exempt. It also sets the "is blocked by" links, in requests of their own after that one: a link per blocker added and a deletion per blocker dropped, each blocker an open child, as add checks, and none that waits for the item itself, directly or through others. A link to any other issue stays as it is, since a read doesn't show it and the team may have made it. Of a person's issue it writes only the plan-item property, and a comment: the team's screens don't show the property, so the comment tells the team why the scores changed, and the store refuses the edit without one. Its links stay the team's, which Jira shows on its board where it doesn't show a score. The comment's text comes from whoever scores, in the project's language. Where Jira takes the edit and then refuses a link or the comment, the edit counts as made, and a note says what to do by hand.
  • The loop may re-score a person's issue that already holds scores, and never moves it. lilleman's calls of 2026-11-12 cover an issue nobody scored, and say nothing of one that holds scores; larv-review chose on 2026-11-16, through todo item 382. A re-score changes only the loop's own reading of the issue, and not what the person wrote, so it is allowed, with a comment as the first scores need. L, E, I and S are set together, so no issue is left partly scored. The Fix Version says when the team ships the issue, and a release is its team's, so the store refuses the move and CLAUDE.md has the worker ask the human to move the issue.
  • todo-item edit --comment carries the comment, and a plan in a file takes the flag and keeps no comment, so one command works in every project, as goal 1.3 asks. A bench of readers picked the spelling: three fresh readers, seated as the consultant who runs the loop in a client's project, each picked --comment over --reason, --why and --because. Only it says the text is posted where the team reads it, and --reason read as --exempt's reason.
  • The store finishes an item with the transition that the config's jira-finish-transition names, which must lead to the status jira-finish-status names, since each Jira workflow differs (lilleman's call, 2026-11-12); any open child of the epic may move. It refuses a status outside Jira's done status category: the read counts an issue as finished only in that category, so the item would stay in the plan. Where the issue's present status has no direct transition to the status jira-finish-status names, todo-item finish fails and a person moves the issue in Jira: the store never walks an issue through other statuses to reach it. lilleman answered on 2026-11-15: "If it is possible to move it to done without a transisiont, that should happen. If not, fail." The implementer read "without a transition" as "without a transition in between". rank_todo.py refuses to rank a plan in Jira, and its --check passes, since Jira's backlog ranks it; rule-hook's rank check skips it. Each read first asks Jira for the epic itself, since a search under an epic the account cannot see answers no issues, as a finished plan does.

project config: the loop shows a Jira description and a Confluence page as adf-codec's portable markdown, and a save whose text is the text a read showed leaves the document as Jira or Confluence holds it

2026-11-17, claude, through item 391. Serves goal 1.6: a team's Jira and Confluence keep each block's localId and the empty paragraphs Jira uses for spacing, and agents, the judge and people still read the text easily, which keeps goal 1.4's reading cost down. adf-codec converts markdown and ADF by two pairs of calls, as bin/adf_codec/convert.py says. The lossless pair keeps the localIds and spacing paragraphs, but wraps every block in two !adf: marker lines: a five-line detail became 17 lines in a trial (larvit/adf-codec#185). The portable pair drops both. So the loop reads by the portable pair, and leaves a document alone where a save's text is the text a read showed. JiraPlan.shows compares a new detail with the description converted again. ConfluencePage keeps the digest of the text it read in the version a write names, and checks that the page still holds that version. Valid while the lossless markdown wraps every block in marker lines. A save that changes one line still rewrites the whole document by the portable pair, and so drops every localId and spacing paragraph, until todo.md item 395 keeps each block the save didn't change.

2026-11-18, claude, item 402. Serves goal 1.6. A Jira epic's description is written by the portable pair too, though the item named the lossless pair: that pair shows the loop marker lines around its blocks, which this decision rejects for the reading cost. EpicDescription.write sends nothing for the text a read showed, refuses a write over a description whose document differs from the one read, and refuses a change to ## Goals or ## Audience unless the human approved that section. Until item 395, a save that changes one section also reduces a mention or macro in Goals or Audience to its text, which project-config's help and the README tell the reader.

project config: tooling-on-host = true lets a project with no container setup run its language runtime, package manager, tests and task runner on the host

2026-11-12, lilleman, through todo item 358. Serves goal 1.6: a legacy product may have no container setup, and the loop works in it without its owners adding one. CLAUDE.md's container rule and the stability reviewer follow the setting. rule-hook checks only how a container starts, its memory limits and its image's pin, never where a runtime runs, so it needs no change. A decision may still put one tool on the host where the project has containers, as this repo's bin/ decision does. Readers seated as the person who writes the config picked the key, 2 of 3. Valid while the loop runs on the machine that holds the checkout.

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 the review 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/chunk_driver/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 reviewer's definition changes, and for a project only while its rung is Opus 5.5 at medium, the rung the trials ran on: 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 doesn't refuse anything, 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 change only what a user wouldn't 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 no score blocks a 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 didn't change anything (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/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.

2026-11-11, lilleman. Serves goal 1.1. Item 296 made chunk-pr merge refuse while a scoring run the plan calls is unrecorded on the branch, so a missing run can block a merge. No score or ruling does, and the titles say so: "no score blocks a merge".

2026-11-15, lilleman, on the worker's proposal in item 374, replacing the call of 2026-11-13. The call asked that a ruling never charge one chunk with another's change, by reading against the new base after a rebase. Only the release review runs a paired ruling, and it measures the whole release, so its base stays the last measured commit. What another chunk's merge changes is the head: a ruling recorded before the merge came in read a head that never merges. So chunk-pr merge stops where the default branch has moved since the branch last recorded a paired ruling, and the worker runs the ruling again at the new head.

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 project's rung changes from the one this trial replayed it on: 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: the worker mutation-tests a chunk's changed lines before each stability round, 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.

The worker runs the project's mutation command, bin/mutate-changes where the README documents none, kills the survivors that change behaviour, runs it again, and hands stability-reviewer what is left to judge. Before the move, stability-reviewer ran the mutation tools by hand in 133 of its 144 reports, and 223 of its 428 round-1 findings from 2026-11-02 to 2026-11-10 (52%) were test gaps. One command finds the survivors the same way every time, and the reviewer spends its round on what remains. The worker runs it before each stability round, not once: each fix moves the head, and a reviewer handed a run on an older commit runs it again inside review.

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.

review: the worker runs the project's tests and static analysis and checks the docs for each changed name before each stability round, and hands stability-reviewer the commit

2026-11-11, lilleman through todo item 270, implemented by claude. Serves goal 1.4: a check the worker can run is run once before review, not in each reviewer's round. A subagent counted by keyword, from their headings, the new 🔴 and 🟡 findings in the stability and product-owner round-2 reports modified in the 60 days before 2026-11-11: 73 and 18, from 148 and 75 reports, so the shares are rough. About 29% were an untested branch or surviving mutant and 9% a weak assertion; bin/mutate-changes finds both before review since item 293. About 21% were a README, CHANGELOG, help line or comment that the change had made false, and 1% a lint or type error. The rest, edge-case logic (18%), false comments the change didn't cause and wording, need judgement, so they stay with the reviewer.

Stability reviewers ran the whole suite in 52 of this repo's 63 reports from the last 60 days, and the worker's run on the same commit gives the same result. So the worker sweeps for each name, flag, path and number the change touches, runs the suite and analysis as the project's README documents them, and hands the reviewer the passing commit; the reviewer runs them only for another commit. The sweep is the worker's reading, not a program, since a stale claim has no fixed spelling.

Valid while the worker's run on a commit finds what a reviewer's run on it would, and while stale-doc findings in round 2 fall below the 21% measured.

review: agents of one type launch in one message, not one a message before the others

2026-11-11, claude, in the stability review of the chunk that took the plan item proposing it; lilleman dropped that item the same day. Serves goals 1.4 and 1.5. Anthropic's prompt caching docs say a cache entry is readable only once the first response that wrote it has started, and the item measured 748 comprehension seats, 153 security passes and 130 general-purpose subagents that each wrote their own prefix, $99 from 2026-09-30 to 2026-11-11. Launching one agent of a type before the rest, to read its cache, doesn't pay: a foreground Agent call returns only when its agent has finished, and larv-review runs reviewers in the foreground, so each later launch group would wait one agent's whole run, a seat's median 1.6 minutes, to save a prefix of about 14k tokens. The stability reviewer also found, in the transcripts of 73 seats started within 90 seconds of an earlier seat, that each already read the shared prefix.

Valid while a foreground Agent call returns only when its agent has finished.

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 whose replay of its rounds finds a share of their 🔴 and 🟡 findings no more than a margin below the project's rung's own replay… 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. loop-claude scores each item the worker names on its Chunk items: line by todo.md (routing: loop-claude reads the items a chunk takes), routes on their highest E + I from the next cycle, 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 whose replay of its rounds finds a share of their 🔴 and 🟡 findings no more than a margin below the project's rung's own replay, and misses no 🔴 that both of the project's rung's replays found; 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. On 2026-11-11 lilleman approved the bar below, as somewhat risky, with a close evaluation a release later: todo.md item 321. Serves goal 1.4 without giving up goal 1.1: a cheaper reviewer saves money only where it finds nearly as much.

bin/review-replay <pass> <model> replays a pass's archived rounds on the code each reviewed, twice on the project's rung. A rung below qualifies where its replay finds at least the mean share of the archived findings that those two replays found, less 10 percentage points, over at least 8 rounds, and misses no 🔴 that both found. The tool tries the project's model at each lower effort first, since the ladder leaves those out, then each ladder rung below, highest first. It stops at the first rung that doesn't qualify.

The bar used to be every finding the project's rung found again. But the project's rung itself found only 69 to 73% of its own findings again, so a reviewer exactly as good failed that bar, and so would the project's rung on a second replay. The margin of 10 points allows for that spread: in the latest run below, the project's rung's two replays found 41 and 43 of the same 55 findings, 4 points apart. A missed 🔴 still fails a rung, since a 🔴 that both replays found is no matter of chance.

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 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. For a rung off the ladder, such as the project's model at a lower effort, that chunk also sets the effort key in the reviewer's frontmatter under agents/, which sets the effort per reviewer.

The runs, each on the latest 10 rounds of Opus 5.5 projects that hold a 🔴 or 🟡:

  • 2026-10-15, stability, under the old bar: 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, under the old bar: 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, under the old bar, 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.
  • 2026-11-12, prose, under the new bar: 8 rounds, 55 findings, after 2 more rounds failed on the project's rung. The project's rung found 41 and then 43 of them, 76%, so the bar was 66%. Opus 5.5 at low effort found 27, 49%, and missed no 🔴 that both replays found. No rung qualifies, and Sonnet 5.5 at high was not tried.

The prose pass went first under the new bar: 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, so it is unlikely to reach the new bar either; and Opus 5.5 at low, the likeliest rung, fell 17 points short on the pass whose misses cost least. The architecture, principles, overrides and product-owner passes are not replayed yet: todo.md item 196 keeps their replays in the plan.

Valid until the rungs below the project's rung change, 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/agent_cycle/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 runs without the advisor tool

2026-11-12, lilleman, settled by the bench below. Serves goal 1.4: a switch that raises cost without raising quality is no saving. Valid while the ladder's L 1 and L 2 workers run on Sonnet 5.5 and the advisor would be Opus 5.5.

claude -p calls the advisor. A probe with --advisor claude-opus-5-5 made one call: it read the whole conversation, 20,187 uncached input tokens, and cost $0.093 beside the worker's $0.036. workflow-bench/advisor_bench.py ran six archived chunks of this repo (todo items 290, 251 and 218 at L 1, and 289, 229 and 214 at L 2) once on each of three arms: Sonnet 5.5 at high with the advisor, Sonnet 5.5 at high alone, and Opus 5.5 at medium. A judge on Opus 5.5 at medium, blind to the arm, ruled each run's change against the change that shipped, with the tests of the packages either change touches.

Arm Passes Mean cost Mean seconds Runs with an advisor call
Sonnet 5.5 with the advisor 6 of 6 $0.37 286 1 of 6
Sonnet 5.5 alone 6 of 6 $0.27 151 0 of 6
Opus 5.5 at medium 6 of 6 $0.46 197 0 of 6

Every arm passed every case, so the bench found no quality gap for an advisor to close, and Sonnet alone cost 41% less than Opus at medium. The advisor's one call, in item 214's run, cost $0.72 of that run's $1.24, against $0.41 for Sonnet alone. Anthropic's reported gain (https://claude.com/blog/the-advisor-strategy) came on SWE-bench Multilingual, a harder set than L 1 and L 2 chunks. The bench ran each arm once per case, and its judge is of the worker's own model family, so it shows a direction only. It tested L 1 and L 2 items alone. Workers on items above L 2 run without the advisor too, since nothing shows it pays there, until a bench of such items does.

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 it names on its Chunk items: line 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.

A stepped worker resumes its session, also when the step changes its model. A plan item, since dropped, proposed a fresh session with a brief of the chunk in its place, after arXiv 2608.24358 measured a fresh strong model ahead of one handed the weak model's transcript. workflow-bench/handoff_bench.py benched it on 2026-11-17, on L 3 items this repo shipped. Sonnet 5.5 at high effort started each of six and was stopped at $0.36. It stopped itself on item 163 as it reached the budget, which the bench reads as a finished run, so five items went on, each stopped after 9 to 13 turns. Opus 5.5 at medium effort then finished each of the five three ways: resuming the session, resuming it after /compact, and in a fresh session with the item's text and a brief, which says that the unfinished change lies uncommitted in the clone. A judge that did not know the arm graded each change. It saw the item, the change that shipped for it, and the result of the tests run on the worker's tree.

arm runs pass partial fail mean cost $ mean seconds
resume 5 2 3 0 0.68 235
compact 5 1 3 1 0.56 198
brief 5 1 4 0 0.78 310

Resume's verdict matched or beat the brief's on every item, and the brief cost less on two of the five. So the bench gives no reason to pay for a fresh session. Its price is more than a change to how the worker starts. The archive files a chunk under its session's first line. For a chunk that spans two sessions, the archive, and each figure read from it, would have to join them. The bench is small: each arm ran once per item, the judge is Opus 5.5 too, and no first run was longer than 13 turns. Run it again before changing this, with longer first runs, since the paper's gap may open only on a long transcript.

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: loop-claude reads the items a chunk takes from the worker's latest Chunk items: line and scores them by todo.md as the default branch held it when the cycle started; the judge reports the escalation and whether a release is ready to cut

2026-11-11, claude. Serves goal 1.4 and code health. The judge's reply held three facts beside its verdict: the items the worker took into the chunk, with their highest L and E + I; whether a release was ready to cut; and any escalation the worker asked for. Routing lifts the worker's and the reviewers' rungs by the items' levels. Code now reads the items: each chunk's first prompt, and each prompt resuming it, asks the worker for a line opening Chunk items:, bin/loop_claude/chunk/chunk_items.py reads the latest such line in the worker's own text, and plan.todo_table scores the items. So the judge's reply is smaller, and every L and E + I that routing reads comes from todo.md, through one module.

The judge field trials (judge-field-trials/) read each fact by code over the 709 archived cases. Code was wrong in each of the 39 cases where it and the judge disagreed on an escalation, and read a release ready to cut in 3 of the 31 interrupts that asked about a cut, so the judge keeps both. Workers stated an item with its L and E + I in 413 cases, but also stated items they filed, finished or only mentioned, so the worker writes the items on a line that holds only them, which code reads. Three fresh readers picked its label Chunk items:, 3 to 0, because it says the items are the chunk's.

An item the chunk re-scores on its branch routes on its planned levels until the branch merges; where the new L picks a higher rung, the worker cites escalation trigger 1, which the judge finds. Where the worker writes no line, loop-claude counts no item as taken in, so the route holds. Rerun judge-field-trials/release_ready.py when the way chunk-preflight detects a release review changes.

Valid while workers write the line when asked, and while todo.md on the default branch scores each item a chunk takes.

routing: on a model judge-replay covered, the judge runs on its model's highest rung

2026-10-15, lilleman's plan, settled by the replays below. Serves goals 1.1, 1.2 and 1.4, under the ladder and steps of routing: one ladder.

On a model listed in JUDGE_REPLAYED in bin/agent_cycle/routing.py, the judge runs on its model's highest rung, whatever the chunk's items score: on an Opus 5.5 project, Opus 5.5 at xhigh. It keeps its rung when the worker steps up. 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). From 2026-10-16 to 2026-11-12 the judge ran at medium below an E + I of 5 and at xhigh from 5, climbing with the highest E + I among the routed item and those the worker took in, as a review does: lilleman's call, since the judge checks the worker's decisions as the reviewers check its code, and a decision it lets through reaches lilleman, as a defect that review lets through reaches the users (goal 1.2).

On 2026-11-12, bin/judge-replay claude-opus-5-5 replayed 60 verdicts, 15 of each kind, and also tried each rung above the project's that a review climbs to by E + I. The reference judge reproduced 46. On those 46, Fable 5.2 missed 2 interrupts and 6 other verdicts at low, 1 interrupt and 4 others at medium, and 1 interrupt and 2 others at high. Every Fable 5.2 rung it tried misses an interrupt, so the judge keeps to its own model's rungs (goal 1.2). That rule also keeps it off Fable 5.2 at max, which no replay tried. Opus 5.5 at medium missed no interrupt, but returned another kind on 4 quoted answers, 3 of them as finished.

2026-11-12, claude, raising the judge's floor to xhigh, settled by the reruns below. Serves goal 1.1, at a cost to goal 1.4. Today's records still hold each of the 4 archived quotes, so no case drops out. For fejkdata the quote, Split a milestone into items in todo.md before starting it, doesn't plainly answer whether a split changes what release 0.5.0 holds, which is lilleman's choice. That case stays, since xhigh quotes it in 3 of 3 replays. Each case was replayed on today's records and the archived transcript copy. Opus 5.5 at medium returned the quoted answer 7 times in 20: adf-codec 4 of 5 (the fifth as finished), claude-config 3 of 5 (2 finished), plainpages 0 of 5 (5 finished) and fejkdata 0 of 5 (5 unfinished). At xhigh it returned it 9 times in 12: adf-codec 1 of 3 (2 interrupts), claude-config 3 of 3, plainpages 2 of 3 (1 finished) and fejkdata 3 of 3. So the misses persist at medium, and xhigh returns the quote more than twice as often. A quoted answer returned as finished closes a chunk whose worker was asking a question, a quality miss (goal 1.1). xhigh costs more per judge run (goal 1.4); the Judge cost: lines of three of the four cases, run at medium, read 0.57 to 0.79. xhigh is not free of misses: it returned a quoted answer as finished once, and as an interrupt twice, which only asks lilleman more.

Valid while the archived verdicts show what a judge should return, and until the rungs the replays tested change: the project's rung, those below it and each rung above it that a review climbs to. Replay then.

routing: one ladder of (model, effort) rungs, ordered by the Artificial Analysis Intelligence Index, shipped as bin/model_routing/routing-ladder.json, which a project may replace with a file of that name in its config's folder; 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 shipped ladder and one set of steps for every project, read by loop-claude and by the worker through bin/subagent-rung; a project runs on other rungs only through a ladder file of its own (2026-11-15 note). The judge's rung is set by routing: on a model judge-replay covered. bin/model_routing/routing-ladder.json holds the rungs and ladder.py beside it the steps.

The rungs, least competent first: Sonnet 5.5 at high; Opus 5.5 at medium; Fable 5.2 at low and medium; Opus 5.5 at xhigh; Fable 5.2 at high and max. The 2026-11-11 note below put them so. Before it they were Sonnet 5.5 at high; Opus 5.5 at medium, high, xhigh and max; Fable 5.1 at max, after the 2026-10-29 note 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), 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). The first cut, from the index read 2026-10-14, dropped 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 fell among the dropped rungs. lilleman put Fable 5.1 at max back on top: the index scored 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. Fable 5.2 at max tops the index outright, so that exception has ended.

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 doesn't route anything: 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 one up, 4 two 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 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, and raised L 3 and L 4 on 2026-11-14, as below. 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.

2026-11-11, lilleman approved the rungs for Fable 5.2 from the index read that day. Its score and cost per task, for each effort from low to max: Sonnet 5.5 26 $0.51, 31 $0.78, 42 $1.64, 50 $4.09, 55 $10.02; Opus 5.5 35 $0.98, 48 $2.45, 52 $3.46, 57 $6.05, 59 $10.04; Fable 5.2 54 $3.10, 56 $3.80, 62 $9.08, 62 $14.83, 65 $26.54. The cut drops Opus 5.5 at high, since Fable 5.2 at low scores more for less; Opus 5.5 at max, since Fable 5.2 at high scores more for less; and Fable 5.2 at xhigh, which ties Fable 5.2 at high at a higher cost. Sonnet 5.5 at high stays the bottom rung, as the 2026-10-29 note chose. With Haiku 5.5 off, the cut alone would also keep Sonnet 5.5 at low and medium and Opus 5.5 at low, below it. On an Opus 5.5 project, an L 4 worker, an E + I 5 review and a worker's first escalation now run on Fable 5.2 at low, where they ran on Opus 5.5 at high; E + I 8 runs on Fable 5.2 at high, where it ran on Fable 5.1 at max. Three steps land on a rung the index scores lower than before: E + I 6 on Fable 5.2 at medium, 56 against Opus 5.5 at xhigh's 57; E + I 7 on Opus 5.5 at xhigh, 57 against Opus 5.5 at max's 59; and an L 3 worker's escalation stops, without lilleman's yes, at Fable 5.2 at medium, where it stopped at Opus 5.5 at xhigh. On a Sonnet 5.5 project, E + I 6 runs on Fable 5.2 at low, 54 against Opus 5.5 at high's 52; E + I 7 on Fable 5.2 at medium, 56 against Opus 5.5 at xhigh's 57; and E + I 8 on Opus 5.5 at xhigh, 57 against Opus 5.5 at max's 59. Fable 5.2 at max, on top, is reached only one rung up from Fable 5.2 at high, as by a reviewer's rerun. A Fable 5.2 project's rung is Fable 5.2 at low, so its L 1 and L 2 workers run on Opus 5.5 at medium.

2026-11-14, lilleman ruled that L 3 is to step one rung up and L 4 two up, in every project and for delegated subagents. The steps take effect in 0.12.0, as lilleman chose on 2026-11-16. On an Opus 5.5 project, an L 3 worker or subagent runs on Fable 5.2 at low, and an escalation stops without lilleman's yes at Opus 5.5 at xhigh. An L 4 one runs on Fable 5.2 at medium, and stops at Fable 5.2 at high. The ruling settles the two calls that routing-calls-raised.md stamps 2026-11-14T13:57:34Z, raised on the routing figures measured at 2026-11-14T00:59:50Z. The figures came from 276 chunks finished since the 2026-10-29 reset. Chunks started on Opus 5.5 at medium, 79 of them, took a mean 0.8 review rounds past each pass's first, 0.3 unfinished verdicts and 0.2 later fixes. Chunks started on Fable 5.2 at low, 5 of them, took 0.4, 0.0 and 0.0. Under the old steps, only L 4 items started on Fable 5.2 at low on an Opus 5.5 project, so it did better on harder items. Two things weaken the evidence: 5 chunks is the fewest a call allows, and the Opus 5.5 figures include chunks from before Fable 5.2 joined the ladder. On the 2026-11-11 index, an L 3 task's cost rises about 1.3 times, from $2.45 to $3.10, for fewer rounds and fewer unfinished verdicts (goal 1.4). The chunks started on Sonnet 5.5 at high, 164 of the 276, don't move.

2026-11-15, lilleman asked for the ladder as a file that a project can replace, on a day when an outage left only Fable 5.2 answering: the rungs were a constant in bin/model_routing/ladder.py, so no project could leave Sonnet 5.5 and Opus 5.5 without a release. The shipped ladder is bin/model_routing/routing-ladder.json, a JSON list of rungs, least competent first. A project that keeps a routing-ladder.json in its config's folder, ~/.claude-projects/<key>/, runs on that ladder whole, and the steps count on it as on the shipped one. Every project still runs the same routing rules and steps, so the workflow of goal 1.3 holds; the ladder joins what a project's config folder may supply, which that goal's list does not name yet. lilleman chose a file per project over one per machine, so a single project can differ. A ladder holds one model of each family, since the Agent tool launches a subagent or a review by its family's name. The project's file is lilleman's to write, as any change to the ladder is, and the loop never commits it. loop-claude reads the project's ladder as each cycle starts; subagent-rung and rule-hook's reviewer-rung read it each time they run, from the checkout they run in. A ladder file that holds a fault stops each of them, since work routed on the shipped ladder in its place could run on a model the project cannot reach. The routing figures, judge-replay and review-replay span every project, so they read the shipped ladder: a rung only a project's own ladder holds is left out of the figures' calls, and no replay qualifies it. lilleman shipped the change as 0.10.1, a patch cut from the tag v0.10.0, on the day of the outage: it adds a file format and an exit 1 to subagent-rung, which the technical principles' semantic versioning gives a minor, and lilleman asked for the patch "even if that breaks semver", so that the release in use could run again without taking the unreleased work on main.

2026-11-18, lilleman kept the ladder and the steps, settling the call raised on the routing figures measured at 2026-11-18T15:04:48Z: chunks routed onto Sonnet 5.5 at high took more review rounds past each pass's first than chunks routed onto Opus 5.5 at medium. The figures came from 19 chunks finished since the 2026-11-17 reset. The 13 chunks started on Sonnet 5.5 at high took a mean 0.5 rounds and 0.0 unfinished verdicts; the 6 started on Opus 5.5 at medium took 0.5 and 0.2. Neither rung had later fixes, among the 11 and the 4 chunks whose later fixes are known. Both means show 0.5, so the gap is under 0.1 rounds. Sonnet 5.5 did better on unfinished verdicts, and it is the cheaper rung (goal 1.4). loop-claude lists the call in routing-calls-raised.md only once the session that put it to lilleman ends, stamped with the time the figures were measured, so this note cites that time.

Valid while the index ranks these models, and while no newer model joins the catalog.

routing: the offline classifier may decide finished, since lilleman ruled a miss rate of about 1 in 100 decided close enough to none; the judge's model keeps every other verdict kind

2026-11-18, claude. Serves goals 1.2 and 1.4, and applies project principle 1: a cost cut waits for a measurement that shows quality holds.

bin/judge-replay claude-opus-5-5 --offline replays all archived verdicts of the Opus 5.5 projects through three deciders. Each reads only the worker's final message, doesn't send anything to an outside service, and decides a kind or leaves the verdict to the judge's model. A missed interrupt is an archived interrupt decided as another kind, which lets the worker settle a decision that is lilleman's. Deciding interrupt can't miss one: a wrong interrupt only asks lilleman more. On 2026-11-17 the archive held 1,104 verdicts (660 finished, 333 interrupt, 33 quoted answer, 78 unfinished); on 2026-11-18 it held 1,116 (668, 336, 34, 78).

  • A "?" rule (interrupt where the message holds a "?", finished where it holds none) decided every one of the 1,104 and missed 197 interrupts.
  • A decision table, the rows of DECISION_TABLE in bin/judge_replay/offline.py. Its rows were read from this archive's interrupts, so its run isn't a held-out test. It decided 974 of the 1,104 and missed 55. Most of its misses are a worker reporting a merged chunk while a release is ready to cut, which depends on the plan; the rest ask for an answer in words no row names.
  • A classifier, a logistic regression over the message's words, trained on the archive. It decides finished only where its chance of an interrupt is below that of every interrupt among its training folds when held out, and interrupt only where it is above that of every other kind. It averages five regressions that differ only in the order they shuffle the samples, since a single shuffle moved its missed interrupts between 0 and 2 on the same archive. Its bar is no missed interrupt on both tests: held-out folds, each tested by a model trained on the other folds, and the latest fifth of the verdicts, learning from the rest.
    • On the 1,104 verdicts, held-out folds: 103 decided, none missed. Latest fifth: 29 decided, all as finished, and 1 interrupt missed. That fails the bar, and shuffles 5 to 9 and 10 to 14 failed it alike.
    • On the 1,116 verdicts, held-out folds: 95 decided (84 finished, 11 interrupt), none missed. Latest fifth: 20 decided, all as finished, none missed. That meets the bar for finished.

The classifier decides about 1 in 12 verdicts, and about 1 in 100 of what it decides were an interrupt on the 1,104. A latest fifth that starts a few verdicts later no longer holds the one it missed, so the bar flips with the archive's size and doesn't separate a classifier that never misses from one that rarely does. On 2026-11-18 lilleman ruled, at loop-claude's terminal, that a miss rate of about 1 in 100 decided is close enough to none. So the classifier may decide finished and skip the judge's call; the plan holds that change as an item. The judge's model keeps every verdict the classifier leaves, the escalation it quotes and whether a release is ready to cut, since the replay didn't test the classifier on those.

Valid while the archived verdicts hold interrupts that read like a finished chunk. Replay with judge-replay <model> --offline when the archive has doubled, or when a decider reads more than the final message.

routing: the worker changes rung only as a chunk starts, after every second unfinished verdict, when it names a chunk item that picks a higher rung, or when it cites an escalation trigger the judge finds

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 worker names an item on its Chunk items: line whose L picks a higher rung (routing: loop-claude reads the items a chunk takes), 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 cycle in which the worker names it ends.

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. 2026-11-11, lilleman: the hook also checks, at a git commit, each file the commit would commit against the rules that name a file, since a file a Bash command writes reaches no write check; the feedback comes at the commit, not at the write.

agents/: a reviewer starts without CLAUDE.md only where a replay of its pass missed no more findings than the most an unchanged replay missed

2026-11-12, lilleman through todo item 315, implemented by claude. Serves goal 1.4, and applies project principle 1. About 77% of CLAUDE.md is the worker's, and each reviewer loaded it whole. omitClaudeMd: true in an agent's frontmatter starts it without the user, project and local instruction files. settings.json → hooks.SubagentStart runs larv-review reviewer-context, which hands such a reviewer the three sections of ~/.claude/CLAUDE.md it needs: "Shared goal", which the agents cite, "Prose" and "Vocabulary". larv-review reviewer-header ends its header with a line naming the file that holds the project principles and decision titles, which the reviewer reads first.

Three choices in it:

  • The sections come from a hook, not from the six agent bodies, so CLAUDE.md stays their one home.
  • The header names the principles file and doesn't quote it, since the worker types the header into each reviewer's prompt.
  • The frontmatter is the one switch. The hook and the header read it, so an agent that keeps CLAUDE.md is handed neither the sections nor the line.

The gate: review-replay <pass> <model> --omit-claude-md replays 10 archived rounds three times as archived and once without the instruction files. An unchanged reviewer finds only about 70% of its own findings again, at the median of the first table's replays, so each unchanged replay is a control: count the findings it missed that both of the other two found. The replay without the instruction files is held to the findings both of the first two replays found. A pass's reviewer keeps omitClaudeMd only where that replay missed no more of them than the highest of the three control counts. Item 315 first held the replay to no miss at all; the first table below shows four passes failing that, and the second shows unchanged replays missing as many. A round that a replay fails on is left out of the comparison. Claude Code 2.1.322 ignores omitClaudeMd in a main session and fires no SubagentStart hook there, and a replay runs the reviewer as one. So the replay sets CLAUDE_CODE_DISABLE_CLAUDE_MDS and puts the hook's context and the header's line in the prompt itself.

On 2026-11-12, on claude-opus-5-5 at medium effort, first gate (two unchanged replays, no control):

Pass 🔴 and 🟡 archived Found with CLAUDE.md, twice Both times Found without Missed of those found both times
architecture 54 32, 33 27 30 4
overrides no archived round
principles 30 2, 9 2 3 0
product-owner 23 7, 4 4 8 1
prose 68 34, 36 24 39 1
stability 29 16, 13 11 18 1

Only principles-auditor met the first gate. Its evidence is thin: two rounds of each replay failed, and two findings were found both times. Without CLAUDE.md each replayed reviewer found more findings than it found both times with it, and three of the five found more than in either replay with it. So the misses may be the reviewer's own noise, which the second gate measures.

On 2026-11-12, second gate, with the control (three unchanged replays, then one without). Rounds a replay failed on are left out, so the counts differ from the first table's:

Pass Rounds kept of 10 🔴 and 🟡 archived Found with CLAUDE.md, three replays Missed by each, of what the other two found Found without Missed without, of what the first two found Result
architecture 9 46 37, 29, 36 2, 8, 1 32 3 passes
overrides no archived round
principles 8 19 4, 4, 2 1, 0, 1 4 0 passes
product-owner 8 21 7, 6, 11 1, 2, 0 7 1 passes
prose 9 54 39, 38, 41 4, 4, 0 40 3 passes
stability 6 16 6, 10, 8 3, 0, 2 6 2 passes

Every replayed pass passes the second gate. The unchanged replays alone missed up to 8 findings the other two found, so the first gate's one miss in stability, prose and product-owner is no more than an unchanged reviewer misses. The bar is the highest of the three controls. The third replay alone, which is held to the same findings as the replay without CLAUDE.md, missed 1 (architecture), 1 (principles), 0 (product-owner), 0 (prose) and 2 (stability); against it alone, architecture (3), product-owner (1) and prose (3) would fail.

2026-11-12, lilleman: every pass the second gate passed starts without CLAUDE.md, so principles-auditor, stability-reviewer, prose-reviewer, product-owner-reviewer and systems-architect have omitClaudeMd. override-reviewer keeps CLAUDE.md: no archived round of its pass exists to replay. Rerun the gate for a pass whose reviewer starts to miss findings; each pass rests on 6 to 9 rounds and one run.

Valid while Claude Code honours omitClaudeMd for a subagent and passes agent_type to a SubagentStart hook.

agents/: a comprehension seat runs as the comprehension-seat agent, which starts without CLAUDE.md, where its scores on one head held within the spread two runs of the older seats show

2026-11-17, lilleman through todo item 316 (approved 2026-11-11), implemented by claude. Serves goal 1.4, and applies project principle 1. Seats ran as general-purpose subagents, which start with the skill and agent listings, about 7,500 tokens, and CLAUDE.md: about 1.3% of spend over the archive measured from 2026-09-30 to 2026-11-12. agents/comprehension-seat.md has Read, Grep, Glob and Bash and omitClaudeMd: true. A seat reads the project as a newcomer does, and larv-review prepare-scoring still writes its prompt from seat-prompts.md; the prompt's paragraph listing the files the harness pre-loads is gone, with the --preloaded flag that filled it, since the agent pre-loads none. rule-hook holds a seat to the project's rung by its agent type, and still by the opening sentence of its prompt, so a seat launched as another agent is held too.

The measurement, on commit 55235a0 of PR #560, whose two recorded runs of the older seats gave means of Navigation 7.13 and 7.38, Locality 6.13 and 6.13, Shape 6.50 and 6.50, Self-sufficiency 6.13 and 6.50, and overall 6.50 and 6.50. The four seats ran headless on Opus at medium effort, with CLAUDE_CODE_DISABLE_CLAUDE_MDS=1, the way review-replay --omit-claude-md starts a reviewer without the instruction files; the agent itself could not launch in the session that built it. Two runs without CLAUDE.md gave means of Navigation 7.00 and 7.00, Locality 5.75 and 5.88, Shape 6.00 and 6.13, Self-sufficiency 5.88 and 6.00, and overall 6.13 and 6.25: within 0.13 of each other on every dimension, inside the spread of the recorded pairs, at most 0.5 on a dimension and 0.25 overall. A control run with CLAUDE.md loaded gave 6.75, 5.63, 6.13, 5.75 and 6.00, so leaving CLAUDE.md out moved no mean by more than 0.25, and left none of either run more than 0.13 below the control's. All three headless runs read about 0.4 below the recorded pair, so the first scoring run with the agent may read lower than the history before it; read that as the method's offset, not a change in the project, and rerun this check if a later run reads lower still.

Valid while Claude Code honours omitClaudeMd for a subagent.

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. 2026-11-12, todo item 315: a reviewer whose pass met a replay gate starts without CLAUDE.md and is handed three of its sections, per the decision agents/: a reviewer starts without CLAUDE.md….

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 doesn't have anything 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: an item of the next release predicts the files and parts it will touch under Touches: in its detail; chunk-preflight takes, in the plan's order, the items that overlap none taken before them as the chunks that may run at once, and the optional touch-predictions record keeps each chunk's prediction beside what it touched

2026-11-15, lilleman's call of 2026-11-13 in item 373, which split item 361. Serves goal 1.5, held to goal 1.4: several chunks of one project run at once only where they are unlikely to touch the same lines, since a conflict costs a rebase, a gate rerun and often a review round. A session on the project's rung or above writes each prediction, as rules/todo-items.md says, and bin/plan/touches.py reads it. The choices the call left open:

  • The spelling. A Touches: line, then one bullet per file: the path in backticks, then its parts, each a name in backticks or lines <first>-<last>, with (small) after a part the item changes only a little; a path or a name that holds a backtick takes a longer run of backticks with a space inside each end, as a Markdown code span does. A path alone is the whole file. Three readers seated as the README's audience picked the bulleted list over one line and over a table, since backticks hold a heading's commas, colons and parentheses. Two of the three put (small) after the part and outside the backticks, and two left line ranges unquoted. Each picked a different config key: touch-predictions was one reader's first choice and the second choice of the other two.
  • A part's boundaries. Python's ast module names the innermost function or class, a top-level assignment by the name it sets, and (module) for the rest. A Markdown file's parts are its headings outside fenced code. Any other file, and Python that doesn't parse, falls back to line ranges. A table row is no part of its own: the item named one, but the tables chunks collide on are the plan's and the changelog's, which don't count.
  • What doesn't count. The plan and every record the config names, the changelog among them, since every chunk writes them: chunk-pr merge --finish writes the plan and the changelog at merge time, and the other records are appended to. touch-predictions record leaves them out of what a chunk touched, and the rule keeps them out of predictions.
  • The pick. chunk-preflight takes the items of the next release that don't wait, in the plan's order, each where it overlaps neither the next item nor an item taken before it. The call asked for the set that keeps the most chunks running. The plan's order comes first all the same: the largest set could start a low-ranked item in place of one ranked above it, and with more ready items than the parallel limit, either set fills the limit. loop-claude starts as many of the picked items as parallel-chunks allows.
  • An overlap that is taken. Two items may share a part where either marks it (small). The call takes an overlap only for a small change to the same part, and a few lines re-apply onto whatever the other chunk did to it.
  • Which items share a chunk stays the worker's choice, by the review passes they fire, so the pick names items, and an item the next chunk takes starts no chunk of its own.
  • The record is optional. No path setting has a default, and a mandatory one would stop every project until its owner edits the config (goal 1.6). A project that leaves touch-predictions out is still picked for, and keeps no record. The worker runs touch-predictions record before it removes the chunk's items (skills/larv-review/SKILL.md §5), since the prediction leaves the plan with the item, and a plan in Jira keeps no history to read it back from.

Valid while loop-claude starts a project's chunks side by side by this pick (bin/loop_claude/loop/chunk_windows.py may_start), which also checks each new chunk against the running chunks' items. Once the record holds enough chunks to show how often the predictions miss, an item, not filed yet, revisits the pick's order and the (small) rule.

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 the project's readability floor or unmeasured, then the goals file'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 no information 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/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/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; it loads with todo.md, and CLAUDE.md → "Topic rules" asks for it before an item is filed or changed. 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/chunk_driver/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.

todo.md: tools and agents read and change the plan as it stands only through bin/plan_store and todo-item; a tool that reads what a past commit held, ranks the file or checks its rank still parses todo.md

2026-11-14, the worker of todo item 350. Serves goal 1.6: a client keeps its plan where its team works, so no tool or agent may assume a file. bin/plan_store/plans.py holds the interface, PlanStore. todo_md.py holds its markdown backend, FilePlan, and stores.py picks the backend the config names; contract.py holds the tests every backend passes, as bin/record_store/ does for the records. An agent reads and changes the plan with todo-item: list, show, add, edit, move and finish. finish <ID> --no-changelog also drops an item no chunk built.

Four choices the item left open:

  • Three kinds of tool still parse todo.md. Four read what a past commit held: score-outcomes, the routing figures, release_standing's todos_since, and larv-review's plan before the chunk. Only a markdown plan has commits, and todo items 365, 366 and 368 port those tools. Two rank the file, through FilePlan.rank: rank_todo.py and larv-review record-scoring. One checks its rank, through FilePlan.check: rule-hook's todo-rank-check, whose Jira twin is todo item 367.
  • todos_since is empty for a plan outside the checkout, since no commit holds that plan. Before, it read the file as it stood in place of each past commit, which said the same as the plan itself.
  • list and show print no Score. The store hands items over in the backend's order, and a tracker has no score, so an item's place in list says how it ranks within its release. Whoever plans a release compares Scores across releases, and so opens todo.md, until a store hands over a score.
  • The spellings list [--release], move <ID> --release, and edit <ID> with one flag per cell, --detail from stdin and --clear-detail are those a panel of three fresh readers, seated as the audience, picked over a positional release, set and retarget. edit refuses stdin text without --detail, and --detail without text, so no detail is dropped or wiped by mistake.

rules/todo-items.md loads when a session itself reads or writes a todo.md, which a session that runs todo-item never does, so CLAUDE.md → "Topic rules" asks for it before an item is filed, scored, edited or moved. A reviewer without a shell reads the plan from the listing larv-review reviewer-header writes, which the header's Plan: line names. Valid while todo-item is the only command that changes a plan's items.

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 project's 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. 2026-11-11, lilleman: a project principle in AGENTS.md now stands in for the titles of the decisions it covers. 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.