107 KiB
Changelog
0.14.0
loop-claude's judge stops, naming how much to cut the records by, rather than judge a prompt that leaves it less than the transcript's last 50,000 characters. A file the project's config names for two records is read once.- Under
merge = "human",loop-claudeandchunk-preflightpass over an item whose ready pull request awaits a person's merge, andloop-claudestops, naming those pull requests, once every item left awaits one. - do-epic reads two new settings from a project's config:
jira-unblocking-statusesnames the statuses at which an issue unblocks the issues it blocks, andjira-automation-moves-issuesleaves the move out of "In Progress" to the team's own automation. - The prose standard asks that a sentence about several named things holds for each of them.
do-epicresumes a chunk parked onyour mergewhen its pull request no longer merges into its base, so the worker runschunk-pr mergeagain to level the branch; a finished chunk in that state stays open until its pull request merges.larv-review prepare-scoringtakes the scoring run's project values from the checkout'sskills/comprehension-panel/seat-prompts.mdwhere the working-rules file holds no "Scoring run" section, not only where that file is missing.
0.13.0
- Fix loop-claude stopping after a finished chunk: its judge may now quote the worker's task as evidence, so the loop starts the next chunks instead of exiting.
- Add the project setting
merge = "human", for a team that merges its own pull requests:chunk-pr mergethen marks the pull request ready and leaves the merge to a person, and a do-epic chunk parks, shown asawaits your merge, until the pull request is merged. - do-epic reads a team's own repo labels: a
[label-repos]table in~/.claude-projects/do-epic/config.tomlmaps each such label to its repo, such astwu-4 = "tenant-web-ui-4", and do-epic reads a mapped label as it readsrepo:<name>. An issue a person filed a sub-task under is no longer split by repo: its sub-tasks run instead, each under a label of its own, and the team closes the issue. - do-epic --file takes --blocked-by and --parent , so a chunk files the next pull request of a change as an issue that waits for the one before it; a chunk's first prompt says when to use them.
0.12.0
- loop-claude asks a headless claude whether a worker that went quiet before its result is stuck, and prints the verdict and appends it to stuck-workers.md, without killing anything.
- loop-claude stops the background shells that hold a worker after its final result, once they have been quiet for a few minutes, and records each stop
- Add
do-epic-e2e, a command that runsdo-epicend to end against a sandbox epic on a real Jira site and deletes the epic afterwards. do-epic <EPIC-KEY>plans the epic before it starts chunks: it files a sub-task per repo under an open issue that changes several repos, labels each other unlabelled issue with where it is worked, asking on the terminal where the repo rule leaves that unclear, and puts the scored issues it filed in order of score.- loop-claude compacts a waiting worker's session 10 minutes before its hour-long prompt cache expires, where no answer to an interrupt has come and the context holds at least 60k tokens, so the resume doesn't write the whole context again.
- do-epic gives a
do-epic-humanissue that blocks another its own window: it DMs you once through the notifier of one of the epic's repos, takes no running slot, and polls until you close the issue in Jira, when the issues it held up may start. - do-epic tells an epic chunk's worker how its repo ships the change: a bullet under the repo's changelog where the repo publishes something, none where its plan is in Jira, and no
--finishforchunk-pr merge. do-epic <EPIC-KEY> --statussays which chunk asks you a question, and since when each parked chunk has awaited its gate.- do-epic moves a chunk's issue to done in Jira when the chunk finishes, and the split item it belongs to once its last sub-task is done, so no finished chunk starts again and the chunks it blocks start. It moves them by the transition
jira-finish-transitionandjira-finish-statusname, so set both; without them a finishing chunk stops with that reason. - Describe do-epic in the README: its entry under Tools, and its machine settings and
repo-rule.mdunder Set up a project. - do-epic finishes an epic: once none of its issues is open, a finishing chunk files a release review of each repo the epic changed, as an issue labelled
do-epic-release-review, and asks you to confirm each goal.do-epic <EPIC-KEY> --close-epicthen posts the summary piped in as a comment on the epic and closes it in Jira, by the transitionjira-finish-transitionnames, to the statusjira-finish-statusnames. - do-epic parks a chunk whose pull request waits on its checks, an approval or a new review: the chunk frees its place for the next one, its tmux window says what it awaits, and its worker goes on when the gate opens or a reviewer comments, even after a reboot.
do-epic <EPIC-KEY> --statusprints what each open issue does. - A chunk that
do-epicruns files a finding about an epic goal as an issue of the epic, withdo-epic <EPIC-KEY> --file, and records a decision in the epic's description, with--record-decision; its judge reads the epic's Scoring and Decisions before the repo's records. - Added
do-epic <EPIC-KEY>: it runs the chunks of one Jira epic, each in its own window of the tmux sessionepic-<EPIC-KEY>. As many run at once as the line**Max parallel chunks:** 2in the epic's description allows, one without it; a repo takes as many as itsparallel-chunks, and none while loop-claude runs chunks in it. loop-claude in turn starts no chunk in a checkout where do-epic runs one. - Refuse in rule-hook a Bash or Monitor command that waits forever: a sleeping loop with no time or count cap, and a
pgrep -forpkill -fwhose pattern its own command line matches. - A project's config may list its team's convention files in
coding-conventions, which larv-review's reviewer agents read beside the principles and the standards, the team's rule winning where they conflict. larv-review opens the pull request after its own review where a push to the branch starts CI, and files an item to add a mutation tool wheremutate-changescovers none of a language. The technical principles gain rules for tests on a shared environment, "Never mock a service your own team runs" and "Don't loosen a type when refactoring"; stability-reviewer checks a change that stores a value differently; and every finding of an outside reviewer now changes the setup, a deterministic tool first. - do-epic's epic backends rank a child issue just before another, in Jira and in memory, and do-epic can re-rank Jira's backlog to an epic's ranking: it moves only the issues the loop filed, so each issue a person filed keeps its place, and it stops at the first rank Jira refuses and names it. Nothing calls it yet.
- Comprehension seats run as the
comprehension-seatagent underagents/, which starts withoutCLAUDE.mdand the skill and agent listings, andlarv-review prepare-scoringno longer takes--preloaded; after updating, launch each seat withsubagent_type: comprehension-seat. - do-epic splits an epic item that changes several repos into one Jira sub-task per repo, each labelled
repo:<name>, with a headless claude call predicting the repos from the code; the item is markedsplit-by-repoand counts as done once every sub-task is, and an issue a person filed gets a comment for the team in the epic's language. The epic backends gaincomment, in the Jira backend and the in-memory one. - do-epic's epic backends read each issue's scores, its blockers and whether the loop filed it, in the Jira backend and the in-memory one; the Jira backend marks each issue it files as the loop's. Nothing calls it yet.
- The technical principles now forbid a test that decides at run time whether to check anything, by a conditional skip, early return or catch around its assertions, and stability-reviewer flags one.
- do-epic's scorer orders an epic's items by score, then by Blocked by: an item's Moves names a goal as
epic 1.1,code healthorrepo 2, and the epic's achieve goals outweigh the achieve goals of every repo. Nothing calls it yet. todo-item addandtodo-item edit --detailrefuse a detail whoseTouches:list touch-predictions cannot read, andrank_todo.py --checkfails on each item holding one, so rule-hook refuses a commit of such a plan: after updating, run~/.claude/bin/rank_todo.py --checkin each project and fix each list it names.- loop-claude hands each worker's claude a Bash output ceiling of 6,000 characters that saves a longer result to a file, rule-hook refuses a Read of a session transcript under ~/.claude/projects, and review-replay takes --bash-ceiling and --read-limit to test such a limit against archived review rounds.
- do-epic picks each epic item's repo, or that it is Claude's work or a human task, by repo-rule.md and a headless claude call, records the pick as a label on the issue and reads it back without a new call; where the rule leaves it unclear it returns a question for the human. The epic backends gain a label write.
- judge-replay --offline replays every archived verdict through a "?" rule, a decision table and a classifier trained on the archive, with no judge call, and counts the interrupts each misses.
- do-epic finds an epic repo's checkout and project config by the repo's name, and clones a missing checkout from the host and owner of the epic's other repos, asking the human where they differ or the clone fails.
- do-epic reads its machine-wide settings from ~/.claude-projects/do-epic/config.toml and its repo rule from repo-rule.md beside it, and refuses to start while either is missing or misspelt.
project-record savenow writes a goals file kept as a Jira epic's description, except a change to## Goalsor## Audience, which stays an edit in Jira.- Add do-epic's epic backend: one interface that reads a Jira epic's child issues and their sub-tasks, with labels, assignee, status and parent, and files new ones, met by a Jira backend and an in-memory fake that pass the same contract tests.
- Fix for an outside reviewer's comment on a PR now ends with a change to the setup that would have caught it, in claude-config first, then the principles and standards, then the project.
- larv-review reruns the pass that raised a 🟡 when the fix removes or loosens an assertion, changes an expected value, or skips, deletes or guards a test. Other 🟡 fixes still rerun no pass.
- Add
markdown-section <file> <fragment>, which prints the section of a markdown file under the heading the fragment picks, to the next heading of its level or a higher one. It fails, listing the headings, where several hold the fragment. - loop-claude and subagent-rung run an L 3 task one rung above the project's rung and an L 4 task two above it: on an Opus 5.5 project, Fable 5.2 at low and at medium.
- Add
larv-review round-title <pass>, which prints a review round commit's title prefix with the 🔴, 🟡 and misread counts taken from the round's report. rule-hook refuses a round commit whose counts differ from that report, where the report exists and can be counted; a report must head each finding### 🔴or### 🟡, optionally followed by[misread]. - Add
workflow-bench/handoff_bench.py, a bench of how a worker's step to a stronger model hands over the chunk, on six archived L 3 chunks. Sonnet 5.5 left five unfinished at its budget. On those, Opus 5.5 resuming Sonnet 5.5's session passed two and was partial on three, for a mean $0.68; a fresh session with a brief passed one and was partial on four, for $0.78. So a stepped worker still resumes its session. - todo-item edit --blocked-by sets the "is blocked by" links of a Jira issue the loop filed.
- A
Touches:list in the description of a Jira issue is read as one intodo.mdis, a path or name that holds a backtick included: the Jira description spells it in backticks with no padding spaces, and the prediction reader takes that spelling too. todo-item edit --detailandproject-record saveleave a Jira description or a Confluence page exactly as it is, with its block ids and spacing paragraphs, where the text saved is the text a read showed. An unedited save over a page a teammate saved since still refuses.- Add
compress-archives, which gzips each transcript in loop-claude's archive and each file in the review folders 30 days after it last changed, keeping all of them. The tools that read those folders read a gzipped file by its plain name. A new crontab line in the README's Install section runs it daily. - review-replay and judge-replay keep each run, with its prompt, claude's exit code and stream, and the report they print, in a
replays/<tool>-<arguments>-<UTC stamp>/folder of loop-claude's archive, so a replay that decided a rung can be checked and re-priced later; claude's json replies are now stream-json, whose last line is the reply. - loop-claude's archive keeps each judge run's prompt and json reply in a judge/ folder beside its chunk's transcripts, and names the run on a
Judge run:line of the outcome it produced; judge-replay replays a verdict on its archived prompt where the archive holds one. - A plan kept as a Jira epic takes no changelog bullet:
todo-item finishthere needs neither--changelognor--no-changelog, and refuses--changelog, since the issues' history is the changelog.
0.11.0
adf_codec.convertcan now convert ADF to markdown and back without losing a block'slocalIdor the empty paragraphs Jira uses for spacing, so a Jira or Confluence document read and saved back unedited comes back identical:markdown_to_adf_lossless,adf_to_markdown_losslessandadfs_to_markdown_lossless. No tool calls them yet.- A config whose
plannames a Jira epic must now setjira-score-formulaandjira-score-bar, and fails to load without them.todo-item addscores the item by them, refuses one under the bar unless it is exempt, and ranks the new issue among the issues the loop filed: questions first, then security findings, then by score. A person's issues keep their rank. todo-item editandmovework on a plan kept in a Jira epic. They change only an issue the loop filed, and never a link. Of an issue a person filed,editsets only the scores, and posts the new--commenton the issue to tell the team why; a plan in a file takes the flag and keeps no comment.- A release someone else cut while it still held plan items no longer stops the loop: those items count as the next release's,
chunk-preflighttells the worker to move them there, andloop-clauderoutes on them. Where the plan names no later release andtodo.mdnamed none since the cut, the loop still asks which release they belong to. project-record opennow writes the copy of a record kept outside a file under a folder of the worktree that ran it,~/.local/state/project-record/<key>/<worktree>/, so two chunks of one project no longer overwrite each other's unsaved edit. It also removes the folders of worktrees git no longer lists.chunk-pr mergemerges the chunks of one project on a machine one at a time, and--finish <ID>finishes each plan item in the chunk's turn, sotodo.mdandCHANGELOG.mdno longer conflict between open chunks. A pull request that waits for an approval leaves the queue while it waits, and merge stops where a reviewer's comment waits for an answer.loop-clauderuns each chunk in its own window of one tmux session per project,loop-<key>, and needs tmux 3.2 or later. Up to the config's new optionalparallel-chunkschunks run at once, 1 by default; a chunk starts beside the others only where its item'sTouches:prediction overlaps none of theirs.loop-claude <task>starts the windows and attaches to the session, and as a chunk finishes, its loop starts the next. A window whose chunk waits for you ends its name in?and rings the bell, and the question's DM names the window. A stopped chunk keeps its window and its items until you runloop-claude <task>again. A chunk's claude session is named after its window, asA <key> loop-claude item-372. A commit in the config's folder now takes only the file it changed, asgit commit -m <title> -- <file>. To upgrade, finish or stop every running loop-claude beforedeploy-releasemoves~/.claudeto this release: a loop that reloads into it starts its project's windows afresh, and leaves its chunk's open claude session in the session picker.todo-item finishfinishes an item of a plan kept in a Jira epic: it moves the item's issue by the workflow transition, and to the status, that the config's new optional settingsjira-finish-transitionandjira-finish-statusname, both as Jira shows them. It refuses a transition that leads to another status, or to one Jira doesn't count as done, and fails where the config sets neither.- Reviewers and loop-claude's judge read the review standards from the folder a project's config sets as
standards, in place of~/.claude/skills/larv-review/standards/. The setting is required. To upgrade, addstandards = "~/.claude/skills/larv-review/standards"to every config under~/.claude-projects/right afterdeploy-releasemoves~/.claudeto this release, and not before. - A project's config may keep each of its five records on a Confluence Cloud page: set, for example,
decisions = "confluence:https://<site>/wiki/spaces/<space>/pages/<page ID>", with the credentials in the config'senv-file.decisionsandcomprehension-historymay name a page only whereplannames a Jira epic. The loop reads and writes the page as markdown, so a save replaces a mention or a macro on it with plain text. It never overwrites a teammate's edit: where someone saved the page since the loop read it,project-record saverefuses and the loop asks you. todo-item addfiles an item into a plan kept in a Jira epic: a Task under the epic, under the project's Fix Version for the release, labelledsecurityfor a security finding and linked to each item that blocks it. Editing an issue still happens in Jira.- An item of the next release may predict the files and parts it will touch, under a
Touches:line in its detail.chunk-preflightthen names the items that may start chunks at once, and the newtouch-predictions recordkeeps each prediction beside what the merged chunk touched, in the record a project's config places withtouch-predictions. - CLAUDE.md, the todo-items rule, and loop-claude's worker and judge prompts and
--helpdefine the plan as a todo.md or a Jira epic, and say plan where todo.md was false for a Jira plan. - Reviewers without a shell read the plan from a listing that larv-review writes into the review folder, whichever store holds it.
- A project's config may set
tooling-on-host = true, so the loop runs a legacy project's language runtime, package manager, tests and task runner directly on the host. - A project's config may set
readability-floorto a number from 1 to 10: the comprehension score under which code health is very important. It is 7.0 where left out. - A project whose plan is a Jira epic can keep its goals and audience in an epic's description too: set
goals-and-audience = "jira:https://<site>/browse/<KEY>". The loop only reads it, andproject-record open goals-and-audienceprints a file holding its text. - A project with a Jira plan can name each chunk's branch, worktree, commits and pull request by the issue key, as in
ABC-123andABC-123 - …. The README shows the three templates to set. - A read of a plan in a Jira epic converts every issue description in one
adf_codeccontainer run, however many issues the epic holds. The codec builds its image inside one of the machine's heavy slots thatrun-heavyshares, so sessions reading at once build it once. - A project config may name its plan as
jira:https://<site>/browse/<KEY>: the plan is then read from the open child issues of that Jira Cloud epic, in backlog order, with the credentials in the config'senv-file. Such a plan is only read so far: file, edit and finish its issues in Jira. - A new
adf_codecpackage converts markdown to ADF, the rich text of Jira Cloud and Confluence, and back with@larvit/adf-codec0.3.1. It runs in a pinned Node container with a memory limit and no network, and returns adf-codec's error codes as aFailure. No tool calls it yet. - The new
todo-item list [--release <version>]prints the plan's items in the plan's order,todo-item edit <ID>sets an item's cells or detail, andtodo-item move <ID> --release <version>moves it to another release; each change ranks the plan. Agents now read and change the plan's items only withtodo-item, and the tools read the plan as it stands through one store,bin/plan_store, so a later backend can keep a plan outsidetodo.md.todo-item list --releasewith a bad version exits 2, andfinish <ID> --no-changelogalso drops an item no chunk built. - A project's config may name the language its prose is written in (
language) and templates for its commit titles, pull request titles and branch names (commit-title,pull-request-title,branch), in which{id}stands for the plan item's ID and{summary}for the one-line summary. The tools and the prose reviewer follow them. On a branch that fits thebranchtemplate, rule-hook's newcommit-titlerule refuses a commit title that doesn't fit, andchunk-prsuch a pull request title. While a project's config holds a fault, rule-hook refuses every commit there. chunk-pr mergewaits for a human's approval of the pull request where the project's config setswait-for-approval = true: it merges once GitHub reports the pull request approved, and gives up after 90 minutes. It reads approvals on GitHub only. Set it for a client whose pull requests need another person's approval.- The technical principles ask for code in files and folders before
// --- name ---banner comments. They also ask for an entry point a newcomer finds at once: the root holds it, the README and the files a tool reads only from there. - In a client project, the loop reads the team's own
CLAUDE.mdandAGENTS.mdand proposes each change that aligns them with this setup in a pull request of its own. Where the team declines or doesn't answer, the loop follows the team's rule unless it breaks a project goal, and records the conflict as a decision in thedecisionsrecord. - The new
project-record open <record>prints the file in which an agent reads and edits one of a project's five records (decisions,score-anchors,comprehension-history,reading-costandchangelog), andproject-record save <record>stores the edit. Every tool now reads and writes a record the same one way, so that a later release can keep a record outside files. No config needs a change. loop-inboxis gone. loop-claude now asks its questions only on its own terminal. A line typed there answers a question, and/talkopens the worker's session. The DM still tells you a loop waits. To upgrade, quit anyloop-inboxstill open and remove your~/.local/bin/loop-inboxlink.- rule-hook's
run-heavyrule also refuses a heavy command run throughuv run,poetry run,sudoordoasoutsiderun-heavy, such asuv run mutmut runorsudo docker build. Run it as~/.claude/bin/run-heavy uv run mutmut run. - rule-hook refuses a Read or a Grep of
~/.claude/.envor of theenv-fileany project's config names, and a Bash command that names either or searches a folder holding either withag,grep -rorrg, unless the tool skips the file as hidden or ignored, so that a worker doesn't put a credential in its transcript in passing. A command that hides the path, such as behind a glob or a variable, still goes through. - A project's config names the service for loop-claude's DMs:
notifier = "mattermost"or"slack", with the bot's token and the recipient in theenv-file. To upgrade, move the Mattermost keys from~/.claude/.envinto a file outside the checkout and the config's folder, such as~/.claude-projects/<key>.env, name it asenv-fileand addnotifier = "mattermost". A project with nonotifiergets no DM, and~/.claude/.envis no longer read. A failure names each missing key and holds no token. mattermost-dmis nownotify, which sends through the project'snotifier;notify --helpnames the keys.
0.10.1
- The routing ladder is now a file,
bin/model_routing/routing-ladder.json, and a project may run on a ladder of its own: arouting-ladder.jsonin its config's folder,~/.claude-projects/<key>/, replaces the shipped ladder whole for that project, and loop-claude says so as each cycle starts. loop-claude,subagent-rungand rule-hook read the project's ladder; the routing figures,judge-replayandreview-replayread the shipped one.subagent-rungnow reads the config of the checkout it runs in, and exits 1 where that config or the ladder holds a fault; loop-claude stops on a faulty ladder as it does on a faulty config.loop-claude --helpshows the file's shape, and README → Install → "Set up a project" says when to write one.
0.10.0
- The loop commits each change it makes to a file in the config's folder, such as a plan kept there, in that folder's git repo, titled as it titles its commits in the checkout. rule-hook ranks the plan on such a commit; before, it refused the commit.
- Every tool, prompt, rule and skill reads and writes the plan,
AGENTS.md, the records and the changelog at the paths the project's config names. A plan outside the checkout is read as it stands; the tools that need a file's commits say what they leave undone for it, and the loop goes on. - loop-claude,
rank_todo.py,todo-itemand rule-hook'stodo.mdchecks now fail in a checkout no config names: write a config for each project, withgoals-and-audience = "checkout:README.md"where its goals stay in its README. They read the goals and audience from the file that setting names, in place ofREADME.md.larv-review reviewer-headernames it on aGoals and audience:line, and the reviewers read it from there. A client's project can keep the file, namedgoals.md, in its config's folder, and void code health there as a README can. - Reviewers read the technical principles from the folder a project's config sets as
principles, in place of~/.claude/principles/.larv-review reviewer-headernames the folder on aTechnical principles:line and fails where no config sets it, or the folder is missing or empty. Write a config for each project before its next review; a project that keeps today's principles setsprinciples = "~/.claude/principles". - A project can now have a config,
~/.claude-projects/<key>/config.toml, that names its checkout and the path of every file the loop keeps for it.project-configprints those paths, and fails naming each setting a config leaves out. README → Install → "Set up a project" shows how to write one. Every project needs one, as the first bullet says. - larv-review takes an item as a floor item only where its tagline opens with
Reach the comprehension floor:. A tagline that quotes the floor elsewhere, such as in a decision title, no longer makes its chunk due a scoring run. Reword each open floor item's tagline in every project'stodo.mdto open with the phrase.
0.9.0
- larv-review skips stability round 2 where round 1 reported a 🔴 and every 🔴 and 🟡 asked only that a named mutant be killed or a named failing test pass, once the tests and the mutation command run clean on the fixes.
review-replaynow qualifies a rung whose share of a pass's archived findings is no more than 10 points below the mean of two replays on the project's rung, over at least 8 rounds, where it misses no 🔴 that both found. It used to demand every finding the project's rung found again, which the project's rung itself failed. It tries the project's model at each lower effort first, then the ladder below. Its run on the prose pass of Opus 5.5 projects qualified no rung: Opus 5.5 at low effort found 49% against a bar of 66%.- loop-claude records beside each verdict, interrupt and quoted answer the claude-config release and commit that ran it, the tokens the worker, each subagent and the judge spent, by model and kind, with the list prices in force, and any typed answer of yours the judge quotes as reversing a choice the worker took on its own recommendation;
score-outcomescounts those reversals per finished chunk. larv-review prepare-scoringmakes a scoring run's worktree and writes each seat's prompt;record-scoringremoves both once it has recorded the run.deploy-releasemoves a checkout whosesettings.jsondiffers from the release only by a/modelpick or the key order Claude Code writes, and then says to pick the model again.chunk-pr mergewaits for the pull request's checks itself, allowing a minute for them to report, and no longer takes--gate-passed.wait-for <file> [<pattern>]waits for a line in a background job's log or report.chunk-pr syncmerges origin's default branch into the chunk's branch, unless the branch already holds it, then runs the rank check ontodo.md.chunk-pr ready <title>sets the pull request's final title as it marks the pull request ready.bin/run-testsruns this repo's test suite as README.md → Test says, prints each failing test with its error and pytest's summary line, and saves the whole log to a file whose path it prints.command-patterns [<version>] --calls <file>saves each Bash call of the release's chunks as a JSON line, with its chunk, pattern, seconds, sizes and text.todo-item show <ID>prints an item's table row and detail fromtodo.md.- A reviewer under
agents/can start withoutCLAUDE.md:omitClaudeMd: truein its frontmatter drops the file, aSubagentStarthook hands it the "Shared goal", "Prose" and "Vocabulary" sections, andlarv-review reviewer-headernames the project's principles file.review-replay <pass> <model> --omit-claude-mdreplays each round three times unchanged and once withoutCLAUDE.md, and a reviewer passes where it missed no more findings without the file than an unchanged replay missed. Five of the six reviewers pass and start without it: principles-auditor, stability-reviewer, prose-reviewer, product-owner-reviewer and systems-architect. - Add
workflow-bench/advisor_bench.py, a bench of the advisor tool on six archived L 1 and L 2 chunks. Sonnet 5.5 alone passed all six, as Opus 5.5 at medium did, for 41% less, and its advisor ran in one of six runs, so workers stay without it. - loop-claude's judge on an Opus 5.5 project now runs on Opus 5.5 at xhigh in every chunk, never at medium: in replays medium sometimes closed a chunk whose worker had asked a question the README or records answer, where xhigh quoted the answer. The judge never runs on Fable 5.2 either, since each Fable 5.2 rung replayed missed an interrupt.
judge-replaynow also replays each rung above the project's that a review climbs to, and reports what each misses.
0.8.0
- The routing ladder now tops out at Fable 5.2, ordered by the Artificial Analysis Intelligence Index read 2026-11-11: Sonnet 5.5 at high, Opus 5.5 at medium, Fable 5.2 at low and medium, Opus 5.5 at xhigh, Fable 5.2 at high and max. On an Opus 5.5 project, L 4 workers, E + I 5 reviews and a worker's first escalation now run on Fable 5.2 at low, where they ran on Opus 5.5 at high; E + I 6 reviews on Fable 5.2 at medium, where they ran on Opus 5.5 at xhigh; E + I 7 on Opus 5.5 at xhigh, where they ran on Opus 5.5 at max; and E + I 8 on Fable 5.2 at high, where they ran on Fable 5.1 at max. On a Sonnet 5.5 project, E + I 6, 7 and 8 reviews now run on Fable 5.2 at low, Fable 5.2 at medium and Opus 5.5 at xhigh, where they ran on Opus 5.5 at high, xhigh and max. The judge climbs with the reviews. A Fable 5.2 project starts on Fable 5.2 at low. Update
~/.claudewhile no loop is mid-chunk: a chunk that stepped up to Opus 5.5 at high or max, or Fable 5.1 at max, finds its rung gone and restarts on its item's rung. - loop-claude now sends you a Mattermost DM from a bot for each question it asks, each release ready to cut, each routing call and each stop but Ctrl-C, where
~/.claude/.envnames the server, the bot's token and your username.bin/mattermost-dmsends one by hand;mattermost-dm --helpnames the keys. A DM that fails is one line on loop-claude's terminal, and the loop goes on. - larv-review's worker now runs the project's tests and static analysis, and checks the docs for each name its change touches, before each stability round, and hands stability-reviewer the commit that passed; the reviewer doesn't run them again on it.
- stability-reviewer, product-owner-reviewer and systems-architect have one-line descriptions, which shrinks the agent listing every session carries.
mutate-changesmutation-tests the lines a branch changes, running cargo-mutants, Infection, mutmut or Stryker by each file's language, and prints each mutant that no test kills. Where a project's README documents no mutation command of its own, larv-review now runs it before each stability round and hands stability-reviewer the mutants that survive.- loop-claude now asks each worker to name the items its chunk takes on one line, as in
Chunk items: 12 (L 3, E + I 5), 14 (L 2, E + I 4), and scores them fromtodo.mdon the default branch. That line, not the judge, now sets the items loop-inbox lists, and how far an item beyond the one the chunk was routed on lifts the worker, its reviewers and the judge. The judge still reports escalations and whether a release is ready to cut. ~/.claudeholds noAGENTS.mdany more, so each session in your projects starts about 3,600 tokens smaller, and a session in~/code/claude-configloads itsCLAUDE.mdonce instead of twice.- A project's
AGENTS.mdmay group decision titles into project principles, and each new decision is checked against them: a principle covers it, it breaks one, or it suggests a new one for you to approve. - The prose reviewer now holds prose to the negation rule: write
doesn't cost anything, nevercosts nothing, after any verb or its preposition. rule-hooknow checks files atgit commit: each file that differs from HEAD or is untracked and not ignored, even one the commit leaves out. It holds each toaction-pin,image-pin,ignorefile-sortedandno-ai-attribution, so a file a Bash command wrote is checked as an Edit or Write is. A# rule-overrideline in the file or the command overrides a breach.chunk-pr mergenow refuses while a scoring run the plan calls is unrecorded on the branch, andlarv-review needs-scoring-runcalls one after a release is cut with none.
0.7.0
- README's test, CI and mutation-test commands now have their own section, README → Test.
rule-hook overridesnow lists the chunk's overrides when a file or folder shares the branch's name. It used to exit saying it could not read the reflog.chunk-pr cleanremoves a merged chunk's worktree and local branch and fast-forwards the main checkout. It leaves a main checkout with uncommitted files, another branch or commits of its own as it was, and says why.review-replaynow replays each round at the commit with the newest author time at or before the round's time, and takes the clone's base the same way by the time the chunk began. It took the first such commit in log order, so a commit authored early but merged late, such as a dependency bump, could win over the commits the round reviewed.- The shared goal every project pursues, code health, now asks that code stay easy to read, change safely and debug, tomorrow and after seven years of development.
rank_todo.pynow lets an item that adds a test, a gate leg or a probe name the maintain goal it guards, by how much more confident the project becomes that the goal holds, 1 to 10. Each point is worth 0.5.chunk-preflightnow quotes the detail of each item that may join the chunk, so a worker no longer openstodo.mdto read it.command-patterns [<version>]prints a table of the shell command patterns a release's chunks ran.deploy-release --cutreports each step as it finishes, waits for the checksmain's protection requires and names them, deletes the merged release branch, and ends on one line saying the release is cut.- CI runs the test suite on every pull request, and
mainmerges nothing until it passes. larv-review reviewer-header <pass> [--rerun]writes the branch diff and the places into the chunk's review folder and prints the header of a reviewer's prompt: the pass, its next round, the PR, the worktree, the branch, the merge base of HEAD and the default branch, and the paths of the report, the diff and the places.chunk-pr open|ready|mergeopens a chunk's pull request as a draft, marks it ready and merges it, withghorteaas the remote needs. It merges only with--gate-passed, by the first merge method the repository allows.larv-reviewandCLAUDE.mdnow tell workers to use it.score-outcomesnow gives, where most of the chunks it counts for L hold no 🔴, the share of chunks with a 🔴 at each L in place of L's rank correlation by 🔴 findings.todo-item addnow files an item intodo.mdwith one command. It takesNext IDas the item's ID, raisesNext ID, writes the row and the detail it reads from stdin, and ranks the file.todo-item finish <ID>now removes a finished item's row and detail fromtodo.md. With--changelog <bullet>, it also adds that bullet first underCHANGELOG.md→## Unreleased. Where aCHANGELOG.mdexists, it refuses to run without--changelog <bullet>or--no-changelog, so no bullet is left out by mistake.- A worker whose review rules its work below standard now fixes it on its own rung where the fix changes only prose, a comment or docstring included. It hands the fix to a higher rung only where code, config or tests change.
loop-claude's judge now sends a question you answered earlier in the chunk back to the worker, quoting your answer, unless the question ends with the words of your answer that leave it open. You are asked only about what your answer left open.score-outcomesnow shows, beside what each finished item's chunk measured, the size of the files and folders its tagline or detail names in backticks: how many files, and how many lines, as they stood before its chunk.workflow-bench/bench.pynow prints a failed run, such as a failed clone, as a<run>: FAILED: …line beside the other runs' results, in place of stopping at the first failure.- A scoring run under the comprehension floor of 7.0 now leaves a plan item meant to reach it.
larv-review record-scoringfollows itsFloor:line with aNext:line. It says to file one ambitious refactor aimed at the lowest dimension, or to refresh the onetodo.mdalready holds. The item's tagline holdscomprehension floor, so its own chunk runs a scoring run. It goes into the release after the chunk's, so the floor doesn't hold up any release (larv-review §3 → "Floor item"). An item already intodo.mdwhose tagline holds those words counts as the open one: drop or reword it if it isn't such a refactor. loop-claudenow interrupts you less. A worker takes its own recommendation on a choice no rule reserves for you, and records it, and the judge answers an ask that carries a recommendation by quoting the rule that says so. You are still asked about a goal, a release's planned items and its cut, a change to the routing ladder, and whatever another rule asks your approval for;CLAUDE.md→ "Working loop", "Ask, don't guess" lists them.- This setup's own plan now ranks items by
Score = 100 * V / (2**S + 32), up from 8: F, a chunk's fixed cost, is 32, about one size-5 change, fitted to ten finished chunks' tokens, so small items rank lower against large ones.docs/decisions.mdholds the fit. loop-claudenow keeps the cycle it last measured the routing figures at, and each routing call it raised, inrouting-state.jsonat the archive's root, and reads them back from there in place ofrouting-figures.mdandrouting-calls-raised.md. The two markdown files hold what they held before. From them, loop-claude now reads only aResetline inrouting-calls-raised.md, which still resets the figures. The first loop to close a cycle after the upgrade measures the figures at once. If the figures still make a call raised since the latest reset, it puts that call to you once more.loop-claudeand the routing figures no longer read aWorker:line written as a sentence, as versions before 0.4.0 archived. A rerun routes a chunk whose archive still ends in one afresh, and the figures leave it out of the routed chunks and charge its dollars to a row named by the sentence.score-outcomesno longer credits a chunk's measurements to an item the chunk removed fromtodo.mdwithout building it. Remove such an item in a commit whose title opensDrop item 69: <why>, orDrop items 69, 70 and 71: <why>, andscore-outcomesleaves it out. Items dropped before this release still count as shipped.- rule-hook's
todo-rank-checknow checks a branch of this setup's repo with that branch's ownbin/rank_todo.py, so a branch that changestodo.md's shape commits without an override. Any other repo is still checked with~/.claude's.
0.6.0
deploy-release --cut, run in~/code/claude-config, now cuts a release. Once the next release holds no item intodo.mdand its release review has landed, it renames## UnreleasedinCHANGELOG.mdto the version and merges that through a pull request: it opens the pull request, waits for its checks and merges it fast-forward only. Then it tags the merged commit, pushes the tag and moves~/.claudeto it. Where a step fails it stops with git's or the forge's reason, and a rerun continues. Nobody can push tomainon the remote any more, so the old manual steps under README → Release no longer work. Cut 0.6.0 itself from the clone,~/code/claude-config/bin/deploy-release --cut, since~/.claudestill holds 0.5.0.- The routing figures now count what
loop-claude's judge costs.loop-claudearchives each judge run's cost, from claude's reply, in aJudge cost:line beside the verdict or rejection, androuting-figures.mdadds it to its dollars by project, rung and tool, and under the subagent typejudge. Before, the judge's cost was left out. Chunks archived before this change, and a judge run that failed, add none. - In a repo with no tag,
chunk-preflightnow counts the newest version under a datedCHANGELOG.mdheading, such as## 0.0.1 - 2026-10-03, as the last cut. A later release intodo.mdreads as next, the unreleased commits are those after the commit that added that heading, and aRelease review ofcommit counts only for a release after it. A heading without a date doesn't count, and a tag always wins. Before, such a repo was sent to review a release it had already cut. rule-hookno longer hangs, or reads without end, on an Edit, MultiEdit or Write whosefile_pathis a FIFO or a device: it reads only a regular file.- A
loop-inboxask file now stores when the loop asked as an ISO UTC datetime, such as2026-11-04T09:30:00Z, in place of seconds since the epoch. Restart anyloop-inboxrunning when you deploy: one started before doesn't list the new asks. Aloop-clauderunning then reloads itself at its next cycle, andloop-inboxdoesn't list a question it asks before that; answer such a question on the loop's terminal. - Each chunk's first worker prompt now holds a reading rule: never read more than 80 lines of a file at once, nor take a tool output over 3,000 characters into your context. Where the 20 chunks after it take more review rounds, unfinished verdicts, findings, misread findings, dollars or hours than the 20 before, a later release drops it.
rule-hook'sround-capnow refuses a round commit whose title names no larv-review pass, such asAnswer architectur round 1:. Before, a misspelled pass got a count of its own, so its rounds never reached the cap.- A routing call from
loop-claude's figures now opens claude in the setup's development clone,~/code/claude-config, not in~/.claude. Recording the answer there no longer leaves~/.claudewith changes that stopdeploy-releasefrom moving it. - Where the default branch's tags cannot be read,
chunk-preflightnow says so, with git's reason, and that it cannot tell which release is next, andloop-clauderoutes the chunk on the project's rung. Before, both read such a branch as one with nothing cut, sochunk-preflightcould report an empty plan where a release review was due. - A branch that changes
workflow-bench/run-prompt.mdorcompare-prompt.mdnow counts as changing config, as a skill does: its reviewers run on the rung its items pick, not on the project's rung. deploy-releasenow stops with git's own error where git cannot refresh the checkout's index. Before, it went on and could refuse with a wrong report of uncommitted changes.
0.5.0
- A bare run of
chunk-preflightnow only prints the facts. It no longer adds the worktree<checkout>-item-<ID>and the branchitem-<ID>, or runsreading-cost,larv-review placesand its other checks in that worktree.chunk-preflight --worktreedoes all that, andloop-claudenow passes it. Before, every run that found an item added the worktree and branch, and you had to remove them after a run made only to read the facts.
0.4.1
- A release review now fixes the findings of its architecture and principles passes in the release it reviews. Before, it filed each one in
todo.md, so the release held the drift the review had found. It files only three kinds of finding, each under the release being reviewed: one whose fix needs a human answer, markedquestion; one whose fix adds a feature; and one whose fix the five rounds cannot finish. Until each is done, the release isn't ready to cut. - In a repo with no tag yet,
chunk-preflightnow calls a release finished oncetodo.mdfiles no item under it: its release review is due, and no later release's item is taken. Before, it lost sight of such a release. - In a run
loop-claudestarted,rule-hooknow refuses a/security-reviewor/claude-securitySkill call that the worker makes in its own context on a rung below the project's. It also refuses one from any subagent whose prompt doesn't open withYou are the security pass for this chunk., since that subagent's rung is unchecked. The refusal says to invoke the skill from a subagent on the project's rung, its prompt opening with that sentence. Before, only an Agent call that launched the security pass was held to that rung. loop-claudeandloop-inboxno longer write~/.claude.json. Each claude they open on a terminal, for/talk, a release ready to cut or a routing call, now hasCLAUDE_CODE_SANDBOXED=1set, so Claude Code skips its trust dialog. Before, they marked the checkout and each worktree trusted in that file, and a write Claude Code made at the same moment could be lost. Claude Code doesn't document the variable: where a version drops it, the trust dialog comes back.
0.4.0
-
~/.claudenow holds only a release, and this repo is developed in a clone,~/code/claude-config. A new tool,deploy-release, moves~/.claudeto the newestv*tag and printsCHANGELOG.md's section for each version it moved past. It refuses while a tracked file there has an uncommitted change the new tag doesn't hold, such as a hook Claude Code wrote intosettings.json, or where the move would drop commits no release holds; a model picked with/modelis no such change. To switch a machine over:- Stop any
loop-clauderunning in~/.claude, and finish or move its open chunk. - Clone this repo to
~/code/claude-config, and rungit config filter.settings.clean bin/settings_filter.pythere. - Run
~/code/claude-config/bin/deploy-release. Where~/.claudeis on a branch, it refuses until a release holds that branch's commits. - Run loop-claude for this repo from
~/code/claude-config. It asks for the project's model, since the project is new to it.
- Stop any
-
larv-review's architecture and principles passes now run only in a new release review: the chunk that runs once a release holds no item and changes are unreleased, before the release is ready to cut. Each reads the whole project, may refactor boldly and takes up to five rounds; their fixes take the stability, security, overrides and prose passes, two rounds each. No other chunk runs either pass, so a chunk that changes code no longer waits on the principles audit. Between releases, the product-owner pass now also reviews changes to routes, request and response shapes, events, webhooks, published file formats, CLI flags and exit codes, which the architecture trigger used to cover. The comprehension check's paired ruling moves to the release review too.
chunk-preflightnow reports a release review due where it reported a release ready to cut, until a commit titledRelease review of <release>follows the newestv*tag on the default branch. Open the review's branch with that commit.- rule-hook's
round-capandlarv-review round-countallow the architecture and principles passes five rounds.
-
Haiku 5.5 is off the routing ladder, which now runs from Sonnet 5.5 at high to Fable 5.1 at max. A Sonnet 5.5 project's L 1 and L 2 workers now run on Sonnet 5.5 at high, where they ran on Haiku 5.5 at max: such a chunk took more than two hours and 3.1 million output tokens on a README change. A review replay can now lower a pass only to Sonnet 5.5 at high.
subagent-rung,review-replayandjudge-replaytreat Haiku 5.5 as a model off the ladder. -
larv-review runs fewer reviews on changes that hold no code:
- A fix for a 🟡 no longer reruns the pass that found it. Only a 🔴 fix does, with each pass whose re-entry row the fix meets.
- A comment counts as prose in every file, config included, so a comment in a workflow or compose file fires only the prose pass. Markdown an agent follows counts as config:
CLAUDE.md,AGENTS.md, and files underagents/,principles/,rules/orskills/. - A branch that changes only other Markdown, such as
README.md,docs/andtodo.md, runs the prose pass, and the product-owner pass where an outside reader lands on the change. Its reviewers run on the project's rung, whatever its items' E + I. loop-claude's prompt says so, and rule-hook'sreviewer-rungallows it. - A
todo.mdrow or detail that a chunk files from a finding, re-scores or moves between releases is no longer reviewed. The chunk that ships the item reads it.
-
New tool
loop-inboxlists the interrupts of every loop-claude on the machine, oldest first, in one terminal. Each entry shows the loop's checkout, how long it has waited and the question's first lines. Pick one to answer the question as on the loop's terminal, except that Enter alone goes back;/talkopens claude in loop-inbox's terminal. Of a pasted answer, only the first line is sent, and the rest is dropped. The loop takes the first answer, from its terminal or loop-inbox, so it works as before with no loop-inbox running. A loop that ends drops off the list, even one killed outright. A loop whose claude is already open, such as for a release ready to cut or the routing calls, is listed but answered in that claude. A loop asking for its project's model, as on a project's first run, asks on its own terminal only. Below the questions, loop-inbox lists every running loop, with the ID and tagline of eachtodo.mditem its chunk takes. Link it ontoPATHas README → Install shows. -
Ctrl-C in a claude that
loop-claudeopens on its terminal, for/talk, a release ready to cut or the routing calls, now reaches only that claude. Before, it also stoppedloop-claude, which closed that claude a quarter second later. -
reading-costnow lists the files a chunk read in the worktreechunk-preflightmade,<checkout>-item-<ID>. It listed none, since no transcript command names that worktree. -
larv-review ruling-basenow finds the last measured commit when run in a subfolder of a checkout. Before, it found no change to the comprehension history there and fell back to the merge base. -
score-outcomesnow counts each finished chunk's later fixes: the later chunks on the default branch that fixed code it shipped, each a defect that review let through. A later chunk counts where a change of it rewrites or removes lines thatgit blametraces to the earlier chunk: its whole change where it ships atodo.mditem markeddefectorsecurity, or one of its round commits whose title counts both a 🔴 and a finding a reviewer marked[misread]. Each finished item shows the count beside its guessed scores, and a new list, after the misread findings, names the chunks that fixed each one, newest first.routing-figures.mdshows the mean per rung, over the chunks whose later fixes are known, in a new column of the routed-chunks table. To find them, loop-claude now reads each archived project's checkout, and the figures name each project whose default branch it could not read. -
loop-claudenow opens every message it prints with the machine's local time, as in2026-10-28 11:46:01, so you can see when each happened, such as how long a question has waited. A message of several lines, such as a question, carries the time on its first line only. Theretrying at …time of a usage-limit wait now also shows seconds, and no longer names the zone. -
larv-review now gives each review pass at most two rounds per chunk, where it gave three and then asked for more, and no longer asks: the fixes answering a pass's second round merge once the gate passes. rule-hook's new
round-caprule refuses a round commit that would take a pass past round 2, such asAnswer stability round 3: …, and takes no override. It counts the pass's earlier round commits on the branch, so a third commit titled round 2 is refused too.larv-review round-countmarks a pass at two rounds as at the cap. -
rule-hook has a new rule,
repeat-read, and now runs before each Read call too. It blocks a Read, or a Bashcat,headorsed -n '<A>,<B>p'of one file, when every line it asks for is already in the agent's context, and the block names those lines. The rule takes no override.- A line is in context when an earlier read's result in the agent's own transcript showed it since the last compaction, as the file holds it now. A subagent is judged on its own transcript, not its session's.
- A read goes through when it asks for a line no earlier read showed, or one that changed since. A Bash output that Claude Code cut short shows no lines.
- A Read also goes through until the agent has read the file with Read or written it with Edit, MultiEdit or Write, and again once the file changed after that. Edit, MultiEdit and Write refuse the file until then, and a Bash read does not count.
- Where the context lacks lines the transcript shows, as after Claude Code cleared old tool results,
grep -n '' <file> | sed -n '<A>,<B>p'reads them.
-
Install the latest stable Python, today 3.14, as
python3: the tools and their tests no longer support 3.11 to 3.13. A full test run now takes about 29 s, where it took about 3.3 minutes. It runs once, on that Python, in four pytest-xdist workers, where it used to rerun the whole suite on 3.11. -
routing-figures.mdnow reports dollars by project, subagent type, rung and tool, in place of tokens. Cache reads are included; the tokens left them out, though they were about a quarter of the cost. The dollars are what each worker transcript's lastcost-stateentry records for each model, split across the messages of the worker and its subagents in proportion to their cost at list prices. The judge's runs are not counted, since the archive doesn't hold them. -
larv-review's principles pass now launches one auditor per round, which checks the README's goals, code health and every principles file that applies, so it reads the project once per round. It used to launch one auditor for the goals with code health and one for each principles file, each reading the whole project. Its report is
principles-round-<n>.md, like every other pass's. -
A session running larv-review now enters the chunk's worktree with
EnterWorktreebefore the first review pass, so/security-reviewand the full scan read the branch's diff. Run from the checkout root, they used to find it empty. -
loop-claudenow stops with exit 2 when the judge rules one chunk unfinished 6 cycles running, so a worker and a judge that disagree can no longer cycle unattended without end. Rerunning resumes the chunk and gives it 6 more cycles. -
larv-review now launches a round's reviewers in up to three waves, each wave's reviewers in one message, in place of one reviewer at a time: first the architect, then the principles auditor with the security and overrides passes, then the stability, product-owner and prose passes. Each wave now lasts as long as its slowest reviewer, where a round used to last as long as all its reviewers one after another.
-
loop-claude's worker, and every subagent it launches, now run with a 200k auto-compact window, handed as
CLAUDE_CODE_AUTO_COMPACT_WINDOW: Claude Code compacts their context at about 170k tokens, where it used to let it grow to about 967k. loop-claude's judge no longer reads a compaction summary as words you typed.CLAUDE.mdhas a new section, "Compact instructions", saying what a summary keeps. -
On Linux,
run-heavynow caps the memory of a container its command makes withdocker runordocker create. A container that sets no limit gets a memory limit and a swap limit, both the slot's share: three quarters of the machine's memory, split across the heavy slots. A container that sets one of the two limits keeps it, and gets the other as large. This covers containers a project's own scripts start, which rule-hook can't see. Adocker composeservice, and a docker named by its full path, get no cap. rule-hook'sdocker-run-memorynow lets adocker rununder run-heavy pass. -
rule-hook has a new rule,
docker-run-memory. It blocks adocker runordocker createthat lacks a memory limit or a swap limit, such as--memory 4g --memory-swap 4g, sized to what the work needs.--memory-swap -1, unlimited swap, counts as none.CLAUDE.mdasks for the same limits on a container a script or a compose file starts, which rule-hook can't see. rule-hook'srun-heavyrule also now reads docker's--tlscacert,--tlscert,--tlskeyand buildx's--builderas options that take a value, and readsdocker container runas a run:docker --tlscacert ca.pem build .was not blocked outside run-heavy before. -
Reviewers now mark a 🔴 or 🟡
[misread]where it arose because the implementer misread code that had already shipped. A round's commit title now counts the marked findings, as inAnswer stability round 1: 1 🔴, 2 🟡 (1 misread); …, and rule-hook'sround-title-countsblocks a round title without that count.score-outcomesshows the count on each finished item, and lists it after the medians for each chunk whose round titles carry it, newest first. A chunk whose round titles predate this change reads as unknown. -
Sessions running at once no longer starve the machine. A new tool,
run-heavy <command>, runs a heavy command, such as a full gate, mutation tests, an e2e run or adocker build, once it holds one of the machine's heavy slots: one per 4 CPUs, shared by every session.CLAUDE.mdhas every session run its heavy commands under it, and rule-hook blocks adocker buildor a mutation run outside it. loop-claude now waits to start a worker while less than a quarter of the machine's memory is available. -
larv-review's skill now says a commit answering the external auto-reviewer takes no
Answer <pass> roundtitle, and thatlarv-review round-countdoesn't list the auto-reviewer. A worker who followed the skill used to get a "not a pass" warning. -
loop-claude's first prompt for a chunk that no plan item routed now also names the rung on which the worker launches its reviews for an item it takes in, as the prompt after a step-up or an unfinished verdict already did.
-
loop-claude --helpnow describes routing in two short paragraphs for the person running the loop. The rules it used to repeat are now stated once, in the code that enforces them. -
loop-claude now archives the route on each
Worker:line as a JSON record, such as{"model": "claude-opus-5-5", "effort": "high", "item": 3, "likelihood": 4, "escape_and_impact": 5, "escalated_at": 12}, and reads it back field by field. The line used to be a sentence, such asclaude-opus-5-5 at high effort, routed by item 3's L of 4 and E + I of 5, which loop-claude parsed back word for word: rewording the sentence in the code would have made every archived line unreadable, and a rerun would have routed the open chunk afresh. A rerun and the routing figures still read the sentences archived since loop-claude routed on L. A rerun that finds aWorker:line it can't read now says so on stderr. The judge's reply now names the levels the worker took inhighest_likelihood_taken_inandhighest_escape_and_impact_taken_in, in place ofbundledandbundled_escape_and_impact. -
A chunk now takes every unblocked item of its release that fires the same review passes, whatever its purpose: one PR title no longer has to state what the items achieve together. An item with R above 5 ships alone.
chunk-preflightsays so for such an item, and never lists one as an item that may join another. -
A branch whose name is not UTF-8 now shows no branch in the status line, in place of a name with replacement characters.
-
A new technical principle, "About seven things per level", sets soft limits on what a reader takes in at once: the parameters and branches of a function, the methods of a class, the files and folders in a folder, the sections of a document and the components of a system. Aim for four or five of the things that act on each other, such as parameters. Things found by name, such as files named by locale, may run far past seven. Crossing a limit asks you to group the things or record why they stay. The systems-architect reviewer now reads its limits from this principle. It rates a unit that crosses a limit with no recorded reason a 🟡, where it used to be a 🔴, and no longer asks for the limits as merge-gate rules.
-
The comprehension panel's base worktree and a build probe's output now go in a folder under the chunk's review folder in
~/.local/state/larv-review/. Both used to go in a session scratchpad, which loop-claude's headless sessions don't have. -
rule-hook now reads
git > out commit -m xas one git commit, as the shell runs it. A redirect used to split a command in two, so such a commit escapedcommit-one-line,round-title-countsandtodo-rank-check. -
larv-review needs-scoring-runnow calls a scoring run for the releasechunk-preflightnames as next, not for the earliest release in the plan. It also counts a change as unreleased the waychunk-preflightdoes: an entry underCHANGELOG.md→## Unreleased, or, where there is no such section, a commit after the newestv*tag (any commit when there is none). Before, a chunk that moved the next release's last items to a later release without shipping them called a scoring run, whilechunk-preflightcalled that release unplanned. -
README → Install now says that every machine taking this checkout must be a sandbox with no direct access to a production environment, since
settings.jsonruns Claude Code in auto mode with the dangerous-mode prompt skipped. Before, it asked for a sandbox only forloop-claude.
0.3.0
- A task scored L 1 now routes its worker, or a delegated subagent such as a search, one rung below the project's rung, as L 2 does; it used to go two rungs below. On an Opus 5.5 project that is Sonnet 5.5 at high, not Haiku 5.5 at max: chunks started on Haiku 5.5 took more review rounds and unfinished verdicts.
- loop-claude's worker now starts with
ScheduleWakeupdisallowed. A worker that scheduled a wakeup keptclaude -prunning after its turn ended, so loop-claude neither ran the judge nor asked you, and the chunk stalled until someone killed the worker. - Every project's audience now includes the contributor, the person who reads the code to change it. A README doesn't list them; only its
**Void:** code healthline drops them. larv-review's comprehension check now measures how hard the project is for them to read. score-outcomesnow also measures projects that merge by rebase: each run of commits that share one commit time counts as a chunk. Adddocs/score-anchors.mdto those projects too. A chunk that was pushed or fast-forwarded may hold only part of its pull request, so the medians and rank correlations leave it out.settings.jsonno longer carries a model: each machine keeps the one you pick with/model. Git's clean filterbin/settings_filter.pydrops"model"and sorts the keys, so neither a pick nor Claude Code's key order can reach a commit. Update now starts withgit add settings.json: without it, Update'sgit checkout -fdrops the machine's model. On upgrade, on each machine:- Turn the filter on in
~/.claude:git config filter.settings.clean bin/settings_filter.py. - Pick a model with
/model. Until you do, Claude Code runs its default model; this repo setopusbefore.
- Turn the filter on in
- larv-review's "Re-entry" is now one table of which passes a fix reruns, and the pass table's triggers say only when a pass first runs. The rule is unchanged; a fix for a 🟢, a ❓ or a prose finding still reruns no pass.
0.2.0
- Every project now shares one achieve goal, code health: the code is easy to understand and change safely.
CLAUDE.md→ "Shared goal" states it, with its signal and counter-signal.rank_todo.pyranks it first among a project's achieve goals. A project's overall is the overall mean of the newest scoring run indocs/comprehension-history.md, averaged with every other run on its commit. While that overall is under 7.0, or no run has measured the project, code health weighs four times as much as it does at 7.0 or above. An item's Moves cell names it as incode health by 6. A README voids it with**Void:** code health, since <reason>.under## Goals, andrank_todo.pythen refuses an item that names it.larv-review record-scoringre-rankstodo.mdafter it appends a run, and exits 1 whererank_todo.pywould, keeping the run. Expect items that make code easier to read to rank higher in every project. On upgrade:- Move every machine to this release before any of them ranks a plan another machine shares: an older
rank_todo.pyscores it without code health and rejects acode healthcell. - Void code health in each project that opts out of the comprehension check, or
rank_todo.pyrefuses its plan. - Run
rank_todo.pyin each project that keeps code health. It re-scores every item, so until thenrank_todo.py --checkfails, and rule-hook holds the project's nexttodo.mdcommit. - In each project whose README restates code health as a goal of its own, file an item to drop that goal and point the Moves cells citing it at
code health. Dropping it renumbers the goals after it, so the same item repoints every Moves cell and decision citing them;rank_todo.pycannot tell a cell left pointing at the wrong goal.
- Move every machine to this release before any of them ranks a plan another machine shares: an older
stability-replay <model>is nowreview-replay <pass> <model>, and replays any pass an agent underagents/reviews, such asreview-replay prose claude-opus-5-5. It now tries every rung below the project's, down to the ladder's lowest. Its runs on the prose and stability passes of Opus 5.5 projects found no rung below the project's that finds every 🔴 and 🟡 the project's rung finds: Sonnet 5.5 at high missed 12 of 27 prose findings and 11 of 20 stability findings. So every pass stays where it runs. A rung a future run finds lowers only its pass, onceREPLAYEDinbin/model_routing/ladder.pynames it, and only where the chunk's E + I steps no review up and the worker runs no higher than the project's rung; there it may run below the worker's rung.chunk-preflightnames the release it finds finished and ready to cut, or to be planned first, wherever todo.md has named that release since the last cut.- Each reviewer under
agents/now writes its full report to a file that larv-review names in the reviewer's prompt, in a folder per chunk under~/.local/state/larv-review/. It returns only its verdict and one line per finding, so a review takes less of the worker's context. The worker reads a finding's full entry before it fixes or answers a 🔴 or 🟡. Each reviewer now holds Write.rule-hookrefuses a reviewer's Edit and MultiEdit, and any Write outside~/.local/state/larv-review/; no override waives this rule. Each chunk's folder stays after the merge, soreview-replaycan replay a round that reads an earlier round's report. It replays on a copy of the folder. loop-claudeasks an interrupt's question on its own terminal and resumes the worker headless with your one-line answer, so the loop no longer waits for you to leave a claude session. Type/talkinstead to open the worker's session in claude, as every interrupt did before, to read the diff or discuss first. A release ready to cut opens that session at once. Pressing Enter on an empty answer stops the loop, exit 2. Keys typed before the question shows are dropped, and a pasted answer keeps only its first line; type/talkfor a longer one. The judge counts that answer as yours, like one typed in claude: the chunk stays open until the answer is recorded, where a later chunk could need it.todo.mdmay mark a renamed release in a## Renamedsection, one line per rename, such as- 0.2.1 renamed to 0.3.0.chunk-preflightandloop-claudethen skip that release when they pick the next one, and larv-review's scoring-run trigger calls no run for it. Without the mark, a release named since the last tag whose items all moved to other releases reads as finished:chunk-preflightsays it is ready to cut and the loop stops for you, and the trigger calls a scoring run.rank_todo.pyfails on a## Renamedline of another shape, and on an item filed under a release it marks. Before you move a machine to this release, add the line to thetodo.mdof every project that renamed a release since its last tag, or its loop stops for that release's cut.- When a worker's run ends with a question and a request for a higher rung,
loop-claudenow steps the worker one rung up as the judge interrupts, or as it answers the question with a quote fromREADME.mdor another file it may quote. The judge must quote a passage showing that the escalation trigger the run cites fired. Before, the step was lost for an answered question, and the worker carried on from the answer on its old rung. The step has the same limits as the step on an unfinished verdict. An escalation trigger that fired before the worker's last step-up doesn't step it again, so one trigger buys one step. A trigger that fires after the step steps the worker again, in the same cycle or a later one. A chunk left open across the upgrade to this release starts with no step-up on record, so a trigger that already stepped its worker may step it once more. The archive's interrupt and quoted-answer outcomes now name the worker's rung. - A scoring run due because a release's items ran out costs four more seats: it is done twice on one head.
larv-review agreementcompares how often Mid A and the inherited architect vote alike in paired rulings with how often their overall scores move the same way between the two runs. After 10 such pairs it gives a verdict, and onAssumption fails:larv-review asks you whether to keep the paired ruling. workflow-bench/bench.pygives each run a fixed list of allowed tools. Before, it skipped every permission check. A run may launch agents, run/security-review, edit its clone (not the clone's.git/or.claude/) and its report, and read its clone and the copy of~/.claudeit benches. For git it gets one command,workflow-bench/review_git.py, and no baregit. The wrapper runslog,diff,show,status,ls-files,addandcommit -mon the run's clone, whatever the working directory. It allows only the options it lists for each, and refuses an argument that names a path outside the clone. git runs with no global or system config, hook, pager or editor. A run loads no settings or MCP servers from~/.claudeor from the case's clone, so their hooks and extra directories do not apply to it. Every other call is denied. Expect a benched review that needs another git command, or to run a project's code or tests, to say in its report that it could not.- Every goal in
README.md→ Goals is marked**Maintain:**, a state to hold, or**Achieve:**, a direction to pursue. Each achieve goal has a signal, a counter-signal and a one-line reason under it. A change that breaks a maintain goal is redesigned or dropped, whatever it scores:rules/todo-items.mdsays so, and larv-review's goal alignment step no longer merges such a PR.rules/goals-and-audience.mdstates the form for every project's README. Expect larv-review to stop a PR on a maintain goal where it asked you before. - Reshape every project's
todo.mdto the new shape below: until it is reshaped, that is the project's only work, as it is while README.md lacks Goals and Audience, andrank_todo.pysays so. First move every machine to this release: an older release rejects the new formula, so it fails on every reshapedtodo.md. Then mark the README's goals**Maintain:**or**Achieve:**, score each item's L, E and I, and set a bar on the new scale below the score of every item to keep, since the old bar would drop most items. Until then, an old-shapetodo.mdstill ranks by its own formula and weights. todo.mdranks items by value per cost: this setup's own plan usesScore = 100 * V / (2**S + 8), where 8 is a chunk's fixed cost, about one size-3 change, andrank_todo.py --helpshows it. A Moves column replaces A, G and Goals, naming each achieve goal an item moves and how far, such as1.1 by 8, 1.2 by 5. V sums each named goal's weight times its move.rank_todo.pyweighs each achieve goal 0.97 times the one above it in README.md, so a goal far down the list still counts almost as much as the first and the goal weights table goes. The weights sum to 1: 5 achieve goals weigh 0.212 down to 0.188, 15 weigh 0.082 down to 0.053. An item names the most specific goal it moves, never a goal beside its own sub-goal.rules/todo-items.mdandrank_todo.py --helpshow the new shape.- L, E and I replace C, and set R. L is the chance the change holds a defect, from 1 to 4; E the chance a defect escapes tests and review, from 1 to 3; I the damage it would do, from 1 to 5, counting every project and session that runs the change.
rules/todo-items.mddefines each level in words, andrank_todo.pywrites R as L + E + I − 2, at least 7 when I is 5 and at least 5 when I is 4. The table's score columns are| L | E | I | R | S |.score-outcomestakesL E I S, and reports how well L, E and I each order finished chunks by review rounds and 🔴 findings. loop-clauderoutes a chunk's worker on its item's L, from two rungs below the project's rung at L 1 to one above it at L 4. It routes the reviewers on the highest E + I among the chunk's items, counting each item the worker takes in: one rung above the project's for each point past 4, never below the worker's rung. It runs the judge of an Opus 5.5 project on the rung that highest E + I picks, never below the project's, and keeps it there when the worker steps up. The comprehension seats and the security pass stay on the project's rung. rule-hook holds each reviewer launch to the reviewers' rung, which it works out from the E + Iloop-claudehands the worker inLOOP_CLAUDE_ESCAPE_AND_IMPACT. A delegated task's subagent takes the rung its L picks:subagent-rungtakes L in place of R + C. Until a project reshapes itstodo.md, every chunk there runs on the project's rung. Expect reviews of items whose defects would escape far or break much to cost more, and escalation from an item of L 4 to reach Fable 5.1 only with your yes.- An item that restores a maintain goal the project breaks today is exempt as
defect, and its Moves may name that maintain goal, weighed as the heaviest achieve goal. A defect ranks by its score like any item. Only two kinds rank ahead of the rest of their release: questions first, since an answer may change other items, then security items. - The stability reviewer applies
principles/technical-principles.mdas written, in place of its own copies of it. Its test-data check now asks for UUID v7, where it asked for randomised UUIDs. - larv-review's principles audit is a pass of its own, and runs on every chunk that changes code, config or tests, not only on one with an architectural decision. A chunk of prose or planning alone skips it.
rule-hookrefuses an Agent call that launches a reviewer, a comprehension seat or the security pass on a rung below the oneloop-claudenames for it, and takes no override: pass the model and effort the refusal names.score-outcomeslists a project's score anchors: the shipped items itsdocs/score-anchors.mdnames for each level of L, E and I, each with what its chunk measured.rules/todo-items.mdhas a scorer compare a new item with them, and says how to choose two or three per level. Add the file to each project that merges with merge commits; elsewhere, score by the level descriptions inrules/todo-items.md.loop-claudearchives each judge reply it rejects in the chunk's<sha256>.outcomes.md, with the reason and the reply as json. Before, such a reply reached only stderr, so a run that exited 1 overnight could not say what the judge had returned. stderr now prints only the reason; the reply is in outcomes.md. If archiving fails,loop-claudeexits 1.loop-clauderoutes each chunk ontodo.mdas the default branch holds it, freshly fetched: merge atodo.mdedit before the chunk it should route starts. Wheretodo.mdholds no item for the next release, the earliest release it has named since the newest tag, no item routes the chunk, and the worker is told that release is finished and ready to cut, or, where no work has landed since the tag, to be planned first. Before routing,loop-clauderuns the newbin/chunk-preflightand quotes what it prints in the worker's first prompt: the chunk's mechanical facts, whichchunk-preflight --helplists. The preflight also makes the chunk's worktree,<checkout>-item-<ID>beside the checkout on the branchitem-<ID>, or continues the one already there, and leaves an uncommitted figure in that worktree'sdocs/reading-cost.mdfor the chunk to commit. It stops a fetch, forge CLI or tool after 60 seconds, or after the secondsCHUNK_PREFLIGHT_TIMEOUTsets. The prompt also asks the worker to count the item's size again once it has read the code, and to have the item re-scored where its L would change. Expect the worker to start editing sooner.
0.1.0
todo.md's items table has a Blocked by column, right after Release, listing the IDs of the items that must be done before an item starts, such as12, 14. Move every machine to this release before any of them ranks a plan another machine shares: an older release reads the new table as no plan.rank_todo.pyranks each blocker above every item it blocks, drops an ID once that item leaves the table, and adds the column to a table without it. It does not turn a line such as "Needs 12" in an item's detail into a Blocked by cell; move each into the column by hand. It now fails on text beside the table under## Items, such as a line naming items to take first: put an order in the scores or the column. It reads the table's cells by column name, and fails on a column it does not know rather than drop it.loop-clauderoutes a chunk on the next release's first item that is neither markedquestionnor blocked by an item still in the table, which is the item the worker takes, so the first cycle runs on that item's rung.- The new
bin/stability-replay <model>replays archived stability reviews of the projects run on the model, each on the code it reviewed, first on the project's rung and then on each rung below, and prints the lowest rung that, like each rung above it, finds every 🔴 and 🟡 finding the project's rung finds. It shares its search withjudge-replay, which now tries rungs from the project's rung down, where it tried them from the cheapest up. Its first run, on Opus 5.5 projects, found none: Sonnet 5.5 at high missed 13 of the 29 findings the project's rung found again. So the stability reviewer stays on the project's rung while the worker runs below it. - A
todo.mditem you tell a session to keep is markedownerin its Exempt cell, and stays whatever its score. - A
loop-claudeworker hands a task that proves too hard for its rung to a subagent one rung up, edits included, when a trigger fires: a re-score of the item on the project's rung or above picks a higher rung, the same failing test or finding survives two fix attempts, or a review pass reports a 🔴 in round 2 or later. Each further trigger climbs one more rung, to at most two rungs above the rung the chunk'stodo.mditem picks, unless you agree.CLAUDE.mdstates the rule, andloop-claude's prompt names the rungs a trigger opens. The worker opens the subagent's prompt withEscalation trigger <n>:, androuting-figures.mdcounts the escalations by trigger. Expect a chunk that gets stuck to spend more on the stuck part, and fewer unfinished verdicts. - A loop-claude worker may end its run asking for a higher rung, citing an escalation trigger. Once the judge quotes the transcript passage that shows the trigger fired, the next cycle resumes the worker one rung up, up to two rungs above the rung the chunk's
todo.mditem picks. The archive quotes that passage underEscalation:in the unfinished verdict. - A reviewer that rules a chunk's work below standard, with systems-architect's BLOCK or a finding against larv-review's
standards/quality.md, may ask to rerun one rung up, as may a comprehension seat whose vote in a paired rulingrecord-rulingcounts as worse. The worker relaunches it once, on the rungloop-claude's prompt names. A relaunched reviewer gets the report that asked and confirms or dismisses each of its findings. The relaunch's report stands in place of the one that asked, in the same round, so it adds no round. The ruling that stands is a fourth escalation trigger inCLAUDE.md. Expect a chunk whose work falls below standard to spend more on its review and its fix. - A session or subagent below the project's rung, the cheapest rung of the project's model, no longer scores or reshapes
todo.md: it drafts each new item and each change to a filed item, and before its next commit one subagent on the project's rung or above applies and scores the drafts and sets their release. It may still remove finished items.rules/todo-items.mdstates the rule.CLAUDE.mdhas a session launch a subagent that files or scores items on the rung the newbin/subagent-rung --plan <model> <R+C>prints, never below the project's rung, andloop-claude's prompt to a worker below that rung names the command. Expect one extra subagent in a chunk that files items while its worker runs below the project's rung. loop-clauderuns the judge of an Opus 5.5 project on the rung the chunk'stodo.mditem picks, never below Opus 5.5 at medium effort, the project's rung. Before, the judge ran at the effortsettings.jsonsets, xhigh. A replay of 39 archived verdicts found every cheaper rung missing verdicts. The judge keeps its rung when the worker steps up or takes in another item, and runs on the project's rung when no item routed the chunk. A project on another model keeps its judge at its settings' effort. Each verdict in the archive now names the judge's rung on aJudge:line. The newbin/judge-replay <model>replays the judge on archived verdicts and prints the lowest rung that, like each rung above it, returns them. Expect the judge to cost less on items of R + C 12 or less, and more on items of R + C 15 or more.- Every 20 cycles across all projects,
loop-claudemeasures every finished chunk in its archive, with no model run, and writes the figures torouting-figures.mdat the archive's root: tokens by project, subagent type, rung and tool, and, for each chunk atodo.mditem routed, grouped by the rung it started on: its review rounds past each pass's first, its unfinished verdicts and its subagents' rungs. It interrupts you, withclaudeon the project's model on the terminal in~/.claude, when chunks routed onto a rung took more review rounds or unfinished verdicts than chunks routed onto the next rung up, each rung with 5 chunks or more, or when 5 or more subagents of one type wrote reports longer than the tool results they read. Each call is raised once, then listed inrouting-calls-raised.mdbeside the figures; the next chunk of this repo files atodo.mditem for it. Off a terminal, the calls are said on stderr and the loop goes on. They are raised at the next measurement on a terminal. After a routing change, a- <UTC time> Resetline in that file makes the figures count only chunks finished after it, and lets its calls be raised again. Expect a pause of about ten seconds at each measurement. - A session delegates a task to a subagent only when it needs just the task's conclusion, such as a search across many files, and keeps edits in its own thread. It scores the task's R and C as for a
todo.mditem, and launches the subagent on the model and effort that the newbin/subagent-rung <model> <R+C>picks from the project's model, such asmodel sonnet, effort high.CLAUDE.mdstates the rule. Expect searches to run on cheaper models, and less of each session's context to fill with search output. loop-clauderoutes each chunk's worker on a ladder of model and effort rungs, from Haiku 5.5 at low effort to Fable 5.1 at max, when the project's model is on it. As a chunk starts, the R + C oftodo.md's top item in the next release picks the rung: 11–12 picks one rung above the project's rung, so Opus 5.5 at high for an Opus 5.5 project, and so on up to four rungs. An item of R + C 10 or less runs the worker at or below the project's model's cheapest rung, which for Opus 5.5 is medium effort, below the xhighsettings.jsonsets. While the worker runs below the project's model's cheapest rung, it launches every reviewer, comprehension seat and security pass, the full scan included, in a subagent on that rung. While it runs above that rung, it launches each comprehension seat and the security pass on that rung. It steps up one rung after every second unfinished verdict on a chunk, and to a higher rung when it takes in an item of higher R + C. Each cycle's header, and each finished or unfinished verdict, stop and step-up in the archive, name the worker's rung; a rerun resumes an open chunk on the latest rung archived for it.docs/decisions.md→routing:gives the ladder, its source and the bands. Expect a chunk on an easy item to cost much less than under xhigh, and perhaps to take more review rounds, and one on an item of R + C 15 or more to cost more.- A session reads
todo.mdup to## Details, and the details of only the items its chunk takes. It reads adocs/decisions.mdentry only where the entry's title leaves open what it needs. Both rules are inCLAUDE.md, so they hold from a session's start. The decisions rule replaces one inrules/decisions.md, which loads only once a session has openeddocs/decisions.mdorAGENTS.md. A chunk's opening line now counts the unreleased changes instead of listing them. Expect fewer tokens read before a chunk's first commit. - larv-review's stability and product-owner reviewers report only a defect, a requirement of the plan or the goals that the change breaks, a breach of a technical principle, or for stability a hard place the change touches; the stability reviewer leaves the style of comments to the prose reviewer, which now also reads help and error text. Each architect finding names a concrete later change the PR makes harder, and one that names none is dropped. The prose pass runs only on a chunk that changes prose a reader reads, such as docs, comments, help text or
todo.md, and skips a code-only chunk. Expect fewer findings and fewer review rounds. - Every
todo.mditem carries a C score, how hard the change is to get right, from 1 to 10, in a column after S. C stays out of the score.rank_todo.pyfails on an items table without the column, and the rule hook then blocks committing thattodo.md. Before the next commit that changes a project'stodo.md, add the column and score every item's C, asrank_todo.py --helpshows. - The new
bin/score-outcomesshows what finished chunks measured beside the R, S and C their items were guessed at: lines and files changed, review rounds, and 🔴 and 🟡 findings. It reads them from the default branch's merge commits, so a project that merges by squash or fast-forward shows none. Given a guess, it lists the 5 finished items guessed nearest. It always reports, for each score, the median outcome at each guessed value, once 10 chunks that each shipped one item record it: R against 🔴 findings, S against lines changed, C against review rounds past each pass's first. A session filing or editing an item runs it and scores R, S and C from what it shows. - larv-review round commits now carry the round's 🔴 and 🟡 counts,
Answer stability round 1: 1 🔴, 2 🟡; …, and the rule hook's newround-title-countsrule blocks a round title without them. - The stability reviewer mutation-tests the lines each change adds or modifies: it makes small changes to that code, such as flipping a comparison. For each test to add or strengthen, it reports one 🟡 naming the changes that test would catch. It uses the project's documented mutation command, or else cargo-mutants, Infection, mutmut or Stryker. The technical principles replace "Test coverage should not decline" with "Every mutant of a changed line fails a test, unless the mutant leaves behaviour unchanged", and say what a valuable test is: it checks behaviour through the unit's interface, and fails when that behaviour breaks. README → "Tools" gives the mutmut command for
bin/. Expect longer stability passes and more 🟡s about tests. In a project whose README documents no mutation command, the reviewer picks and installs a tool on each run; document one there to make the runs consistent. - Each new
loop-claudeworker session's prompt now quotes the README's Goals and Audience. A line above them says that the chunk'stodo.mditems, or else the task, set its scope, and that the goals only choose how to deliver it. A session outside the loop reads Goals and Audience before starting a chunk, asCLAUDE.mdnow says. - A session no longer reads the technical principles before writing code. It writes the simplest change that solves its item, test first wherever a test can check the change, and reads a principle only when the item changes it, a finding names it, or a decision or
todo.mditem it writes cites it. larv-review's reviewers hold the change to the principles, and a finding against one names it. Expect more findings from the prose and stability reviewers, since sessions no longer load the rules for comments and READMEs. - The rules for comments and READMEs, "Quality" and the examples behind "Prose" moved to
skills/larv-review/standards/, which the prose and stability reviewers andloop-claude's judge read.CLAUDE.mdkeeps a short core of "Prose"; sorting where order carries no meaning lives only in the technical principles. - A session no longer points out a preference you have repeated or asks you to write it up, and no longer restructures
CLAUDE.mdandrules/after changing them. - A
todo.mditem names a release whose version bump fits the item under strict semver: a major for a change to what exists (a minor before 1.0.0), a minor for an addition, a patch for a fix. CLAUDE.mdkeeps only the rules no file path can scope. The rules fortodo.mditems, decisions and a README's Goals and Audience moved to files underrules/. Claude Code loads each one when a session reads or writes a matching file.loop-claude's judge reads them besideCLAUDE.md.- A README no longer holds cross-cutting decisions;
docs/decisions.mddoes. - A technical principle, "Prefer deep modules": a module puts a small, intuitive interface in front of a lot of hidden work, and hides how it works but never what it depends on. It wins over "Explicit over implicit" unless hiding the work makes it harder for someone new to the project to tell what a call does. "Functional core, imperative shell" moves up to second place, a core rule beside "Compose, do not entangle" that no other principle overrides. The systems architect holds every module to it.
- A hook blocks each Bash, Edit, MultiEdit and Write call that breaks a rule a program can check: a commit message that is not one line passed with
-m, a Claude or Anthropic attribution, a container image short of a full patch version, an Action pinned to anything but a semver tag, an unsorted block in an ignore file, and a commit of atodo.mdthatrank_todo.py --checkrejects.CLAUDE.mdstates those rules only where the hook cannot check them;~/.claude/bin/rule-hook --helpstates what it checks. A call overrides a rule with# rule-override <rule>: <reason>. larv-review's new overrides pass, run before stability, accepts or rejects each override the chunk logged, and the PR body lists each with its ruling; a rejected override means the chunk keeps the rule. An override that touches a credential, a security rule or a production system, or cannot be undone, is asked of you. - A project may opt out of larv-review's architect, product-owner pass or comprehension check in every chunk, through a
docs/decisions.mdentry titledreview opt-out: …that names the goal that skipping them serves. A project without such an entry is reviewed as before. Opting out of the comprehension check also skips the scoring run due at a release's end. The principles audit always runs. - A README goal states the project's aim and intent, and no longer names a step of the work, such as "kill weak candidates early". Such steps go in a method section further down the README and name the goal they serve.
- The stability reviewer keeps its scratch work in a directory it creates for the run, deletes that directory afterwards, and deletes nothing else.
- larv-review's mechanical rules run in the new, tested
bin/larv-review: the paired ruling's base (ruling-base), each pass's round count (round-count, which ignores case in a round's commit title, counts a repeated round number as a round of its own, and says to ask you before another round once a pass is at or past the cap), the scoring run's trigger (needs-scoring-run <item ID>...), and the vote count, means and history format (record-ruling <votes file>andrecord-scoring <scores file> [<item ID>...], which append todocs/comprehension-history.mdand refuse a second entry on what a seats file's first line reads;record-scoringrefuses a run the plan does not call, and printsFloor:naming each mean under the comprehension floor of 7.0), and the places seats found hard since the newest scoring run (places). The skill says when to run each and what its answer means. A seats file line the tool cannot read fails the run, so a mistyped vote never counts as same. The base search compares the history before and after each merged change, so it no longer depends on how a line is worded. A release whose last plan item moves to another release is due a scoring run too, once work has landed towards it. A seats file must name commits the checkout holds. When origin cannot be fetched, the tool reads it as last fetched and says so. - The new
bin/metric-benchbenches cheap static metrics of a project's Python against the places its comprehension history names as hardest: cognitive complexity, length, shared state and change spread, each scored by how well it ranks the named functions above the rest. No metric enters review yet. - larv-review runs a comprehension check, which records how hard the project is to read and blocks no merge. It runs once per chunk, after every pass, on the branch as review left it. Where the architecture pass ran, Mid A and the inherited architect read that commit beside the last measured commit: the default branch's newest merged change that added a ruling or a scoring run to
docs/comprehension-history.md. They vote better, same or worse on each dimension and overall:Navigation same, Locality worse, Shape same, Self-sufficiency same, Overall better. When their overall votes differ, the maintainability senior and Junior A vote too. A ruling needs a lead of two or more votes, else it is same. Each place a seat names opens with the dimensions it moves, such asLocality, Shape:, or the run fails, and a vote that no place opens with counts as same. Four seats score the project from 1 to 10 when a chunk ships or removes a release's last plan item, or ships an item naming the comprehension floor of 7.0. A project whose owndocs/decisions.mdorAGENTS.mdstill says the floor or a worse ruling blocks a merge keeps that rule; edit it there to stop blocking. - larv-review reruns fewer passes after a fix. A fix reruns the pass whose 🔴 or 🟡 it answers, plus stability when the fix changes behaviour, security when it opens an untrusted-input boundary or touches authn/authz, secrets or crypto, and architecture when it carries an architectural decision. From round 2, a reviewer agent reviews only the answers to its previous round's findings: each fix, and each dismissal with its reason. A fix from another pass that re-enters it gets a first-round review, limited to the fix's lines. On those answers it reports only a fix or a dismissal that is plainly wrong or worse than the change it answered, so a pass should converge in its second round. A fix for a 🟢, a ❓ or any prose finding reruns no pass, and prose takes one round.
- larv-review runs one security pass on each change: the full scan alone when it runs, else
/security-review. - larv-review runs the new
bin/reading-cost, which measures each chunkloop-claudefinished from its archive: the new input tokens the worker and its subagents took in before the worker's first commit, and the files git tracks that they read most. It appends each figure the project'sdocs/reading-cost.mdlacks. Once 10 chunks are measured, and the last 5 chunks' median is above the 5 before them, larv-review files one plan item naming the files read most, or refreshes it. The chunk that ships it runsreading-cost --reset, so the trend counts only chunks that finished after it. - larv-review appends every paired ruling and scoring run to the project's
docs/comprehension-history.md: the commit the seats read, a ruling's base, each seat's vote or scores, and the places each seat named. The PR summary gives each ruling with its base and votes. The seats do not read the history. - The architect and the stability reviewer get the places seats found hard since the newest scoring run, from the new
larv-review places: that run's places, and each later ruling's places a seat voted worse. Each reports, as a 🟡, a place the change touches without making it easier to read; the chunk fixes it or says in the PR summary why not. A session filing atodo.mditem reads the places too, and an item touching one says to make it easier to read. - The README's goals put quality with the fewest interrupts first, as goal 1; sharing the setup, backups and leaking nothing follow as goals 2–4.
- larv-review skips the comprehension check for a chunk whose plan items a project decision names. The decision also names the later item whose check ends the suspension. The skipped chunk's summary cites the decision. A chunk that ships or removes a release's last plan item, or ships an item naming the floor, still gets the scoring run.
- README → Install and Update give the commands that check the latest tag out into
~/.claude: on a new machine, whether or not Claude Code has already created the directory, and on one already on an older tag. - A session commits changes Claude Code made to
settings.jsononly once their diff holds no credential, and asks you to move any credential out of the file first. - A technical principle, "Sane defaults, where a default serves better than an explicit ask". A default suits a value most callers want, does no harm when wrong, and can be seen and changed. It lives at the program's edge, such as a CLI; a library still asks for data, the clock and randomness.
- larv-review's principles audit reads only the files under
~/.claude/principles/that apply to the project, launching a file's auditor when unsure. A file'sApplies toline says what it covers; one without the line covers every project. The summary names each file left out. After its first round, the architecture pass reruns only the reviewers whose 🔴 or 🟡 the fixes answer, unless the fixes carry an architectural decision. - When
loop-claude's judge rules a chunk unfinished, the resumed worker is shown the passage the judge quoted as the work remaining. A loop started before this change exits 1 at its next reload; rerun it. - larv-review's architecture pass and full security scan get short names,
ArchitectureandFull scan. Each round's commit is titled with its pass's name in lower case:Answer full scan round 1: …. loop-claude's judge reads your~/.claude/CLAUDE.mdbeside the project'sAGENTS.mdanddocs/decisions.md. It no longer interrupts for a choice that file settles, and it answers the worker's questions from it.loop-claude's judge holds a chunk open until each answer you typed in it that a later chunk could need is recorded. An answer counts as recorded once the README's goals or audience,AGENTS.md,docs/decisions.mdor~/.claude/CLAUDE.mdhold it. It also counts once the transcript shows the worker writing it into the README's goals or audience,AGENTS.md,docs/decisions.md,todo.mdor a code comment. The worker writing to~/.claude/CLAUDE.mddoes not count, since new rules there are yours. The resumed worker is told this rule.loop-claudearchives each answer the judge quotes, with the question it answers and its UTC time, in<sha256>.outcomes.md.- larv-review keeps its three-round cap across a resumed session. It closes each review round with a commit naming the pass and the round, empty when the round changed nothing, and counts rounds from the branch's own commits.
- larv-review runs
/security-reviewin a subagent, so the run goes on to the next pass without you prompting it. - larv-review asks once before the full security scan: it states the evidence and its recommendation, and
claude-security's cost prompt is the ask. loop-claudeaccepts the judge's quote of the transcript when it elides with an ellipsis and the transcript holds each fragment in order. The transcript the judge reads, and the worker's printed output, show tool input with its non-ASCII characters as written, so the judge can quote it.- Unless another Exempt reason fits, larv-review marks a
todo.mditem filed from a 🟡 finding against~/.claude/principles/withprinciple, an Exempt reason that keeps it whatever its score. loop-claude's judge reads the project'sAGENTS.mdanddocs/decisions.mdbeside the README's goals and audience, and does not interrupt for a choice they settle. When the worker asks a question that the README or those files answer, the worker resumes with the judge's quote of the answer, whichloop-claudeprints. A quote they do not hold word for word is dropped, and the question goes to you. So does a question asked again after its answer. The fourth question they answer in one cycle goes to you too, with the quote. The judge reads as much of the transcript's end as fits a 400,000-character prompt, up from the last 40,000 characters.loop-claudeexits 1 whenAGENTS.mdordocs/decisions.mdcannot be read or is not UTF-8.- A project's decision log is
docs/decisions.mdalone, the one file the judge,rank_todo.pyand the reviewers read. loop-claudewaits out a usage limit and retries: 2 minutes past the reset, or every 10 minutes when the reset time is unknown. A limit is not a failure, and restarts the count of three failures in a row. It prints what claude said about the limit and when the next try is due.- Add the official plugin marketplace and install every plugin
settings.jsonenables (README → Install):claude-security,code-reviewandrust-analyzer-lsp, which needsrust-analyzeronPATHfor Rust projects. Withclaude-security, larv-review's full security scan runs once you confirm its cost; an unattended larv-review reports the scan as not run.settings.jsonsilences the plugin's scan tip aftergit push. - systems-architect and product-owner-reviewer can no longer edit what they review; stability-reviewer keeps its shell to run tests, and loses Claude Code's file-editing tools.
- Every project's
todo.mdtakes one shape, and larv-review's gate checks it: one table of items, each scored by the formula and goal weights the file states and held to its bar, an item under the bar dropped unless its Exempt cell says why.bin/rank_todo.pyranks the table, andrank_todo.py --helpshows a valid file. - Run
loop-claudeonly in a sandbox with no direct access to production: every claude it starts skips every permission prompt. - First release:
README.mdstates what the checkout holds and needs,loop-claude --helpwhatloop-claudedoes. settings.json, the agents and the status line run unedited on any machine with README → Install's prerequisites; the status line shows reset times in the machine's own time zone.loop-claude's no-premises exit names what is wrong:README.mdunopenable or not UTF-8, a## Goalsor## Audienceheading missing or repeated, or nothing under one.loop-claudesays why when it cannot read or write~/.claude.jsonbefore an interrupt, naming aprojectsentry that is not an object, and the interrupt then lands in Claude Code's trust dialog.loop-claudeskips a transcript line it cannot parse, exits 1 naming a transcript it cannot read, and counts aclaudeit cannot start as a failed worker run.loop-claude's judge quotes the transcript for every verdict, and a verdict quoting nothing or interrupting without a question, or aclaudethe judge cannot start, is a failed judge run; aclaudethat cannot start for an interrupt exits 1.loop-claude's exit-2 message says what the human is needed for.loop-claudeexits 1 saying why whengit, or python for a reload, cannot start.loop-claude --helplists each exit cause on its own line, and when an edit toloop-claudebreaks its reload, the exit-1 message names what the edited script could not read.loop-claudeshows the judge's reply when it rejects the judge's verdict.loop-clauderetries a failed worker within its cycle.loop-claudecounts an interrupt reply starting with<as typed.loop-claude's judge sees a reply the human types while claude works, and an interrupt counts one as typed.loop-claudearchives the raw.jsonltranscript at every interrupt and as every cycle ends, Ctrl-C and failures included, in one folder per chunk. Each distinct transcript is kept once, named by its SHA-256. Beside it,<sha256>.outcomes.mdholds the verdict, with the transcript passage the judge rested it on, and why the loop stopped. The verdict and the stop each open with their UTC time. The subagents' transcripts and the session's other files go in the chunk folder'ssession/subfolder.loop-claudeexits 1 when it cannot archive.loop-claudeexits 1 when it cannot delete a finished chunk's session, naming what to delete before rerunning; the next chunk would otherwise resume it.loop-claudekeeps the mode of~/.claude.jsonand of its models file when it rewrites them, and creates the models file 0600.