Files
claude-config/CHANGELOG.md
T

34 KiB
Raw Blame History

Changelog

Unreleased

  • 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.md says so, and larv-review's goal alignment step no longer merges such a PR. rules/goals-and-audience.md states 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.md to 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, and rank_todo.py says so. First move every machine to this release: an older release rejects the new formula, so it fails on every reshaped todo.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-shape todo.md still ranks by its own formula and weights.
  • todo.md ranks items by value per cost: this setup's own plan uses Score = 100 * V / (2**S + 8), where 8 is a chunk's fixed cost, about one size-3 change, and rank_todo.py --help shows it. A Moves column replaces A, G and Goals, naming each achieve goal an item moves and how far, such as 1.1 by 8, 1.2 by 5. V sums each named goal's weight times its move. rank_todo.py weighs each achieve goal by its position in README.md, the first heaviest, so the goal weights table goes. An item names the most specific goal it moves, never a goal beside its own sub-goal. rules/todo-items.md and rank_todo.py --help show 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.md defines each level in words, and rank_todo.py writes 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-outcomes takes L E I S, and reports how well L, E and I each order finished chunks by review rounds and 🔴 findings.
  • loop-claude routes 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 item's E + I, 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 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 loop-claude hands the worker in LOOP_CLAUDE_REVIEWER_RUNG. A delegated task's subagent takes the rung its L picks: subagent-rung takes L in place of R + C. Until a project reshapes its todo.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.md as 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-hook refuses an Agent call that launches a reviewer, a comprehension seat or the security pass on a rung below the one loop-claude names for it, and takes no override: pass the model and effort the refusal names.
  • score-outcomes lists a project's score anchors: the shipped items its docs/score-anchors.md names for each level of L, E and I, each with what its chunk measured. rules/todo-items.md has 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 in rules/todo-items.md.

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 as 12, 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.py ranks 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-claude routes a chunk on the next release's first item that is neither marked question nor 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 with judge-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.md item you tell a session to keep is marked owner in its Exempt cell, and stays whatever its score.
  • A loop-claude worker 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's todo.md item picks, unless you agree. CLAUDE.md states the rule, and loop-claude's prompt names the rungs a trigger opens. The worker opens the subagent's prompt with Escalation trigger <n>:, and routing-figures.md counts 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.md item picks. The archive quotes that passage under Escalation: 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 ruling record-ruling counts as worse. The worker relaunches it once, on the rung loop-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 in CLAUDE.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.md states the rule. CLAUDE.md has a session launch a subagent that files or scores items on the rung the new bin/subagent-rung --plan <model> <R+C> prints, never below the project's rung, and loop-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-claude runs the judge of an Opus 5.5 project on the rung the chunk's todo.md item picks, never below Opus 5.5 at medium effort, the project's rung. Before, the judge ran at the effort settings.json sets, 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 a Judge: line. The new bin/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-claude measures every finished chunk in its archive, with no model run, and writes the figures to routing-figures.md at the archive's root: tokens by project, subagent type, rung and tool, and, for each chunk a todo.md item 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, with claude on 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 in routing-calls-raised.md beside the figures; the next chunk of this repo files a todo.md item 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> Reset line 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.md item, and launches the subagent on the model and effort that the new bin/subagent-rung <model> <R+C> picks from the project's model, such as model sonnet, effort high. CLAUDE.md states the rule. Expect searches to run on cheaper models, and less of each session's context to fill with search output.
  • loop-claude routes 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 of todo.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 xhigh settings.json sets. 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.md up to ## Details, and the details of only the items its chunk takes. It reads a docs/decisions.md entry only where the entry's title leaves open what it needs. Both rules are in CLAUDE.md, so they hold from a session's start. The decisions rule replaces one in rules/decisions.md, which loads only once a session has opened docs/decisions.md or AGENTS.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.md item 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.py fails on an items table without the column, and the rule hook then blocks committing that todo.md. Before the next commit that changes a project's todo.md, add the column and score every item's C, as rank_todo.py --help shows.
  • The new bin/score-outcomes shows 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 new round-title-counts rule 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-claude worker session's prompt now quotes the README's Goals and Audience. A line above them says that the chunk's todo.md items, 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, as CLAUDE.md now 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.md item 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 and loop-claude's judge read. CLAUDE.md keeps 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.md and rules/ after changing them.
  • A todo.md item 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.md keeps only the rules no file path can scope. The rules for todo.md items, decisions and a README's Goals and Audience moved to files under rules/. Claude Code loads each one when a session reads or writes a matching file. loop-claude's judge reads them beside CLAUDE.md.
  • A README no longer holds cross-cutting decisions; docs/decisions.md does.
  • 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 a todo.md that rank_todo.py --check rejects. CLAUDE.md states those rules only where the hook cannot check them; ~/.claude/bin/rule-hook --help states 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.md entry titled review 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> and record-scoring <scores file> [<item ID>...], which append to docs/comprehension-history.md and refuse a second entry on what a seats file's first line reads; record-scoring refuses a run the plan does not call, and prints Floor: 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-bench benches 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 as Locality, 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 own docs/decisions.md or AGENTS.md still 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 chunk loop-claude finished from its archive: the new input tokens the worker and its subagents took in before the worker's first commit, and the files git tracks that they read most. It appends each figure the project's docs/reading-cost.md lacks. Once 10 chunks are measured, and the last 5 chunks' median is above the 5 before them, larv-review files one plan item naming the files read most, or refreshes it. The chunk that ships it runs reading-cost --reset, so the trend counts only chunks that finished after it.
  • 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 a todo.md item 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.json only 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's Applies to line 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, Architecture and Full 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.md beside the project's AGENTS.md and docs/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.md or ~/.claude/CLAUDE.md hold 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.md or a code comment. The worker writing to ~/.claude/CLAUDE.md does not count, since new rules there are yours. The resumed worker is told this rule.
  • loop-claude archives 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-review in 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-claude accepts 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.md item filed from a 🟡 finding against ~/.claude/principles/ with principle, an Exempt reason that keeps it whatever its score.
  • loop-claude's judge reads the project's AGENTS.md and docs/decisions.md beside 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, which loop-claude prints. 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-claude exits 1 when AGENTS.md or docs/decisions.md cannot be read or is not UTF-8.
  • A project's decision log is docs/decisions.md alone, the one file the judge, rank_todo.py and the reviewers read.
  • loop-claude waits 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.json enables (README → Install): claude-security, code-review and rust-analyzer-lsp, which needs rust-analyzer on PATH for Rust projects. With claude-security, larv-review's full security scan runs once you confirm its cost; an unattended larv-review reports the scan as not run. settings.json silences the plugin's scan tip after git 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.md takes 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.py ranks the table, and rank_todo.py --help shows a valid file.
  • Run loop-claude only in a sandbox with no direct access to production: every claude it starts skips every permission prompt.
  • First release: README.md states what the checkout holds and needs, loop-claude --help what loop-claude does.
  • 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.md unopenable or not UTF-8, a ## Goals or ## Audience heading missing or repeated, or nothing under one.
  • loop-claude says why when it cannot read or write ~/.claude.json before an interrupt, naming a projects entry that is not an object, and the interrupt then lands in Claude Code's trust dialog.
  • loop-claude skips a transcript line it cannot parse, exits 1 naming a transcript it cannot read, and counts a claude it 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 a claude the judge cannot start, is a failed judge run; a claude that cannot start for an interrupt exits 1.
  • loop-claude's exit-2 message says what the human is needed for.
  • loop-claude exits 1 saying why when git, or python for a reload, cannot start.
  • loop-claude --help lists each exit cause on its own line, and when an edit to loop-claude breaks its reload, the exit-1 message names what the edited script could not read.
  • loop-claude shows the judge's reply when it rejects the judge's verdict.
  • loop-claude retries a failed worker within its cycle.
  • loop-claude counts 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-claude archives the raw .jsonl transcript 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.md holds 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's session/ subfolder. loop-claude exits 1 when it cannot archive.
  • loop-claude exits 1 when it cannot delete a finished chunk's session, naming what to delete before rerunning; the next chunk would otherwise resume it.
  • loop-claude keeps the mode of ~/.claude.json and of its models file when it rewrites them, and creates the models file 0600.