Files
claude-config/todo.md
T
lilleman 49964b5d64
CI / tests (pull_request) Successful in 3m26s
Finish item 472 in the plan
2026-11-20 23:43:29 +01:00

107 KiB
Raw Blame History

todo

Scoring

Score = 100 * V / (2**S + 32)

Bar = 0.1

Next ID = 511

Items

ID Release Blocked by Exempt Item L E I R S Moves Score
479 0.15.0 owner Record in a decision which of CLAUDE.md, path-scoped rules, agents, skills, hooks and plugins Claude Code loads from a CLAUDE_CONFIG_DIR home, whether a long-lived token logs in there, and where its transcripts and model catalogue land. 1 2 1 2 3 1.6 by 4 1.3
500 0.15.0 owner Mutate the Go lines a branch changes with Gremlins in mutate-changes, as it mutates Python, Rust, TypeScript and PHP, and print each mutant the tests do not kill. 2 2 2 4 4 1.1 by 4 1.2
501 0.15.0 479, 500 owner Ship task-bench, which plants a bug the tests catch at the places the comprehension seats found hardest, has Haiku fix it in a vanilla Claude Code at a base and a head, and prints for each side how often the fix passes, with its median tokens, turns, wall time and reads before it opens a file the bug is in. 4 2 1 5 9 1.1 by 5, code health by 4 0.6
502 0.15.0 501 owner Distil each task-bench run into a digest of short traces and decoys, the files most failing runs read but no fix touches, and have a stronger model turn it into plan items before the transcripts are deleted. 3 2 1 4 5 1.1 by 4, code health by 4 4.8
469 0.15.0 Move a do-epic parent issue whose sub-tasks a person filed to Release Ready once every sub-task has landed, and to Done once every sub-task is done, by transitions its config names. 3 2 2 5 4 1.2 by 4, 1.5 by 4, 1.6 by 3 3.1
503 0.15.0 502 owner Calibrate task-bench on fejkdata: bench a head against itself for the noise floor, then one finished chunk at its base and head, and record in a decision how many tasks and runs the bench needs. 1 2 1 2 2 1.1 by 3 1.2
509 0.16.0 503 owner Run task-bench beside the scoring run in larv-review comprehension check, and record its figures in the comprehension history beside the panel scores. 3 2 3 6 5 code health by 5, 1.1 by 3 5.6
504 0.16.0 503 owner Bench new features in task-bench, each a spec for Haiku with acceptance tests it never sees and a reference patch that proves it can be built, kept in a bench-tasks folder the project config names, starting with six for fejkdata. 3 2 1 4 6 1.1 by 4, code health by 3 2.6
505 0.16.0 504 owner Bench adding source data in task-bench: hand Haiku a fake register that a seeded script generates for a made-up country, and check the importer, the data and the licence entry it adds, starting with five tasks for fejkdata. 3 2 1 4 5 1.1 by 3, code health by 2 2.6
508 0.16.0 501 owner Plant bugs for task-bench in Python, Rust, TypeScript and PHP, from the mutants mutate-changes runs for each, so this repo benches itself. 3 2 1 4 5 1.1 by 3, code health by 2 2.6
506 0.16.0 504 owner Go over the bench features in each release review: reapply each reference patch, drop a feature that no longer breaks a goal, and add features until they cover the places the seats find hardest. 2 2 2 4 3 1.1 by 3 1.1
507 0.16.0 504 owner Bench rebuilding a feature the project shipped: revert its commit at the head, hand Haiku its item tagline, and check with the tests that commit added. 3 2 1 4 5 1.1 by 3 0.7
477 0.17.0 question Rewrite ## Goals and ## Audience for a setup others install and run apart from their own ~/.claude. 1 1 2 2 2 0.0
478 0.17.0 question Name the project, its repo and its two commands, today proposed as do-release and do-epic. 1 1 2 2 1 0.0
480 0.18.0 owner Resolve every path the tools use in one module: the release root (the folder the running code ships in), the config folder, the state folder and the Claude home. Then only that module names ~/.claude, and the loop still runs from ~/.claude. 3 2 3 6 6 1.6 by 3, code health by 3 2.4
481 0.18.0 480 owner Put the release's tools on PATH for every session the loop starts and every hook it runs, name them bare in the prose in place of ~/.claude/bin/<tool>, and refuse the old spelling in new prose. 3 2 3 6 6 1.4 by 2, code health by 2 1.6
482 0.19.0 478, 479, 481 owner Install the setup with uv tool install from a release tag, with do-release and do-epic on PATH, and replace deploy-release with do-release self-update. 3 2 3 6 7 1.6 by 4, 1.3 by 3 1.3
485 0.19.0 478, 482 owner Rename loop-claude to do-release, and keep loop-claude as an alias that warns, for one release. 2 2 3 5 4 1.3 by 2 2.1
483 0.19.0 479, 482 owner Run every claude the loop starts in a Claude home the install generates from the release, with hooks that point into it and do-release login to sign in there, so the human's ~/.claude stays theirs. 4 2 3 7 7 1.6 by 6 0.5
486 0.19.0 483 owner Open an interactive claude in the loop's home with do-release claude, for a manual /larv-review or a talk with the setup loaded. 2 1 1 2 3 1.6 by 2 0.7
484 0.19.0 482 owner Keep project configs, this machine's rules, transcripts and review reports in ~/.config/do-release/ and ~/.local/state/do-release/, move them there with do-release migrate, and have rule-hook guard the new places. 3 2 4 7 6 1.6 by 3 0.4
487 0.20.0 483 owner Run larv-review's passes from a program that picks them from the diff and the item, counts rounds against the cap and decides each rerun, with each reviewer returning its findings as JSON against a schema. 4 2 3 7 8 1.1 by 5, 1.4 by 5 0.5
498 0.20.0 487 owner Drive each chunk as a state machine in do-release, from preflight through implementing, review, the pull request and the merge to finishing its items, with the worker as one model step that ends in a result that code checks. 4 2 3 7 8 1.1 by 4, 1.4 by 4 0.4
488 0.20.0 498 owner Cut the larv-review skill, CLAUDE.md and rule-hook down to what do-release doesn't own: the judgement the model makes and the safety guards. 2 2 3 5 5 1.4 by 4, code health by 2 2.8
489 0.21.0 498 owner Run every model step through a harness interface whose operations are a headless run, a one-shot reply, an interactive run, resume and reading a transcript, with each harness declaring what it supports and Claude Code as the first adapter. 4 2 3 7 8 1.3 by 4, code health by 3 1.3
492 0.21.0 489 owner Refuse to run a harness without pre-tool hooks in a project that sets an env-file, unless it runs in a sandbox that cannot read that file. 3 2 4 7 5 4 by 5 3.9
510 0.21.0 489 owner Run task-bench, its gather step included, through the harness interface, in place of calling claude -p directly. 2 2 1 3 3 code health by 2 3.1
491 0.21.0 489 owner Move the harness detail out of the shipped instructions, rules, standards, principles and reviewer briefs, and have each adapter render its own form, such as Claude Code's agent frontmatter, skills and settings. 3 2 3 6 7 1.3 by 3 0.9
490 0.21.0 489 owner Name a harness on each rung of the routing ladder, as {"harness": "claude-code", "model": …, "effort": …}, so the worker, the judge and each reviewer pick a harness as they pick a model. 3 2 3 6 5 1.4 by 3 0.6
493 0.21.0 490, 491 owner Add a second harness adapter and run one chunk of this repo on it end to end. 3 2 2 5 7 1.4 by 3, 1.3 by 2 0.9
495 0.22.0 owner Fail the gate where shipped content names a person, a client, a private host or a private URL. 2 1 3 4 3 4 by 5 6.2
497 0.22.0 498 decision Compare the first 10 chunks do-release's state machine drove with the 10 before them on tokens, 🔴 and 🟡 findings and interrupts per chunk, and move back to prose each step whose figures got worse. 1 2 1 2 3 1.1 by 3, 1.4 by 3 2.1
496 0.22.0 478, 491 owner Rename the repo to the name item 478 picks, and rename what says Claude where it means any harness, such as CLAUDE.md. 3 2 3 6 6 code health by 2 1.3
494 0.22.0 477, 483 owner Let a newcomer install, log in and run a first project from the README alone, with an example config, and test a fresh install in a container in the gate. 2 2 2 4 5 1.6 by 4 0.8
446 0.23.0 question Kill the process a stuck check names where its verdict is stuck, once the human says the recorded verdicts match what they would have done. 2 2 3 5 3 1.5 by 3 1.0
462 0.23.0 Run under mutate-changes the tests that today fail in mutmut's copy of the tree, so a mutant of a line only they cover is killed. 2 1 2 3 3 code health by 3 4.7
77 0.23.0 Teach bin/metric-bench Go and TypeScript, rerun it once two projects' comprehension histories name places, and bring into review only a metric that tracks the panel. 4 2 1 5 6 1.1 by 7, 1.4 by 7 2.1
196 0.23.0 decision Replay the architecture, principles, overrides and product-owner passes with review-replay on Opus 5.5 projects, record each run in the review-replay routing decision, and, where a run qualifies a rung, add back the code that lowers a pass to it. 2 2 3 5 2 1.4 by 3 1.2
321 0.23.0 196 decision Evaluate the review passes that run on a rung review-replay qualified, against the chunks before them, and revert any pass whose findings or later fixes worsened. 1 2 1 2 2 1.1 by 3, 1.4 by 2 2.0
273 0.23.0 decision Re-tune the E + I steps of REVIEW_STEPS for 6 to 8 once 10 finished chunks have scored an E + I of 6 or more, from how well E + I orders their review rounds and 🔴 findings. 1 2 2 3 2 1.1 by 2, 1.4 by 3 2.0
268 0.23.0 End a run whose release is ready to cut with a notice on loop-claude's terminal, in place of an interrupt that waits for an answer. 2 2 3 5 3 1 by 5 1.9
499 0.23.0 defect Stop todo-item add and edit from waiting on a stdin that stays open without data, so a call without a heredoc ends at once. 2 2 2 4 2 1.5 by 3, 1.4 by 2 1.9
445 0.23.0 Refuse a plan that holds an item a Finish item <ID> commit already removed, so a merge resolution cannot bring a finished item back. 2 2 2 4 3 1.4 by 3, 1.1 by 2 1.8
171 0.23.0 decision Group the routing figures' review rounds by the reviewers' rung as well as the worker's, so a call blames a rung only for rounds its own reviews raised. 3 2 2 5 4 1.2 by 3, 1.4 by 3 1.8
300 0.23.0 owner Reach the comprehension floor: restructure the places the comprehension seats found hardest to follow, so the project reads at 7.0 or above on every dimension, Locality and Self-sufficiency first; today the scoring run at a357cc7b scored Navigation 7.00, Locality 6.00, Shape 6.13, Self-sufficiency 6.00 and Overall 6.38. 4 2 3 7 8 code health by 8 1.7
264 0.23.0 Report the comprehension seats and the escalated subagents as subagent types of their own in routing-figures.md, with their dollars. 2 2 1 3 3 1.4 by 5 1.7
323 0.23.0 Count a release review as landed once its pull request has merged, whatever its commits are titled. 3 2 3 6 3 1.4 by 3, 1.5 by 2 1.7
342 0.23.0 Research the tooling agents read, search and run commands with once more, and file an item for each tool that cuts tokens a replay shows keep quality. 1 2 1 2 3 1.4 by 3, 1.5 by 2 1.7
471 0.23.0 Ship jira-rest METHOD PATH [BODY], which makes one Jira Cloud REST call with the credentials of the project's config, or do-epic's, reading the env file itself, so an agent calls Jira without naming a file rule-hook guards. 2 2 4 6 3 1.6 by 3, 1.4 by 2 1.7
149 0.23.0 decision Fill each release by priority up to a capacity it states, in place of the bar, and move what does not fit to a later release. 4 2 3 7 5 1.1 by 7 1.6
165 0.23.0 Make this repo's tests assert the facts a prompt or help text carries in place of its sentences, and drop the tests that scan source or assert a constant. 3 2 1 4 5 1.1 by 4, 1.4 by 3 1.6
392 0.23.0 owner Group bin/'s packages by concern into seven folders (plan, records, integrations, loop, review, forge and host), so a newcomer finds a tool's neighbours in one place. 3 1 3 5 7 code health by 4 1.6
456 0.23.0 Make the child-shell stop test pass under load, so a full test run doesn't fail on a race. 2 2 2 4 2 1.1 by 2, 1.5 by 2 1.6
151 0.23.0 decision Keep 10 to 20 settled decisions per project as its goals' test set, and rerun them after a goal changes. 3 2 2 5 5 1.2 by 7 1.6
68 0.23.0 principle Test workflow-bench/compare.py's blinding and bench.py's run plan. 2 1 1 2 4 1.1 by 5 1.5
102 0.23.0 Give loop-claude's retry delay, and the file it reads the machine's memory from, environment overrides, so the black-box test stops replacing time.sleep and machine_load.memory.MEMINFO through sitecustomize. 1 1 2 2 3 1.1 by 4 1.5
135 0.23.0 Fingerprint only the modules loop-claude imports, so editing another tool's code no longer reloads a running loop. 2 2 3 5 3 1.1 by 4 1.5
443 0.23.0 Measure whether compacting a waiting worker's session cut the cost of 20 chunks with an interrupt, with quality holding. 2 2 1 3 3 1.4 by 4 1.4
5 0.23.0 decision Key a project on its checkout's full path, and refuse to start while another session uses that key. 4 2 3 7 5 1.1 by 6 1.4
291 0.23.0 owner Let principles/technical-principles.md → "Sane defaults" allow a library whose README goals ask that it work with no config to default the clock and randomness in its public constructor, where a documented option overrides each. 1 2 3 4 1 1.2 by 3 1.3
156 0.23.0 decision Drop rank_todo.py's ranking of an old-shape table once no project under ~/code holds one. 2 1 3 4 4 1.1 by 4 1.2
388 0.23.0 Refuse an agent's Write or Edit of a routing ladder file in rule-hook, since a change to the ladder is the human's. 1 1 3 3 2 1.2 by 3 1.2
365 0.23.0 Have score-outcomes read the finished and dropped items of a plan outside the checkout, from the project repo's history or from Jira's issue changelogs. 3 2 2 5 4 1.6 by 2, 1.1 by 2 1.2
368 0.23.0 Call a release review due, call a release ready to cut, and tell whether a chunk owes a scoring run, for a plan outside the checkout, from the project repo's history or from Jira. 3 2 2 5 4 1.6 by 2, 1.1 by 2 1.2
260 0.23.0 decision Compare the first 20 chunks whose worker got the reading rule with the 20 before them, on review rounds past each pass's first, unfinished verdicts, 🔴, 🟡 and misread findings, dollars and hours per chunk, and drop the rule where any rose. 1 2 1 2 2 1.4 by 3 1.2
309 0.23.0 Run a scoring run's second pass on one head with two seats in place of four, once larv-review agreement shows the seats agree with each other more than a run agrees with its rerun. 2 2 2 4 2 1.4 by 3 1.2
51 0.23.0 principle Hand loop-claude's terminal output to an injected effect, so no storage or retry function prints. 2 1 3 4 5 1.1 by 5 1.1
419 0.23.0 Run the external auto-reviewer until its review of the PR's head has no findings, and answer each of its threads on the PR. 3 2 3 6 5 1.1 by 5 1.1
444 0.23.0 Rank an epic item that is split by repo, by the goals of each repo its sub-tasks name. 2 2 2 4 3 1 by 3 1.1
366 0.23.0 Count the chunks of a project whose plan sits outside the checkout in the routing figures, from the project repo's history or from Jira. 3 2 2 5 4 1.6 by 2, 1.4 by 2 1.1
201 0.23.0 owner Save the human's tmux setups and restore them after a reboot, so work is up and running again quickly. 3 2 1 4 4 1.5 by 4 1.1
267 0.23.0 Keep waiting when an interrupt gets an empty answer, at the terminal or in the claude opened for it, in place of stopping the loop. 2 1 3 4 2 1.5 by 3 1.1
4 0.23.0 Name each chunk's archive folder by the chunk's start time, so <key>/ lists chunks in the order they ran. 3 2 3 6 3 1.1 by 3 1.1
324 0.23.0 Count in the routing figures the finished chunks whose worker wrote no Chunk items: line. 2 2 1 3 3 1.1 by 2, 1.4 by 1 1.1
187 0.23.0 Count the tokens a worker spends reading reviewers' reports, so goal 1.4's signal shows whether report files lowered what a review costs the worker's context. 2 2 1 3 3 1.4 by 3 1.0
266 0.23.0 Move the chunks archived under the key home/lilleman/.claude to the key claude-config, so the routing figures and score-outcomes count this repo's chunks as one project. 3 2 2 5 3 1.4 by 3 1.0
339 0.23.0 Lower the reading cost of the files a chunk reads most before its first commit. 2 2 1 3 3 1.4 by 3 1.0
341 0.23.0 Hand each worker's claude a lower Read limit through CLAUDE_CODE_FILE_READ_MAX_OUTPUT_TOKENS, kept only where replays of the archived review rounds find what two unchanged replays find. 2 2 3 5 3 1.4 by 3 1.0
181 0.23.0 principle Have the test of a quoted answer's step-up assert the stepped rung's facts as literals, not through prompts.rungs_held. 1 1 1 1 1 1.1 by 2 0.9
193 0.23.0 Narrow numbered's mark to Mark by a typed lookup in place of typing.cast, so a mark added to the regex but not the lookup fails at run time, and one added to the lookup but not Mark fails mypy. 1 1 3 3 1 1.1 by 2 0.9
194 0.23.0 Make test_waits_out_a_usage_limit_which_ends_a_run_of_failures expect a usage-limit wait independent of the wall-clock time that passes during the run. 1 1 1 1 1 1.1 by 2 0.9
298 0.23.0 Send the judge only the decision entries and the transcript tail a verdict needs, and keep the cut only where judge-replay changes no verdict kind. 3 3 3 7 4 1.4 by 2, 1.5 by 1 0.9
265 0.23.0 Archive each wait that costs a chunk wall time, for a usage limit, low memory, a failed worker start or a heavy slot, with its start and end stamps, so goal 1.5's hours split waiting from work. 3 2 2 5 4 1.5 by 3 0.8
475 0.23.0 Have stability-reviewer report, as a finding, each lookup that an input from outside the repo can make fail without an error naming what was missing. 1 1 2 2 2 1.1 by 2 0.8
395 0.23.0 decision Keep each block a save didn't change, with its localId, and the spacing paragraphs beside it as Jira or Confluence holds them. 3 2 2 5 5 1.6 by 4 0.8
425 0.23.0 Show on loop-claude's terminal why it doesn't start a chunk beside the next item, as chunk-preflight prints it. 1 1 2 2 2 1.5 by 2 0.7
169 0.23.0 Have rule-hook's todo-rank-check catch a todo.md that the same Bash call edits and then commits. 3 1 3 5 3 1.1 by 2 0.7
447 0.23.0 Stop a headless claude call that runs past a time limit, and report it as a failure, so a hung judge or stuck check can't hold the loop. 2 2 2 4 3 1.5 by 2 0.7
367 0.23.0 Check that every write to a Jira plan leaves it ranked, as rule-hook's todo-rank-check checks todo.md today. 2 2 3 5 3 1.6 by 2 0.7
423 0.23.0 Skip the judge's model call on a worker's final message that the offline classifier decides is finished. 3 3 3 7 5 1.4 by 2 0.4
197 0.23.0 Let the human edit what they type at loop-claude's terminal questions with the arrow keys, so Left moves the cursor in place of printing ^[[D. 2 2 3 5 2 1.5 by 1 0.4
1 0.24.0 question Say in README → Install how the transcript archive is backed up, once bender-infra backs up ai-sandbox's data volume. 1 2 1 2 1 0.0
397 0.24.0 owner Script each step that the chunks of releases 0.10.0 to 0.22.0 repeated by hand and a program can compute, filing one item per step, and file this audit again for the next release. 1 2 1 2 2 1.4 by 3, 1.5 by 3 2.3

