13 KiB
13 KiB
Changelog
Unreleased
- 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), the scoring run's trigger (needs-scoring-run <item ID>...), and the vote count, means and history format (record-rulingandrecord-scoring, which read a seats file and append todocs/comprehension-history.md). 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, and orders a change's rulings by their headings' times. A release left with no plan item is due a scoring run however its items left, moved to another release included. - 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 blocks a merge when simulated readers rule that the PR makes the project read worse than the last measured commit: the default branch's newest merged change that added a scoring run to
docs/comprehension-history.md, or whose last ruling there is better. A ruling of same leaves that commit in place, so a worse ruling may name places earlier chunks wrote. In each architecture pass Mid A and the inherited architect vote better, same or worse; when they disagree, the maintainability senior and Junior A vote too. A ruling needs a lead of two or more votes, else it is same, and a vote that names no place counts as same. A worse ruling never ships: after three rounds larv-review asks you for another round, a no leaves the PR unmerged, and so does an unattended run. The four-seat scoring run checks the comprehension floor only when a chunk ships or removes a release's last plan item, or ships an item naming the floor; between those runs the floor blocks nothing. A score under the floor blocks the merge until fixed or until you decide to ship; a decision indocs/decisions.mdthat lets every chunk ship under the floor counts as yours. - 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. A rerun reviews only what changed since that pass last reviewed. 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. Thecomprehension floor:entry indocs/decisions.mdkeeps only the decisions to ship under the floor; a project's next scoring run moves the last scores the entry still holds into the history. The seats do not read the history. - 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 reruns the comprehension check before merge when any commit since its last run changes more than
docs/decisions.md,docs/comprehension-history.md,docs/reading-cost.md,todo.mdorCHANGELOG.md, so the recorded result is the merged commit's. A result that blocks the merge is never filed intodo.md. A rerun counts toward the three-round cap only when it reports a block that no decision of yours covers. - 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. A skipped chunk cannot be blocked for reading worse or for the floor, and its 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.