Details

479. Record in a decision which of CLAUDE.md, path-scoped rules, agents, skills, hooks and plugins Claude Code loads from a CLAUDE_CONFIG_DIR home, whether a long-lived token logs in there, and where its transcripts and model catalogue land.

Part of the standalone-install plan lilleman approved on 2026-11-20. do-release and do-epic stand for the names item 478 picks. The plan runs every claude the loop starts in a Claude home of its own, so the human's ~/.claude stays theirs. Find out by testing on a throwaway home, never the human's. The result decides whether the loop gets a home of its own, or loads the setup with --plugin-dir, --settings and --append-system-prompt-file instead.

lilleman moved it into 0.15.0 on 2026-11-20, ahead of item 501: task-bench runs Haiku in a container, which is a fresh Claude home signed in by a long-lived token, so the decision also says how that container signs in.

Touches:

  • docs/decisions.md: ## Claude Code in a home of its own: what loads from CLAUDE_CONFIG_DIR, and how a long-lived token signs in

500. Mutate the Go lines a branch changes with Gremlins in mutate-changes, as it mutates Python, Rust, TypeScript and PHP, and print each mutant the tests do not kill.

fejkdata runs Gremlins v0.6.0 from a compose service of its own today, so a Go project's review mutates outside the shared tool. Run gremlins unleash --diff <merge base> --output <file> through --prefix, as the other tools run, read its JSON report, and print each mutant that LIVED or is NOT COVERED as <path>:<line>:<column>: <status>: <mutator>. Leave out *_test.go. Gremlins v0.6.0 mutates one run of lines per hunk, so its git runs with diff.context=0, as fejkdata's compose file sets. A worktree keeps git's data outside the folder a container mounts: --help shows the prefix that mounts it, as fejkdata's README does with GIT_COMMON_DIR.

Touches:

  • bin/mutate_changes/main.py: (module) (small), mutate (small)
  • bin/mutate_changes/changed_lines.py: TOOLS (small), TEST_NAME (small)
  • bin/mutate_changes/in_diff_tools.py: run_gremlins
  • bin/mutate_changes/test_mutate_changes.py
  • README.md: ## Tools (small)

501. Ship task-bench, which plants a bug the tests catch at the places the comprehension seats found hardest, has Haiku fix it in a vanilla Claude Code at a base and a head, and prints for each side how often the fix passes, with its median tokens, turns, wall time and reads before it opens a file the bug is in.

The panel's scores barely move between chunks, and reading-cost measures chunks whose tasks differ. A planted task stays fixed, so a change in its cost comes from the code. The bench runs only programs; no model judges anything in it.

  • Plant. Run Gremlins, as item 500 runs it, without --diff, over the files that hold the places larv-review places prints. Draw 5 of its KILLED mutants by a seeded pick, and re-apply each at its file, line and column. The task's text is the failing assertion's message, without the test's name, file or line, so it says what goes wrong and not where. Go is the first language; item 508 adds the others.
  • Copy. The tree at the commit, without .git, committed once with the bug in it, so git diff and git log show Haiku nothing.
  • Run. Inside a container that holds only the copy: the project's development image with Claude Code added, such as golang for fejkdata, signed in by a long-lived token in an environment variable, with a memory limit and the network only for the API. In it, claude -p --bare --strict-mcp-config --disable-slash-commands --no-session-persistence --model claude-haiku-5-5 --effort low --output-format stream-json runs with every tool, Bash included, so Haiku greps, builds, runs the CLI and runs single tests as an agent normally does. A narrower tool list would raise the figures for reasons outside the code, and an allowlist can't fence Bash anyway: a rule that allows cat allows it on any path, such as the real checkout, whose diff would give away the bug. --bare drops the human's instructions, memories, hooks, skills and plugins, which would skew the figures and change with claude-config. The repo's README, AGENTS.md and docs/ stay, since they are part of what the bench measures; a project's CLAUDE.md, which --bare skips, is passed in, so every project is measured alike.
  • Pair. 5 runs per task at the base and at the head, in one bench, so a model or CLI update moves both sides. Each result names the Claude Code version and the model id.
  • Check. The project's test command over Haiku's changes to files other than tests, with the tests restored from the commit, so deleting a test doesn't pass.
  • Measure. From the stream: passed or not, tokens split into input, cache write, cache read and output, turns, wall time, and the reads before the first open of the file the bug is in.
  • Print. One row per task and side, then the head's change against the base. Results and transcripts go under the chunk's review folder.

It runs under run-heavy. The image, the test command and the mutator's prefix are flags, as in mutate-changes. Item 503 sets the task and run counts.

Touches:

  • bin/task-bench
  • bin/task_bench/main.py
  • bin/task_bench/plant.py
  • bin/task_bench/runs.py
  • bin/task_bench/test_task_bench.py
  • README.md: ## Tools (small), ### Packages under `bin/` (small)

502. Distil each task-bench run into a digest of short traces and decoys, the files most failing runs read but no fix touches, and have a stronger model turn it into plan items before the transcripts are deleted.

The thought process of the runs shows why Haiku failed, but whole transcripts would flood the model that reads them. A program distils them; only the last step uses a model.

  • Trace. One line per tool call, such as Read pick.go:120-180 or Grep "readName" → 4 hits, with the model's text between calls cut to 3 lines.
  • Decoys. Per task, the files more than half its failing runs read that the fix doesn't change. They name the code that misled the runs.
  • Digest. The figures, the decoys, and per task two traces picked by rule: the failing run that spent the most tokens and the passing run with the median tokens. A few kilobytes per task. The raw transcripts stay beside it, for the model to open one by its run id where the digest leaves a question open.
  • Gather. task-bench gather starts a claude on the project's rung with the digest and a prompt kept beside the code. It files a plan item with todo-item add for each place to make easier, citing the decoys and traces that show it.
  • Delete. Once gather ends, the bench run's folder goes, transcripts and traces with it. Each bench run also deletes the folders earlier runs left, so a session that crashed doesn't leave data growing. The figures alone outlive the run, in what item 509 records.

Touches:

  • bin/task_bench/digest.py
  • bin/task_bench/gather.py
  • bin/task_bench/gather-prompt.md
  • bin/task_bench/main.py: main (small)
  • bin/task_bench/test_task_bench.py

469. Move a do-epic parent issue whose sub-tasks a person filed to Release Ready once every sub-task has landed, and to Done once every sub-task is done, by transitions its config names.

do-epic moves to done only a parent it split itself (split_items_closed). A parent whose sub-tasks a person filed stays as Jira holds it, and --status says "its sub-tasks are done; close it in Jira". Until someone moves it, the parent blocks every issue it blocks, and through it their sub-tasks. On TW-13503, TW-13505 blocks most of the critical path this way, and TW-13547's sub-tasks are all Release Ready while the parent stays In Progress. The human asked, on 2026-11-20, for deterministic code to move these parents, not a worker or a person.

  • A parent whose sub-tasks have all landed, each in one of jira-unblocking-statuses or done, with at least one not yet done, moves by a transition the config names, such as jira-landed-transition = "Release Ready".
  • A parent whose sub-tasks are all done moves by jira-finish-transition, as a split item does today.
  • do-epic moves such parents as each run plans, and after each chunk finishes, where it now closes split items. A parent already at or past the target status stays: one in a done status never moves back.
  • A parent with no sub-tasks, or with one sub-task still open, is left alone.
  • Without jira-landed-transition, only the move to Done happens, and only where jira-finish-transition is set, as today.
  • --dry-run prints each parent move it would make.

Choice, made 2026-11-20: a sub-task in any of jira-unblocking-statuses counts as landed, so TW's "Teach & Learn" counts as "Release Ready" does. The human named Release Ready and Done; Teach & Learn also means the work merged.

Release: lilleman moved it back into 0.15.0 on 2026-11-20, after dropping the plan to cut 0.15.0 early. A chunk had started it in 0.15.0 and was stopped before it committed; its naming panel picked jira-sub-tasks-landed-transition for the setting, 2 to 1.

Touches:

  • bin/do_epic/main.py: split_items_closed, planned_and_started (small)
  • bin/do_epic/planning.py: planned (small)
  • bin/do_epic/scheduler.py: chunks (small)
  • bin/do_epic/split.py: finished (small)
  • bin/do_epic/config.py: DoEpicConfig, load (small)
  • bin/do_epic/backend/protocol.py: EpicStore
  • bin/do_epic/backend/jira.py: JiraEpic
  • bin/do_epic/backend/fake.py: MemoryEpic
  • bin/do_epic/backend/contract.py
  • bin/do_epic/dry_run.py
  • bin/do_epic/test_do_epic.py
  • bin/do_epic/backend/test_jira.py
  • README.md: ### Set up a project (small)

503. Calibrate task-bench on fejkdata: bench a head against itself for the noise floor, then one finished chunk at its base and head, and record in a decision how many tasks and runs the bench needs.

The decision records the spread of the pass rate and of the median tokens when both sides are the same commit, the task and run counts at which a chunk's change rises above that spread, and what one bench costs in tokens and hours. Where no affordable count rises above the noise, it says so, and files what to try instead. The bench's defaults take the counts it picks.

Touches:

  • docs/decisions.md: ## task-bench: how many tasks and runs a bench takes
  • bin/task_bench/main.py: main (small)

509. Run task-bench beside the scoring run in larv-review comprehension check, and record its figures in the comprehension history beside the panel scores.

It stays a report beside the panel until about 10 chunks show whether the two agree; whether it can replace the scoring run or gate a merge is the human's call then.

504. Bench new features in task-bench, each a spec for Haiku with acceptance tests it never sees and a reference patch that proves it can be built, kept in a bench-tasks folder the project config names, starting with six for fejkdata.

Each feature breaks one of the project's goals while it would suit another audience, so none ever turns into a real plan item, lies half-built in the code, or tempts a merge. A stronger model writes the tasks once. A run counts only where the acceptance tests fail at both the base and the head before Haiku starts, and pass with the reference patch. Haiku's copy leaves the folder out.

fejkdata's first six, each with the goal it breaks:

  1. {p!} picks the name p again (4.3, a name keeps one pick); it exercises pick.go, the seats' hardest place.
  2. {frist} renders as {first}, with a warning on stderr (4.7, fejkdata does not guess at mistakes).
  3. --typos 0.1 misspells one value in ten, for testing deduplication (3.3, values look real).
  4. {@define full = {first} {last}} defines a macro that {@full} prints (4, more syntax).
  5. --table prints a boxed, aligned table (the bulk author, who pipes CSV).
  6. --unique-forever keeps a state file, so no value repeats across runs (seeded output reproduces).

505. Bench adding source data in task-bench: hand Haiku a fake register that a seeded script generates for a made-up country, and check the importer, the data and the licence entry it adds, starting with five tasks for fejkdata.

Adding a source is fejkdata's recurring work, so it stays easy only while the bench shows it does. The country code comes from ISO 3166-1's user-assigned range (AA, QM–QZ, XA–XZ, ZZ), leaving out XK, which the EU and others use for Kosovo, so no task meets real data. Each register has the quirks real ones publish, and its script regenerates it byte for byte.

The checker runs a template such as {/person[QZ]} with a fixed seed, fejkdata's full test suite with the data-licence tests, and the importer again, which must reproduce the committed data.

fejkdata's five:

  • D1: names weighted by frequency, from a semicolon CSV in Latin-1.
  • D2: addresses, with postcodes mapped to towns, from nested JSON; values that belong together come from one pick.
  • D3: a valid national id, from a spec page giving the checksum; the checker validates every id the template prints.
  • D4: companies with legal-form suffixes, from an XML register.
  • D5: D1's register in its next edition, with a renamed column and a new code list, so Haiku updates an importer that exists.

508. Plant bugs for task-bench in Python, Rust, TypeScript and PHP, from the mutants mutate-changes runs for each, so this repo benches itself.

Each tool reports a killed mutant by file and line, and some by column; the planter re-applies it from that report, as it does Gremlins'.

506. Go over the bench features in each release review: reapply each reference patch, drop a feature that no longer breaks a goal, and add features until they cover the places the seats find hardest.

A reference patch that no longer applies is rewritten by the review's model. A feature whose goal changed may have become real work, so it goes. New features follow item 504's rule: plausible for another audience, against one of this project's goals.

507. Bench rebuilding a feature the project shipped: revert its commit at the head, hand Haiku its item tagline, and check with the tests that commit added.

Such tasks cost nothing to write and are realistic. A commit whose revert doesn't apply cleanly at both the base and the head is skipped.

477. Rewrite ## Goals and ## Audience for a setup others install and run apart from their own ~/.claude.

Part of the standalone-install plan lilleman approved on 2026-11-20. do-release and do-epic stand for the names item 478 picks. Goal 2, "Make my claude setup shareable between computers", and an audience of lilleman, with client teams as readers of what the loop writes, no longer fit. The goals and the audience are the human's to write; propose a wording and ask.

478. Name the project, its repo and its two commands, today proposed as do-release and do-epic.

Part of the standalone-install plan lilleman approved on 2026-11-20. Later items say do-release and do-epic for the names this item picks. The names set the install folders, such as ~/.config/do-release/, so items 482, 485 and 496, and every item they block, wait for them.

480. Resolve every path the tools use in one module: the release root (the folder the running code ships in), the config folder, the state folder and the Claude home. Then only that module names ~/.claude, and the loop still runs from ~/.claude.

Part of the standalone-install plan lilleman approved on 2026-11-20. do-release and do-epic stand for the names item 478 picks. Today about 160 references in some 40 modules name ~/.claude; bin/loop_state/paths.py holds a few. This item changes no behaviour.

481. Put the release's tools on PATH for every session the loop starts and every hook it runs, name them bare in the prose in place of ~/.claude/bin/<tool>, and refuse the old spelling in new prose.

Part of the standalone-install plan lilleman approved on 2026-11-20. do-release and do-epic stand for the names item 478 picks. About 70 places in CLAUDE.md, rules/, skills/ and agents/ name a tool by its path in ~/.claude/bin/. Keeping the tools on PATH only inside the loop's sessions keeps short names such as wait-for out of the human's shell. And prose that names no install folder works under every harness.

482. Install the setup with uv tool install from a release tag, with do-release and do-epic on PATH, and replace deploy-release with do-release self-update.

Part of the standalone-install plan lilleman approved on 2026-11-20. do-release and do-epic stand for the names item 478 picks. Add a pyproject.toml that ships the Markdown as package data. uv tool install keeps each tool in an environment of its own, so do-release self-update reinstalls it from the newest tag, and reinstalling an older tag rolls it back.

485. Rename loop-claude to do-release, and keep loop-claude as an alias that warns, for one release.

Part of the standalone-install plan lilleman approved on 2026-11-20. do-release and do-epic stand for the names item 478 picks. The loop will run harnesses other than Claude Code, so its name stops naming one.

483. Run every claude the loop starts in a Claude home the install generates from the release, with hooks that point into it and do-release login to sign in there, so the human's ~/.claude stays theirs.

Part of the standalone-install plan lilleman approved on 2026-11-20. do-release and do-epic stand for the names item 478 picks. The home holds CLAUDE.md, rules/, agents/, skills/ and a generated settings.json, unless item 479's decision loads the setup by flags instead. The human's theme, status line and /model stay in their own ~/.claude. This repo develops itself through the loop, so merge only after one chunk of this repo has run end to end from the new install, and keep the old layout working until then.

486. Open an interactive claude in the loop's home with do-release claude, for a manual /larv-review or a talk with the setup loaded.

Part of the standalone-install plan lilleman approved on 2026-11-20. do-release and do-epic stand for the names item 478 picks. Once the loop has its own home, the human's own claude no longer loads this setup or its rule-hook; this command is how they opt in. Say in the README that only the loop's sessions and this command get rule-hook's guards.

484. Keep project configs, this machine's rules, transcripts and review reports in ~/.config/do-release/ and ~/.local/state/do-release/, move them there with do-release migrate, and have rule-hook guard the new places.

Part of the standalone-install plan lilleman approved on 2026-11-20. do-release and do-epic stand for the names item 478 picks. Today they live in ~/.claude-projects/, ~/.claude/rules/this-machine/, ~/.claude/*-transcripts and ~/.local/state/larv-review. Read the old places for one release, warning on each read. From the first release that reads project configs from ~/.config/do-release/, rule-hook must read each env-file from those configs and refuse a read of it.

487. Run larv-review's passes from a program that picks them from the diff and the item, counts rounds against the cap and decides each rerun, with each reviewer returning its findings as JSON against a schema.

Part of the standalone-install plan lilleman approved on 2026-11-20. do-release and do-epic stand for the names item 478 picks. It applies the decision loop: a step whose result a program can check … in docs/decisions.md. The reviewer briefs stay prose. Start here, since larv-review holds the most sequencing rules.

498. Drive each chunk as a state machine in do-release, from preflight through implementing, review, the pull request and the merge to finishing its items, with the worker as one model step that ends in a result that code checks.

Part of the standalone-install plan lilleman approved on 2026-11-20. do-release and do-epic stand for the names item 478 picks. Keep the worker's step coarse, such as "implement this item in this worktree": many small model calls each reread the context, which raises reading cost, goal 1.4's counter-signal.

488. Cut the larv-review skill, CLAUDE.md and rule-hook down to what do-release doesn't own: the judgement the model makes and the safety guards.

Part of the standalone-install plan lilleman approved on 2026-11-20. do-release and do-epic stand for the names item 478 picks. The skill becomes a thin call of the program, so /larv-review still works by hand. rule-hook keeps its guards on secrets, destructive commands and writes outside the worktree, and drops the checks of step order the program now owns.

489. Run every model step through a harness interface whose operations are a headless run, a one-shot reply, an interactive run, resume and reading a transcript, with each harness declaring what it supports and Claude Code as the first adapter.

Part of the standalone-install plan lilleman approved on 2026-11-20. do-release and do-epic stand for the names item 478 picks. The claude_code package and the calls of claude in bin/loop_effects/effects.py move behind it. Capabilities to declare: subagents on their own model, pre-tool hooks, skills and path-scoped rules.

492. Refuse to run a harness without pre-tool hooks in a project that sets an env-file, unless it runs in a sandbox that cannot read that file.

Part of the standalone-install plan lilleman approved on 2026-11-20. do-release and do-epic stand for the names item 478 picks. Without hooks rule-hook can't stop a worker reading the project's credentials, which breaks goal 4.

491. Move the harness detail out of the shipped instructions, rules, standards, principles and reviewer briefs, and have each adapter render its own form, such as Claude Code's agent frontmatter, skills and settings.

Part of the standalone-install plan lilleman approved on 2026-11-20. do-release and do-epic stand for the names item 478 picks. rule-hook's rules stay harness-neutral too, and each adapter translates its harness's hook payload into them.

490. Name a harness on each rung of the routing ladder, as {"harness": "claude-code", "model": …, "effort": …}, so the worker, the judge and each reviewer pick a harness as they pick a model.

Part of the standalone-install plan lilleman approved on 2026-11-20. do-release and do-epic stand for the names item 478 picks. A rung without a harness reads as claude-code, so today's ladders keep working. A change to a ladder's rungs is the human's, so this item changes only the file's shape.

493. Add a second harness adapter and run one chunk of this repo on it end to end.

Part of the standalone-install plan lilleman approved on 2026-11-20. do-release and do-epic stand for the names item 478 picks. Compare candidates on what they support and what a chunk costs before choosing; putting the harness on a rung of the ladder is the human's call.

495. Fail the gate where shipped content names a person, a client, a private host or a private URL.

Part of the standalone-install plan lilleman approved on 2026-11-20. do-release and do-epic stand for the names item 478 picks. Shipped content is what the install copies: instructions, rules, agents, skills, standards and principles. CLAUDE.md names lilleman today.

497. Compare the first 10 chunks do-release's state machine drove with the 10 before them on tokens, 🔴 and 🟡 findings and interrupts per chunk, and move back to prose each step whose figures got worse.

Part of the standalone-install plan lilleman approved on 2026-11-20. do-release and do-epic stand for the names item 478 picks. This checks the decision loop: a step whose result a program can check … in docs/decisions.md against the signals goals 1, 1.1 and 1.4 already name.

496. Rename the repo to the name item 478 picks, and rename what says Claude where it means any harness, such as CLAUDE.md.

Part of the standalone-install plan lilleman approved on 2026-11-20. do-release and do-epic stand for the names item 478 picks. Moving the repo changes every clone's remote; say so in the release's changelog.

494. Let a newcomer install, log in and run a first project from the README alone, with an example config, and test a fresh install in a container in the gate.

Part of the standalone-install plan lilleman approved on 2026-11-20. do-release and do-epic stand for the names item 478 picks. Check that LICENSE.md fits a public release.

446. Kill the process a stuck check names where its verdict is stuck, once the human says the recorded verdicts match what they would have done.

Item 422 judges a worker that stalls before its result, but only reports: each verdict goes to the terminal and to stuck-workers.md in the project's transcript archive. Question for the human: after a few days of verdicts there, do they match what you would have done? Once you say yes, kill only the process a stuck verdict names, and only where the pid is below the worker's claude, never the worker or the loop, and record the call in a decision.

Touches:

  • bin/agent_cycle/stuck_workers.py: Watch.check
  • bin/loop_effects/child_shells.py: stop (small)
  • bin/loop_claude/loop/usage.py: HELP (small)

462. Run under mutate-changes the tests that today fail in mutmut's copy of the tree, so a mutant of a line only they cover is killed.

Found while shipping item 461: mutate-changes printed 23 mutants on changed lines, 18 not killed. Left out the tests that fail without a mutant, in do_epic/test_main.py, larv_review/test_larv_review.py, larv_review/test_scoring_setup.py, plan/test_ranking.py, repo_checks/…, review_rules/test_review_passes.py, review_rules/test_reviewer_context.py, rule_hook/test_rule_hook.py, test_settings_filter.py. All 18 survivors were in bin/larv_review/scoring_setup.py: prepare_scoring, whose tests are among those left out, so the chunk checked four of them by hand and left 14 unchecked. Find why each left-out test fails in mutmut's copy, such as a path to skills/ or a git checkout it expects, and make it pass there, or report under the count which changed lines no remaining test covers.

Touches bin/mutate_changes/, and the tests named above.

77. Teach bin/metric-bench Go and TypeScript, rerun it once two projects' comprehension histories name places, and bring into review only a metric that tracks the panel.

2026-10-08, lilleman: no metric enters review until a rerun on more data shows it tracking the panel.

Before the rerun, set the AUC and top-k lift over chance that count as tracking, from a published threshold, so the rerun ends in a decision. The rerun needs places from a project in Go or TypeScript, the languages most other projects use, so the bench first measures those languages, run through each project's own tooling. Function and file length stay warnings to look into, never limits: a plain long function can be simple, and a hard one may need five-line pieces.

On 2026-10-08 only this repo's history named places: five scoring runs, all that day. The medians:

Metric AUC Top k
Cognitive complexity 0.66 0.26
Length 0.74 0.18
Shared state constant constant
Change spread 0.67 0.18

AUC is 0.5 for a coin toss, and top k scores 0.10 by chance. Shared state cannot be judged here: every unit in bin/ scores 0 on it. Every run's first place was a section of skills/larv-review/SKILL.md, which no code metric sees.

On 2026-10-09 a question bench asked a headless claude, allowed only Read, Grep and Glob, three questions a script answers from the syntax tree: which units call a unit, which units it calls, and which test files refer to it. It asked them about every unit the history names whose name is unique, plus as many units the history does not name. Five of the history's six scoring runs named such a unit. The tool is in commit 083cc78; it was deleted after the run.

Claude's misses ranked the named units at a coin toss. Top k scores 0.50 by chance on these units:

Metric AUC Top k
Question misses 0.49 0.50
Cognitive complexity 0.66 0.59
Length 0.75 0.69
Change spread 0.57 0.54

Claude's answers overlapped the truth by a median Jaccard index of 0.76. A run took in 62,643 new input tokens and cost $0.70; it did not record which model answered. Grep answers these questions whatever the code's shape, so no question enters review; a new question bench would need questions that take understanding the code, not finding it.

196. Replay the architecture, principles, overrides and product-owner passes with review-replay on Opus 5.5 projects, record each run in the review-replay routing decision, and, where a run qualifies a rung, add back the code that lowers a pass to it.

Item 159's chunk, PR #322, replayed only the prose and stability passes. Sonnet 5.5 at high missed 44 to 55% of what the project's rung found again in each, so the agent judged a replay of the other four unlikely to qualify a rung. The product-owner review of PR #322 asked that the plan keep them, so the ranking decides when they run. Each run costs hours of reviewer replays (goal 1.4), so the score keeps it low until a cheaper model joins the ladder. docs/decisions.md → 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 the runs so far. The release review of 0.6.0 deleted the code that lowered a pass, since no rung had qualified; the decision says where it goes back.

321. Evaluate the review passes that run on a rung review-replay qualified, against the chunks before them, and revert any pass whose findings or later fixes worsened.

The prose pass's replay under item 318's new bar, on 2026-11-12, qualified no rung, so this item waits for item 196's replays of the other passes. lilleman, 2026-11-11: that bar is a risk, so check it closely a release later. Compare the first 20 chunks reviewed on each newly qualified rung with the 20 before: review rounds past the first, 🔴 and 🟡 per chunk, misread findings, and later fixes that score-outcomes counts (defects that escaped review). Revert a pass to the project's rung where any of those worsened beyond the spread of the 20 before.

273. Re-tune the E + I steps of REVIEW_STEPS for 6 to 8 once 10 finished chunks have scored an E + I of 6 or more, from how well E + I orders their review rounds and 🔴 findings.

docs/decisions.md → routing: one ladder… records why lilleman kept the steps on 2026-11-08. Of the 36 chunks it measured, 1 scored an E + I of 6 or more and none 7 or more, so the steps for 6 to 8 are untested. Start once score-outcomes shows 10 finished chunks with an E + I of 6 or more. Then read its rank correlation for E + I, and the routed-chunks table of routing-figures.md in loop-claude's archive ($LOOP_CLAUDE_TRANSCRIPTS, default ~/.claude/loop-claude-transcripts). Propose new steps to lilleman, whose call they are.

268. End a run whose release is ready to cut with a notice on loop-claude's terminal, in place of an interrupt that waits for an answer.

On 2026-11-08 the human answered notice only: the loop prints that the release is ready to cut and ends; no interrupt, and nothing waits in loop-inbox.

Releases are the human's, and CLAUDE.md → "Working loop" already ends the loop once a release is ready to cut, so the ask settles nothing. 15 interrupts in the archive ask whether the human will cut a release, and about 6 of the 45 interrupts from 2026-11-02 to 2026-11-10 said a release was ready to cut; log's 2.5.0 was asked twice within an hour on 2026-11-10. On 2026-11-08 one of the 4 questions waiting in ~/.local/state/loop-claude/ is such an ask, plainpages-plugin-fastjira's 0.3.0 since 2026-11-03. Today a release ready to cut opens claude's session at once (bin/agent_cycle/run.py ask), and the loop stops if the human leaves it with nothing typed. The change also touches what an interrupt covers in CLAUDE.md → "Vocabulary". Where the change touches ask, make it easier to read, as the seats named it.

499. Stop todo-item add and edit from waiting on a stdin that stays open without data, so a call without a heredoc ends at once.

On 2026-11-20 todo-item edit 488 --blocked-by 498, run from the Bash tool without a heredoc, waited 19 minutes on 0 seconds of CPU: its stdin was the harness's socket, which never closed, and piped() in bin/text_files/piped_text.py, called from bin/todo_item/main.py, read it to refuse stray detail text. The same call with </dev/null took seconds. Give the read a short deadline, so a stdin that stays open without data reads as empty, and keep edit's refusal of text on stdin without --detail. Test add and edit with a stdin that stays open. Correct piped's docstring, which says the Bash tool hands /dev/null.

445. Refuse a plan that holds an item a Finish item <ID> commit already removed, so a merge resolution cannot bring a finished item back.

Merging main into item-442 in 610edb1a resolved a todo.md conflict by keeping item 310's row and detail, which e019a6b7 had just finished. loop-claude then started a chunk on item 310, whose work had already merged, and that chunk only removed the item again. No check noticed: rank_todo.py --check reads one file, and rule-hook's todo-rank-check sees only an agent's writes, not what a merge resolution keeps.

Have the gate, or rank_todo.py --check where it runs in a checkout, refuse a plan that holds an ID a commit titled Finish item <ID> removed on the default branch, naming the commit. An item removed by mistake can come back only under a new ID, which keeps the check simple.

171. Group the routing figures' review rounds by the reviewers' rung as well as the worker's, so a call blames a rung only for rounds its own reviews raised.

Raised by the goals audit of PR #296. bin/routing_figures/calls.py groups a chunk's review rounds by the rung its worker started on, and calls for a routing change when a lower rung took more of them. Since PR #296 the reviewers may run above the worker's rung, on the one their item's E + I picks, and no figure groups rounds by it, though the archived worker line names the E + I it follows from. A cheap worker on an item of high E + I gets stronger reviewers, who may raise more rounds, and a call could then blame the worker's rung for them: an interrupt of lilleman that settles nothing (goal 1.2).

300. Reach the comprehension floor: restructure the places the comprehension seats found hardest to follow, so the project reads at 7.0 or above on every dimension, Locality and Self-sufficiency first; today the scoring run at a357cc7b scored Navigation 7.00, Locality 6.00, Shape 6.13, Self-sufficiency 6.00 and Overall 6.38.

Filed by the comprehension check of PR #473 at 13d1550 (larv-review record-scoring), which printed Floor: and Next:, and refreshed from the run of PR #646 at a357cc7b. The lowest means are Locality and Self-sufficiency, both 6.00. Locality: do-epic's parking and scheduling carry order-dependent state across loop turns, state files and flocks, and no code enforces the order. Self-sufficiency: the why of thresholds and orderings sits behind docs/decisions.md → … pointers, 109 of them in 79 modules, and the review rules live in prose that several code sites repeat. Refresh this item's places and aim from the newest run before the chunk starts; do not file a second floor item.

Aim: one ambitious refactor of the areas below, sized so every mean reaches 7.0 on the chunk's own scoring run. Where a place is already easier to read when the chunk starts, drop it.

Places the seats named, hardest first (larv-review places), Locality and Self-sufficiency first:

  • Locality, Shape: bin/do_epic/main.py:287 parked_through, with :354 resumed_news and :241 chunk_run: a three-step park and resume order, the told, finished and news flags and a poll that carries five locals across turns. The docstring gives the order, but no code enforces it and no comment states the loop's invariant. Three seats named it hardest; all three would least want to change it.
  • Locality, Self-sufficiency: bin/agent_cycle/routing.py:115 unfinished_route, with :131 escalated_route: five rungs, a count, the escalation mark and the cap held at once. The module table resolves the what, but the why of each threshold is only in the decision log. Three seats named it.
  • Locality: bin/do_epic/scheduler.py:144 start_chunks: four overlapping sets feed a five-branch chain, counted under nested locks shared with loop-claude. Two seats named it.
  • Locality, Shape: bin/rule_hook/round_cap.py:10 round_cap_breaches, with bin/review_rules/round_titles.py:33 round_counts, bin/larv_review/reviewer_header.py:75 unanswered_round and skills/larv-review/SKILL.md:89 "Round cap": the cap lives in four places across three packages, none owns the whole invariant, and the rules exist a third time in the help at bin/larv_review/main.py:1. Three seats named it.
  • Shape, Self-sufficiency: bin/project_config/settings.py:187 load: about twenty comprehension clauses in one faults list encode the rules that link settings; named predicates would make each findable. Two seats named it.
  • Locality, Shape: bin/chunk_pr/main.py:314 merged, with :447 levelled_and_finished: a queue loop whose variables carry a string or a Failure, and a scoring-run check the name doesn't suggest. Two seats named it.
  • Locality: bin/plan/ranking.py:239 score, with :144 weigh: the old and new table shapes run through the whole module. Two seats named it.
  • Locality: bin/agent_cycle/judge.py:76 TASK_HEADING, with bin/model_routing/route.py:47 and bin/loop_claude/loop/reload.py:36 decode_handed: archive and handover formats that a reworded heading or a renamed field breaks, guarded only by comments. Three seats named one of them.
  • Shape: bin/agent_cycle/judge.py:237 quotes_checked, with bin/agent_cycle/run.py:150 rule: checks that quietly turn one verdict type into another, and one function that runs the judge, steps up and orders the archive writes.
  • Locality: bin/larv_review/plan.py:21 Emptied: a str subclass whose type carries meaning, lost by any code that rebuilds the string.
  • Shape: bin/do_epic/gates.py:42 gate: a long ordered chain where a missing value means something different on each line.
  • Shape: bin/agent_cycle/stuck_workers.py:52 Watch.check: the condition at line 59 mixes or and and without parentheses over state mutated out of sight.
  • Self-sufficiency: bin/agent_cycle/verdicts.py:41 and bin/agent_cycle/run.py:103: comments that cite cycle.judge.re_ask_checked and close.py, neither of which exists; bin/agent_cycle/judge.py:116 Rejected names loop-claude in a module do-epic shares.
  • Navigation, Shape: README.md:225 "Packages under bin/": 84 entries in alphabetical prose with no grouping by layer, two bullets run together at :239, and 40 packages whose __init__.py is empty.
  • Shape: bin/loop_claude/loop/reload.py:18 LoopRun: loop-claude's core run state in a module named for self-reloading; Run, ChunkRun and LoopRun are one concept in three types.
  • Locality: reviewer-merge-trials/driver.py:4: a frozen trial imports live code under bin/, so a refactor there breaks a record.

264. Report the comprehension seats and the escalated subagents as subagent types of their own in routing-figures.md, with their dollars.

Seats launch as general-purpose, so they hide inside that type: $301.24 of the $962.17 the figures of 2026-11-04 count, from 221 subagents. By 2026-11-10 general-purpose was the second-largest spend, $585 of about $2,385, and by transcript size about two thirds of it were seats (291 launches), then 177 security passes. Escalations are counted by trigger only, never in dollars. bin/routing_figures/chunk.py groups subagents by their subagent_type; a seat is told apart by its prompt, and an escalated subagent by the escalation marker its prompt opens with.

323. Count a release review as landed once its pull request has merged, whatever its commits are titled.

release_reviewed in bin/release_plan/release_standing.py counts a release review only by a commit titled Release review of <release> on the default branch. In a replay of archived interrupts (judge-field-trials/), in two projects whose release review had merged, the default branch held no such commit, so chunk-preflight and routing read ReviewDue, and the next loop would run the release review again. skills/larv-review/SKILL.md opens the review's branch with an empty commit of that title, but a worker may skip it, and a rebase or squash merge, which chunk-pr uses where the forge allows no merge commit, may drop it. Detect the review by something every merge method keeps, and check the fix against both projects' histories. Until then the judge keeps release_ready (docs/decisions.md → routing: loop-claude reads the items a chunk takes …).

342. Research the tooling agents read, search and run commands with once more, and file an item for each tool that cuts tokens a replay shows keep quality.

The next round of item 312's research, filed when 312's round ran on 2026-11-12. lilleman, 2026-11-11: repeat the round once per claude-config release, not per project. When this item's chunk finishes, file the next round into the next claude-config release with items left.

Run it as 312's ran: a lead on the project's rung plans 6 to 10 searches where the archive's spend is, cheaper subagents with web access only return sourced findings, and the lead checks each claim against the archive's measured spend before filing.

Sources that proved useful in 312's round: Claude Code's environment variable reference (https://code.claude.com/docs/en/env-vars), its subagent reference (https://code.claude.com/docs/en/sub-agents), its CHANGELOG (https://github.com/anthropics/claude-code/blob/main/CHANGELOG.md), the API's context editing and tool search pages (https://platform.claude.com/docs/en/build-with-claude/context-editing, https://platform.claude.com/docs/en/agents-and-tools/tool-search-tool), and Anthropic's post on code execution with MCP (https://www.anthropic.com/engineering/code-execution-with-mcp). Check a variable a source names with a grep of the installed Claude Code binary; issue mirrors and blogs gave leads but no figure to rely on. The archive counts that decided: command-patterns <version> --calls, and scripts in /tmp over loop-claude's archive summing tool results by agent type, cache writes by lifetime and request gaps, and each subagent's first request.

Dropped in 312's round, and why; look again only where the reason has changed:

  • Editing through Edit in place of python3 heredocs: Edit already accepts a file read with sed or cat on Claude Code 2.1.319 to 2.1.322, 27 such Edits in 0.7.0 and 0.8.0 and no "not read yet" refusal in the archive, and an Edit would have saved about 2,300 command tokens per chunk.
  • Forcing 5-minute caches on the worker or 1-hour ones on subagents (FORCE_PROMPT_CACHING_5M, ENABLE_PROMPT_CACHING_1H): over 53 chunks, the worker's 1-hour writes cost $217 at list prices against $233 for 5-minute ones, and subagents' 5-minute writes cost $226 against $289 for 1-hour ones.
  • A security-pass agent type with fewer tools: its 49 runs started at a median 30k tokens and cost $14 in all.
  • Deferred tool loading: already on, since ENABLE_TOOL_SEARCH defaults on and saves MCP tool definitions only.
  • Context editing and programmatic tool calling: API features that Claude Code doesn't expose as a setting.
  • LSP, repo maps and outline scripts: item 231's trial lost findings and agents didn't call them; the only figures found since are a vendor's and a blog's.
  • Compact test reporters and output filters such as rtk: this archive's test output is a few thousand tokens per release, and the filters' figures are their own; trimming read output is item 311's ceiling.

471. Ship jira-rest METHOD PATH [BODY], which makes one Jira Cloud REST call with the credentials of the project's config, or do-epic's, reading the env file itself, so an agent calls Jira without naming a file rule-hook guards.

Once a Jira credentials file is a config's env-file, rule-hook's env-file-read refuses every Bash command that names it. A machine's own rules that tell agents to source it and curl Jira then stop working. On 2026-11-20 this happened on a machine whose rules call Jira that way, and a machine-only script, ~/.local/bin/jira-rest, took their place. The human asked for it as a claude-config tool, so every machine has it.

  • jira-rest METHOD PATH [BODY.json | -] sends one call to a path under /rest/, with the body from the file or stdin, and prints Jira's JSON answer, or null for an empty one. A refused call exits non-zero with the message atlassian.client.jira_errors gives. No output, error or log line holds a credential.
  • The site and the env file come from the project's config where the checkout has one whose plan or goals-and-audience is a Jira epic: the epic's site and the config's env-file. Otherwise they come from do-epic's config: jira-url and env-file. Where neither holds them, it fails, naming both places.
  • It sends through atlassian.client, as plan_store and do_epic do, so it gains their error messages and timeouts.
  • --help states the contract, and README → ## Tools lists the tool.

After it ships, the machine's ~/.local/bin/jira-rest is removed, and its rules call the shipped tool.

149. Fill each release by priority up to a capacity it states, in place of the bar, and move what does not fit to a later release.

A release's capacity is a sum of its items' cost, as the formula counts it. Each project states its own; the human sets the first value per project. Nothing is deleted by score.

165. Make this repo's tests assert the facts a prompt or help text carries in place of its sentences, and drop the tests that scan source or assert a constant.

A test audit across lilleman's projects on 2026-10-16 found 10 of 33 sampled tests in this repo pinning wording that is not the contract. Examples of these and other weak tests: many tests under bin/loop_claude/, bin/chunk_driver/ and bin/agent_cycle/ pin whole sentences of the question, archive, prompt or help text, up to about 750 characters. test_every_exit_1_stop_has_its_clause_in_help and test_every_failed_judge_run_has_its_clause_in_help parse the source with ast and list each Stop(...) and Failure(...) call by function name. bin/model_routing/test_ladder.py asserts len(LADDER) == 6. Rewrite each to the technical principles' test bullet: assert the facts the text must carry, such as an item ID, a rung or a model argument, and delete a test no real bug could fail. Before and after rewriting a test, run the mutation tool on the code it covers: every mutant the old test killed, the new one kills.

392. Group bin/'s packages by concern into seven folders (plan, records, integrations, loop, review, forge and host), so a newcomer finds a tool's neighbours in one place.

The 0.11.0 release review's architecture pass, round 1, finding 9: bin/ holds 43 packages, about 20 launchers and 10 root files at one level, and the README's two lists are its only index. lilleman chose, during that review, to file this regrouping for a later release instead of doing it in 0.11.0, since it moves every package and no defect lies behind it.

Group bin/ by concern, one package level per group, with the launchers left at the root:

  • plan/: the plan core, with plan_store, release_plan, todo_item and touch_predictions.
  • records/: record_store, project_record and project_config.
  • integrations/: atlassian, adf_codec, rest_client and notifier.
  • loop/: loop_claude, loop_effects, loop_state, model_routing, transcript_archive and routing_figures.
  • review/: larv_review, branch_chunks, review_rules, judge_replay, review_replay, rung_replay, score_outcomes, metric_bench, reading_cost, command_patterns and mutate_changes.
  • forge/: chunk_pr, chunk_preflight and deploy_release, where item 287's shared forge module lands.
  • host/: git_cli, command_lines, claude_code, machine_load, run_heavy, run_tests, text_files, wait_for, rule_hook and subagent_rung.

repo_checks stays at the root, since it tests the repo, not a tool. The README's bin/ list then becomes seven short groups. That list is a place the comprehension seats found hard (README.md → the bin/ package list): make it easier to read.

456. Make the child-shell stop test pass under load, so a full test run doesn't fail on a race.

Found in a full bin/run-tests run on 2026-11-19, on a loaded machine: ChildShells.test_stops_a_shell_and_the_process_it_started_and_no_other (bin/loop_effects/test_effects.py:243) failed at line 249 with AssertionError: 0 != -15, and its file passed alone right after (36 passed). The branch changed nothing under bin/loop_effects.

The race, as far as reading shows: child_shells.stop sends SIGTERM to the shell's descendants first and to the shell last. The test's shell runs sleep 60; true. Once sleep dies, bash goes on to true and exits 0. When the test's process is descheduled between the two os.kill calls, bash has already exited, and the SIGTERM to its zombie does nothing, so wait returns 0. The same window is open in production: a shell running a loop, such as until false; do sleep 60; done, can start its next child between the kills, and that child outlives the stop, against stop's docstring. stop is called by loop-claude's lingering-worker check (bin/agent_cycle/lingering_workers.py:29, through bin/loop_effects/effects.py:106).

So the fix likely belongs in stop, not only in the test: signal the shell before its descendants, or SIGSTOP it first, so it can't run anything after its child dies. Make the test fail on the old order deterministically, for example with a shell whose loop restarts its child, rather than relying on timing.

Touches:

  • bin/loop_effects/child_shells.py: stop (small)
  • bin/loop_effects/test_effects.py: ChildShells.test_stops_a_shell_and_the_process_it_started_and_no_other

151. Keep 10 to 20 settled decisions per project as its goals' test set, and rerun them after a goal changes.

Each case is a question the project settled and the answer it chose. A fresh-context agent given only the README's premises answers each case; a case it answers differently says the goals no longer decide it. Written guidance can fail to change behaviour, which is why the goals get a test.

68. Test workflow-bench/compare.py's blinding and bench.py's run plan.

"Most, if not all, code should have automated tests", in principles/technical-principles.md: compare.blind() keeps the comparison blind, and a version name it misses invalidates the bench silently.

The tests also cover workflow-bench/bench.py's permission_flags, with a probe of a headless claude given its flags. It is denied a read outside the granted trees, a bare git status, and wrapper calls with --output, --no-index, a glued -aF/abs, --fil=/abs or a path outside the clone. A cd <elsewhere> && python3 <wrapper> … acts on the clone only. It is allowed the wrapper's log, diff, show, status, ls-files, add and commit -m. workflow-bench/test_review_git.py tests the wrapper's refusals directly.

102. Give loop-claude's retry delay, and the file it reads the machine's memory from, environment overrides, so the black-box test stops replacing time.sleep and machine_load.memory.MEMINFO through sitecustomize.

Found by the principles audit of PR #242. The SITECUSTOMIZE block in bin/loop_claude/test_black_box.py swaps the global time.sleep, the shape "Functional core, imperative shell" bans, and the audit of PR #376 found the same block swapping machine_load.memory.MEMINFO, the constant in bin/machine_load/memory.py. An override of each lets the test run the code as production runs it.

135. Fingerprint only the modules loop-claude imports, so editing another tool's code no longer reloads a running loop.

The maintainability senior and the inherited architect of PR #257's scoring run named fingerprint and exec_if_edited in bin/loop_claude/loop/reload.py: the fingerprint covers every bin/**/*.py, so editing statusline.py or rank_todo.py re-execs a running loop. Make fingerprint easier to read.

443. Measure whether compacting a waiting worker's session cut the cost of 20 chunks with an interrupt, with quality holding.

The check lilleman set for item 310 on 2026-11-11, which project principle 1 asks for before a cost cut stands: compare the cost entries of 20 archived chunks with an interrupt from before the compaction shipped against 20 from after it. Measure the tokens written to the cache by each resume after an interrupt, and the tokens per finished chunk, and check that review rounds and unfinished verdicts per chunk hold. Where the saving doesn't show, or quality drops, file an item to remove the compaction or retune COMPACT_FLOOR and CACHE_MARGIN in bin/agent_cycle/interrupt.py. Record the outcome as a decision. Start it once 20 chunks with an interrupt have run on 0.12.0 or later.

5. Key a project on its checkout's full path, and refuse to start while another session uses that key.

The key names the project's session, archive folder and models entry. project_key, in bin/transcript_archive/project_key.py, strips ~/code/ and then any leading /, so ~/code/a and /a share all three, and one loop can resume or delete the other's session.

bin/reading-cost keys the archive by the main checkout, the parent of git's common dir, since it runs in a chunk's worktree; loop-claude keys it by --show-toplevel, so a loop started inside a worktree archives where reading-cost never looks. Derive both keys one way.

291. Let principles/technical-principles.md → "Sane defaults" allow a library whose README goals ask that it work with no config to default the clock and randomness in its public constructor, where a documented option overrides each.

"Sane defaults" has a library ask for every input that can change between runs, the clock and randomness included, and leaves defaulting them to the code that wires a program together. A logging library's principles audit found that its constructor defaults both, as its first goal, useful with no config, asks. Its decision log records the defaults as a departure from the principle, and names this item as what ends it. Until then, each principles audit there may raise the defaults again.

2026-11-10, the human: keep the library's defaults, and give the principle an exception for this case, worded about as the tagline says. The exception has to square with "Functional core, imperative shell", which the same bullet cites and no other principle overrides.

156. Drop rank_todo.py's ranking of an old-shape table once no project under ~/code holds one.

While rank_todo.py ranks two shapes, projects follow two sets of scoring rules, against goal 1.3. Once every project has reshaped, drop OLD_SHAPE's weighing from bin/plan/ranking.py, RESHAPE, and the old shape's lines in rank_todo.py --help and rules/todo-items.md. Keep todo_table reading old tables: score_outcomes reads every past merge's todo.md. PR #283's paired ruling found the old-shape path made ranking.py's score, Scoring.weights, unknown_columns and todo_table.py's Moves harder to read; leave each easier, with one shape and moves that are always moves, and the Moves cell's rules in one place. Release 0.3.0's seats named ranking.py's score, weigh and rank and todo_table.py's OLD_SHAPE for the same fork: "every rule exists twice for the old table shape" (Mid A). Make weigh and rank easier to read too.

388. Refuse an agent's Write or Edit of a routing ladder file in rule-hook, since a change to the ladder is the human's.

Filed by PR #553, which made the routing ladder a file: bin/model_routing/routing-ladder.json, and a project's own routing-ladder.json in its config's folder. CLAUDE.md → "Working loop", "Ask, don't guess" reserves a change to the routing ladder for the human, and until PR #553 the ladder was code, which only a reviewed chunk changed. A worker can now write its project's file, and with it choose the rungs its own later cycles and reviews run on. The security pass of PR #553 noted that a ladder changed mid-cycle also makes rule-hook's reviewer-rung skip its check, since the rungs loop-claude handed are then off the ladder.

Project principle 4 asks that a rule a program can check is enforced by a program. Refuse a Write, an Edit and a MultiEdit of a file named routing-ladder.json under ~/.claude-projects/, with no override, and say that the ladder is the human's to change. The shipped file stays editable in the setup's own checkout, where a chunk's review covers it.

365. Have score-outcomes read the finished and dropped items of a plan outside the checkout, from the project repo's history or from Jira's issue changelogs.

lilleman's call, 2026-11-12: 0.10.0 and 0.11.0 switch the history tools off for a plan outside the checkout, and 0.13.0 holds only their ports. In Jira a dropped item, which Drop item commit titles mark today, is an issue resolved by a resolution the config names.

368. Call a release review due, call a release ready to cut, and tell whether a chunk owes a scoring run, for a plan outside the checkout, from the project repo's history or from Jira.

One of 0.13.0's history ports, per lilleman's call of 2026-11-12. Filed from item 344's stability review, round 1.

Today a plan outside the checkout is read as it stands, since no commit holds it. So:

  • bin/release_plan/release_standing.py's todos_since holds one text. Once a release's last item ships, the plan no longer names the release, and next_release gives the release after it as next. chunk-preflight and loop-claude say UNSEEN_RELEASES on every run: the release reviews and the cuts are the human's to call.
  • bin/larv_review/owed.py's owed_scoring_run says it cannot tell whether the chunk owes a scoring run, and the merge goes on. needs-scoring-run and record-scoring refuse the ID of an item the plan no longer holds.

Read the plan's earlier texts from the project repo's commits, which item 345 writes, or the releases Jira's issues name. Then drop UNSEEN_RELEASES and both refusals, and the bullets that record them in docs/decisions.md → "project config: a tool that reads a file's commits …".

The comprehension seats found next_release hard to read: the tag cases, dated headings, renames and named_releases meet in one function. Make it easier to read while there.

260. Compare the first 20 chunks whose worker got the reading rule with the 20 before them, on review rounds past each pass's first, unfinished verdicts, 🔴, 🟡 and misread findings, dollars and hours per chunk, and drop the rule where any rose.

Start once 20 chunks have run under the rule. The rule is READING_RULE in bin/chunk_driver/prompts.py, which every fresh worker prompt holds; git log --first-parent -S READING_RULE on the default branch finds the merge that added it. A chunk got it when its first worker started after that merge. Measure as docs/decisions.md → loop-claude: the worker's claude compacts its context before it fills a 200k window… measured the window: rounds past each pass's first and the 🔴, 🟡 and misread counts from the round commit titles, unfinished verdicts from the outcomes files, hours from the worker's first message to its last, and dollars from the chunk's cost-state entry. Compare means, since the decision weighs the rule by all spend.

309. Run a scoring run's second pass on one head with two seats in place of four, once larv-review agreement shows the seats agree with each other more than a run agrees with its rerun.

Seats cost $1,143 of the $9,154 measured from 2026-09-30 to 2026-11-11 (12.5%), scoring runs $470 of that. A scoring run today is four seats, run twice on one head: eight seat runs. Two seats on the second pass make it six, and two on both passes four.

Why it should hold quality: the seats are one model with different personas, so their errors are correlated, and a correlated extra seat adds little. larv-review agreement showed on 2026-11-11 that Mid A and the inherited architect voted alike in 58 of 75 paired rulings, while their scores moved alike between two runs on one commit in only 1 of 4 pairs: seats agree with each other more than a run agrees with its rerun, so the rerun carries more new information than the third and fourth seat. Nine judges from seven model families carried about two independent votes (arXiv 2605.29800), and ten with error correlation 0.21 carried 3.5 (arXiv 2609.22512).

Decide once larv-review agreement prints Assumption holds: or Assumption fails:; it needs 10 commits each scored twice before it can. Keep four seats on any pass that files a floor item, since its places come from seat reports. Revise the decision review: the comprehension check records how hard a project is to read…, which names the four-seat run.

lilleman moved it from 0.12.0 to 0.13.0 on 2026-11-17, when 6 commits had been scored twice.

Touches:

  • bin/larv_review/seats.py: SCORING_SEATS, scores
  • bin/larv_review/history_commands.py: record_scoring
  • bin/larv_review/scoring_setup.py: SEATS, prepare_scoring
  • bin/larv_review/main.py: (module) (small)
  • bin/larv_review/test_larv_review.py
  • bin/larv_review/test_scoring_setup.py
  • skills/larv-review/SKILL.md: ### Comprehension check
  • skills/comprehension-panel/SKILL.md: ## The scoring run (small)

51. Hand loop-claude's terminal output to an injected effect, so no storage or retry function prints.

"Functional core, imperative shell", in principles/technical-principles.md: say in bin/loop_effects/effects.py takes the effects but prints to stderr itself, and retried and the rest print through say. Two bare print(file=sys.stderr) calls remain outside them, in bin/agent_cycle/interrupt.py and bin/chunk_driver/project/model_choice.py. The tests swap the global stream.

419. Run the external auto-reviewer until its review of the PR's head has no findings, and answer each of its threads on the PR.

Today larv-review §3 → "Round cap" stops the auto-reviewer after two reviews. On a client project's pull request, CodeRabbit spent both reviews on the draft, before the internal passes were done, so its last finding got no answer on the PR. Change:

  • §3 → "Round cap": drop the auto-reviewer's cap. Every finding it makes, whatever its severity, is fixed or shown wrong, and each push waits for its review of the new head. The pass is done when that review adds no finding.
  • §4 step 6: detect a clean review. CodeRabbit posts no review when it has no findings. Instead it updates its summary comment with "No actionable comments were generated in the recent review" and a coveredCommitId that matches the head. Wait for that, not for a new review.
  • Answer every thread in place, with the fix's commit or the reason for not making it.
  • chunk-pr ready and chunk-pr merge refuse while an auto-reviewer thread has neither our reply nor resolved status, read from the thread state GitHub's API reports.
  • round-count, rule-hook's round-cap and the "Answer … round" titles need no change, since the auto-reviewer's commits already take ordinary titles.
  • Once this ships, delete the first two bullets of the machine-local CodeRabbit rule file, which say the same thing for one machine.

The change touches skills/larv-review/SKILL.md "Re-entry", which the comprehension seats found hard to follow (Locality): make it easier to read while editing it.

444. Rank an epic item that is split by repo, by the goals of each repo its sub-tasks name.

Today bin/do_epic/planning.py → ranked_keys leaves an item marked split-by-repo at its position in the backlog, as it leaves a person's issue: ranking.ranked scores an item in one repo's chain of goals, and a split item has several repos. Its sub-tasks follow it, so the whole change keeps whatever rank the item had when it was filed.

Touches:

  • bin/do_epic/planning.py: ranked_keys
  • bin/do_epic/ranking.py: ranked
  • bin/do_epic/test_planning.py

366. Count the chunks of a project whose plan sits outside the checkout in the routing figures, from the project repo's history or from Jira.

One of 0.13.0's history ports, per lilleman's call of 2026-11-12.

201. Save the human's tmux setups and restore them after a reboot, so work is up and running again quickly.

The human asked on 2026-10-21 for tmux support, above all for saving tmux setups. Don't build anything until the human has said exactly what they need. Ask them at least:

  • What a setup holds, such as sessions, windows, panes, each pane's working directory and the command running in it, like one loop-claude per project.
  • When a setup is saved: on demand or on its own.
  • How a setup comes back after a reboot.
  • Whether the code that saves and restores setups must work on every machine that takes this checkout (goal 2), which decides whether that code lives in this repo.
  • What else tmux support should cover.

Weigh the widely used tmux-resurrect and tmux-continuum plugins against a script of our own. Then re-score this item from the answers and that choice, and split it into items where it is more than one chunk.

267. Keep waiting when an interrupt gets an empty answer, at the terminal or in the claude opened for it, in place of stopping the loop.

11 runs in the archive ended with "Stopped: the human is needed to answer the question above, but the interrupt ended without anything typed", each leaving its chunk open until the human restarted the loop. That stop comes from human_typed in bin/agent_cycle/interrupt.py, after the claude opened for /talk or for a release ready to cut ends with no human turn. An empty line at the terminal stops the loop the same way, in typed_answer. Item 268 removes one of the cases that opens claude.

4. Name each chunk's archive folder by the chunk's start time, so <key>/ lists chunks in the order they ran.

Today the folder is the SHA-256 of the transcript's first timestamped line, which tells the human nothing; that line carries the start time. Drop the fallback to the first line, which every chunk of a project shares, and give the tests' fake transcripts ISO timestamps. bin/reading-cost takes a chunk's id from the folder's first 12 characters and skips a chunk whose id docs/reading-cost.md holds, so give it a way to match a figure written under the old name.

324. Count in the routing figures the finished chunks whose worker wrote no Chunk items: line.

docs/decisions.md → routing: loop-claude reads the items a chunk takes … holds only while workers write the line when asked, and nothing counts a chunk whose worker skipped it. There loop-claude scores no item beyond the one the chunk was routed on, so the route holds. Count in bin/routing_figures/, beside the chunks counted, those whose worker's transcript holds no such line, so the human sees when the decision's premise stops holding.

187. Count the tokens a worker spends reading reviewers' reports, so goal 1.4's signal shows whether report files lowered what a review costs the worker's context.

Before PR #310, reports reached the worker as the Agent call's result, a median 19k tokens per chunk (2026-10-08, 68 archived transcripts). Now a reviewer returns its verdict and one line per finding, and the worker reads a 🔴 or 🟡 finding's entry from the report file. reading-cost counts only tracked files (bin/reading_cost/measure.py), and routing-figures counts only the Agent call's result (bin/routing_figures/chunk.py), so neither sees the report reads. Found by the architecture review of PR #310.

266. Move the chunks archived under the key home/lilleman/.claude to the key claude-config, so the routing figures and score-outcomes count this repo's chunks as one project.

The archive holds 277 chunk folders under home/lilleman/.claude, from 2026-09-24 on, and 39 under claude-config (2026-11-10). The routing figures of 2026-11-04 list no project home/lilleman/.claude. They find a chunk's later fixes on the default branch of the checkout its key names (bin/routing_figures/archive.py measure_project), and /home/lilleman/.claude is a release checkout on a detached HEAD. Item 5 fixes how keys are derived, not the chunks already archived. ~/.claude/loop-claude-models.json still holds a home/lilleman/.claude entry; it is machine state outside the repo, so removing it is a one-off step on each machine, not part of the change.

339. Lower the reading cost of the files a chunk reads most before its first commit.

reading-cost printed Rising: on 2026-11-12: the last 5 chunks' median is 128,199 new input tokens before their first commit, the 5 before them 101,795. Read most over the last 5, as opens and searches: todo.md 34, docs/decisions.md 26, README.md 19, skills/larv-review/SKILL.md 13, bin/agent_cycle/routing.py 8, CHANGELOG.md 6. The chunk that ships this runs reading-cost --reset.

Touches:

  • README.md
  • skills/larv-review/SKILL.md
  • bin/agent_cycle/routing.py

341. Hand each worker's claude a lower Read limit through CLAUDE_CODE_FILE_READ_MAX_OUTPUT_TOKENS, kept only where replays of the archived review rounds find what two unchanged replays find.

Raised by item 312's research round, 2026-11-12. Over the 53 chunks archived since 2026-09-30, Read results held about 3.17M tokens (characters / 4) in 1,617 reads. Results over 20,000 characters, about 5,000 tokens, held 479k tokens beyond that size in 115 reads: prose reviewers 144k, stability reviewers 119k, product-owner reviewers 102k, general-purpose subagents 65k, principles auditors 28k, architects 21k. Workers had none, under the reading rule in their prompt. Measured with a script over loop-claude's archive that sums each Read tool_result's characters by the subagent's agentType. The decision of 2026-10-27 found Read results out of a PostToolUse hook's reach; this variable reaches them.

CLAUDE_CODE_FILE_READ_MAX_OUTPUT_TOKENS overrides the Read tool's default limit of 25,000 tokens (https://code.claude.com/docs/en/env-vars, read 2026-11-12: "Override the default token limit for file reads, which is 25,000 tokens."). Claude Code 2.1.322's binary holds the name. A read over the limit fails and asks for an offset and a limit, so an agent may page through the same file and save nothing; the replay measures that.

loop-claude can hand it as it hands CLAUDE_CODE_AUTO_COMPACT_WINDOW, and subagents inherit it, the principles auditors included. The choice of 2026-10-27 that the principles audit reads the project whole holds as long as it pages through what it reads.

The replay: review-replay <pass> claude-opus-5-5 --read-limit already replays a pass's archived rounds three times as archived and once at 5,000 tokens (bin/review_replay/changes.py, bin/claude_code/output_limits.py). Run it for the prose, stability, product-owner and principles rounds. Keeps quality where each pass finds every finding the two unchanged replays both find, or misses no more than the most an unchanged replay misses, as --omit-claude-md counts it. Keep it only where the replays' Read characters also fall; the archived runs hold each result. Then hand the variable over in worker_environment for what passes.

Touches:

  • bin/agent_cycle/run.py: worker_environment (small)
  • bin/loop_claude/loop/usage.py: HELP (small)
  • bin/agent_cycle/test_run.py: Cycles (small)
  • bin/loop_claude/loop/test_usage.py: HelpLimits (small)

181. Have the test of a quoted answer's step-up assert the stepped rung's facts as literals, not through prompts.rungs_held.

bin/agent_cycle/test_run.py's test_a_quoted_answer_that_cites_an_escalation_trigger_steps_the_worker_up_before_it_resumes_and_archives_the_step builds its expected prompt from prompts.rungs_held, the code under test, so a bug there passes it. The technical principles' test bullet bans that shape. Assert the new rung and one review launch as literals, as the typed answer's step-up test does. Raised by the principles audit of PR #308.

193. Narrow numbered's mark to Mark by a typed lookup in place of typing.cast, so a mark added to the regex but not the lookup fails at run time, and one added to the lookup but not Mark fails mypy.

Found by review of PR #317. bin/plan/goals_file.py's numbered writes typing.cast(Mark, mark or None), which asserts the type goal_weights branches on without checking it: a mark added to the regex reaches goal_weights as a value Mark lacks. mypy does not read the regex, so no lookup lets it catch that. Replace the cast with a lookup typed dict[str, Mark], from each mark the regex captures, and "" for none, to its Mark value. A mark added to the regex but not the lookup then raises KeyError at run time, and a value added to the lookup but not Mark fails mypy.

194. Make test_waits_out_a_usage_limit_which_ends_a_run_of_failures expect a usage-limit wait independent of the wall-clock time that passes during the run.

Found by review of PR #317. The black-box test, bin/loop_claude/test_black_box.py:609, not the unit test of the same name in bin/agent_cycle/test_retry.py, which runs on a fake clock, sets resets_at from the test's time.time() and expects the wait, rounded to tens, to be 3720. When more than about 5 s pass between that read and the loop's, the wait rounds to 3710 and the test fails with no bug. Item 102 covers only replacing the time.sleep swap; this item changes the expected value, for example by asserting the wait against resets_at + 120 minus the time the loop read, or a bound on it.

298. Send the judge only the decision entries and the transcript tail a verdict needs, and keep the cut only where judge-replay changes no verdict kind.

153 Judge cost: entries total $109.76, a median of about $0.76 a verdict at every rung, and the cost follows the size of the records, not the transcript: about 76k characters in log and 188k in claude-config. In 224 of 251 recent verdicts (89%) the evidence sits in the worker's final message. A missed interrupt is the costly error, so the bar is zero changed interrupts and zero new rejections across the replay. The judge is about 4.5% of dollars, so the saving is small; each cycle also gets faster.

On 2026-11-20, with docs/decisions.md read once, claude-config's records take 285,754 characters. With a short task they leave the transcript about 107,500 of the judge's 400,000 characters, some 57,500 above the 50,000 it must read. The decision log grows about 4,000 characters a day, so the judge stops on claude-config, naming the shortfall, in about two weeks unless this item ships first.

Touches:

  • bin/agent_cycle/judge.py: Brief, judge_prompt, JUDGE_PROMPT_CHARS
  • bin/chunk_driver/project/records.py: read_records
  • bin/judge_replay/main.py: rule (small)
  • bin/judge_replay/replay.py: case_from (small)
  • bin/agent_cycle/test_judge.py: JudgePrompt
  • bin/chunk_driver/project/test_records.py: Records
  • bin/judge_replay/test_judge_replay.py

265. Archive each wait that costs a chunk wall time, for a usage limit, low memory, a failed worker start or a heavy slot, with its start and end stamps, so goal 1.5's hours split waiting from work.

No record holds these waits today. An outcomes file holds verdicts, stops, step-ups and the judge's cost (bin/transcript_archive/outcomes.py), and ~/.local/state/run-heavy/ holds only the slots' lock files. loop-claude waits out a usage limit and low memory in bin/agent_cycle/retry.py; run-heavy waits for a slot in bin/run_heavy/. A heavy slot's wait happens inside a worker's Bash call, so loop-claude doesn't see it; run-heavy would write it where the archive can find it.

475. Have stability-reviewer report, as a finding, each lookup that an input from outside the repo can make fail without an error naming what was missing.

A forge's auto-reviewer raised two such findings on a chunk whose stability pass had run two rounds and approved: an import script indexed a mapping parsed from a downloaded table by a key the table may leave out, so a gap in the source would have stopped the run with a bare KeyError and no word on which unit the source left out. The reviewer's agent file names error handling and edge cases, and not this case.

Add one line to agents/stability-reviewer.md, where it lists what to check: for every value the change reads from a file, a response or a table that the repo does not hold, follow each lookup by key or index on it, and report one that fails without a message naming the missing key, unless the code states that the key is always there and why. A deterministic tool was weighed first and fits badly: no linter tells a mapping parsed from outside data from one the code built.

395. Keep each block a save didn't change, with its localId, and the spacing paragraphs beside it as Jira or Confluence holds them.

Today a Jira detail edited in one line, or a Confluence record with one entry appended, is written back whole by adf-codec's portable pair, which drops each block's localId and the empty paragraphs Jira uses for spacing. A save whose text is the text a read showed already sends nothing (docs/decisions.md → project config: the loop shows a Jira description and a Confluence page as adf-codec's portable markdown, …). Match the saved markdown's top-level blocks against the held document's, each as the portable pair reads it, and send the held block where they match. The decision's limit on partial saves ends with this item.

425. Show on loop-claude's terminal why it doesn't start a chunk beside the next item, as chunk-preflight prints it.

chunks_beside names each item it refuses and why, such as an unreadable Touches: list, and chunk-preflight prints those lines, but loop-claude's chunk_windows.may_start keeps only picked and drops them, so idle slots show no reason. Found by item 424's product-owner review; a list a person edits in Jira's UI, or one filed before item 424, still reaches loop-claude unchecked.

169. Have rule-hook's todo-rank-check catch a todo.md that the same Bash call edits and then commits.

The hook judges a call before it runs, and changed in bin/rule_hook/todo_check.py compares todo.md with the index and HEAD as they stand then. A call that edits todo.md and commits it, such as a heredoc script followed by git commit, passes unchecked: PR #296's commit 149108e did, and the override marker it carried was never logged. larv-review's gate still runs rank_todo.py --check, so an unranked plan stops at merge rather than at commit. A git pre-commit hook would see the staged file.

447. Stop a headless claude call that runs past a time limit, and report it as a failure, so a hung judge or stuck check can't hold the loop.

Every headless claude that claude_reply runs, the judge's and the stuck check's included, runs without a time limit, and the stuck check runs while the worker's own claude waits for its output to be read. A call that hangs holds the loop, and the worker with it, until a person notices. Found by item 422's stability review.

Give the claude effect a timeout, and have claude_reply turn its expiry into a Failure that names who timed out, as it names a non-zero exit. Pick the limit from the longest such call the transcript archive shows, with room to spare, and say where it comes from in a comment at the constant.

Touches:

  • bin/loop_effects/effects.py: system_effects (small)
  • bin/claude_code/reply.py: claude_reply

367. Check that every write to a Jira plan leaves it ranked, as rule-hook's todo-rank-check checks todo.md today.

One of 0.13.0's history ports, per lilleman's call of 2026-11-12.

423. Skip the judge's model call on a worker's final message that the offline classifier decides is finished.

On 2026-11-18 lilleman ruled that the classifier's miss rate of about 1 in 100 decided is close enough to no missed interrupt (docs/decisions.md → 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).

Taking the item builds this: before the judge call, loop-claude runs the classifier trained on its archive over the worker's final message. Where the classifier decides finished, loop-claude skips the call. The classifier is re-trained as the archive grows. The judge call sits in bin/agent_cycle/run.py → rule, a place the comprehension seats found hard, since the order of stamping, archiving and stepping matters across three functions: make it easier to read.

The judge's model still decides every verdict the classifier leaves, the escalation a worker quotes, and whether a release is ready to cut, since the replay didn't test the classifier on those.

Evidence, from judge-replay claude-opus-5-5 --offline: the classifier reads only the final message, averages five seeded logistic regressions, and decides finished only where its chance of an interrupt is below that of every interrupt among its held-out training folds.

  • On the 1,116 archived verdicts it decided finished with no missed interrupt on both tests: held-out folds, 95 decided and none missed; latest fifth, 20 decided and none missed.
  • On the first 1,104 it missed one interrupt on the latest fifth, while the held-out folds decided 103 and missed none.
  • It decides about 1 in 12 verdicts. About 1 in 100 of those it decided were an interrupt, on the 1,104.

Savings: one judge call per about 12 verdicts. That is small, and nobody has measured it.

197. Let the human edit what they type at loop-claude's terminal questions with the arrow keys, so Left moves the cursor in place of printing ^[[D.

bin/loop_effects/effects.py hands loop-claude Python's builtin input, and nothing under bin/ imports readline, so the terminal gets no line editing: fixing a typo means erasing back to it. loop-claude asks two questions at its terminal. Both read through effects.input: the pick of the project's model, in project/model_choice.py's ask_for_model, and the interrupt's answer, in agent_cycle/interrupt.py's typed_answer. Importing readline in effects.py gives input line editing, at two costs. It moves the prompt from stderr to stdout, while the question above it stays on stderr. test_black_box.py waits for the prompt on stderr. readline's bracketed paste takes a pasted block whole, so an answer can hold several lines. worker_prompts.typed_answer ends the answer at its first blank line, so the judge would read the rest of such a paste as loop-claude's words. The product-owner review of PR #308 raised the interrupt's case. lilleman, 2026-10-18: "Not super-important, but a bit irritating."

1. Say in README → Install how the transcript archive is backed up, once bender-infra backs up ai-sandbox's data volume.

It lives under ~/.claude, which .gitignore keeps from the remote, so a lost disk loses every unattended run's record. Back it up only to a destination private to me and encrypted at rest: the worker runs with permissions bypassed, so the archived tool results can hold credentials it read.

2026-10-02, the human: ai-sandbox is the VM loop-claude will run on, hosted on the server bender. bender-infra, the infrastructure-as-code project that manages bender, will back up ai-sandbox's data volume once ai-sandbox is rebuilt. The item waits for the human to say the rebuild has landed; do not remind them. Before writing the README line, check that ~/.claude lives on that volume and that the backup is private and encrypted at rest.

The README line covers the bench's transcripts in workflow-bench/logs/ too (goal 3).

397. Script each step that the chunks of releases 0.10.0 to 0.22.0 repeated by hand and a program can compute, filing one item per step, and file this audit again for the next release.

lilleman asked, on 2026-10-16, for a standing audit each release, so the loop keeps moving work a program does as well from the model to scripts (goals 1.4 and 1.5). This audit reads the archived transcripts of the chunks that shipped releases 0.10.0 to 0.22.0 for every step that chunks repeated by hand, before, during or after review. It keeps the steps whose answer a program computes the same way each time, such as a lookup, a check, a prompt assembled for a reviewer, a cleanup. File one item per such step, with the time and tokens it cost, into the next release with items left. Leave a step that needs judgement with the model. Run command-patterns <version> first for each of 0.10.0 to 0.22.0; each run's table is the audit's starting point. read_threads and calls in bin/command_patterns/tally.py open the calls of one pattern, or command-patterns <version> --calls <file> dumps them all as JSON lines. The 0.7.0 audit found that most steps its chunks repeated were already scripted by that release's own tools, so a step a shipped item already covers is not filed.

A pattern's call count is a poor guide: most of the 0.9.0 calls were reading and hand edits, which stay with the model. Cluster the calls by their command text with numbers and paths normalised away, then check each cluster against the tools in ~/.claude/bin before filing.

The 0.8.0 audit filed four steps, items 334, 335, 336 and 337. The 0.9.0 audit filed one, item 396, and found most other repeated steps already covered by tools that shipped inside the release: chunk-pr merge's wait for the checks, run-tests, wait-for, larv-review round-title and todo-item show.

The chunk that ships this item files a copy of this audit in the release after this item's own, auditing the releases cut since, and marks the copy owner, so the audit recurs each release until lilleman drops it.