18 KiB
Decisions
larv-review: a project under the comprehension floor is fixed at the lowest dimension
2026-09-20, lilleman. Serves goal 1. Across six projects scored with the four seats, Locality or Self-sufficiency was the lowest dimension at every seat and Navigation at none, so a layout fix would not lift a project under the floor. Valid while the scoring run keeps those four seats.
loop-claude: a judge decides each interrupt and each quoted answer from the transcript, the README's premises, AGENTS.md, docs/decisions.md and ~/.claude/CLAUDE.md, and holds a chunk open while an answer the human typed in it is recorded nowhere; the worker's own account of which goal settles a choice decides nothing
2026-09-21, lilleman. Serves goal 1. Asked to name the goal behind each choice, the worker cites a real goal for a choice that goal does not settle, and under-reports its own decisions; the judge's bar is whether the README discriminates between the alternatives. Valid while the worker's self-report stays unreliable.
2026-10-01, lilleman: the judge reads docs/decisions.md and AGENTS.md too, so an answer recorded there is not asked again (goal 1.2); its bar becomes whether the README or those files discriminate. 2026-10-03, implemented: when the README's premises or those files answer the worker's question, the judge quotes the answer verbatim and the worker resumes with it. The judge then sees the quote as a [loop] line. The worker asking it again shows the quote did not settle it, and the judge sends it to the human. A backstop of three quoted answers per cycle bounds what the judge misses, such as a reworded repeat or a worker asking without end, so the worker cannot loop unattended (goal 1.4); the fourth question that the README's premises or those files answer in one cycle goes to the human with the judge's quote. An interrupt does not reset the count, so every later question those files answer in that cycle also goes to the human. Valid while the worker writes records only in a worktree, as CLAUDE.md → "Working with the codebase" has it, so the records the judge reads from the checkout root are merged ones.
2026-10-03, lilleman: the judge is to read ~/.claude/CLAUDE.md whole too. The worker follows that file, so a question it answers should not reach the human (goal 1.2). Reading the whole file is safe, because the judge may quote only words that appear in it. A list of sections would need keeping current. Implemented the same day.
2026-10-03, lilleman: the judge rules a chunk finished only once every answer the human typed in it is recorded. A finished chunk's session is deleted, and its answers with it, so an answer recorded nowhere would be asked again in a later chunk (goal 1.2). Implemented the same day by claude, which settled two choices the ruling left open. First, an answer counts as recorded where the files the judge reads hold it, ~/.claude/CLAUDE.md included, or where the transcript shows the worker writing it into README.md's premises, AGENTS.md, docs/decisions.md, todo.md or a code comment. A worker's write to ~/.claude/CLAUDE.md does not count: CLAUDE.md → "Maintaining this file" leaves new rules in it to the human. The judge cannot read a code comment or todo.md. Yet CLAUDE.md → "Working loop", "Ask, don't guess" puts a standing choice made in one place in a comment there. And the human's approval of a release's items, which "Working loop" requires, is the set of rows todo.md names for that release. The judge also reads the records once a cycle from the main checkout. That checkout may not yet hold an answer the worker wrote and merged. A judge that refused any of these would hold the chunk open every cycle. Second, only an answer a later chunk could need must be recorded, so an approval such as "merge it" holds nothing open. The worker's resume prompt states the rule, so a worker whose chunk is held open knows it.
loop-claude: one session per project, its id derived from the checkout's path relative to ~/code, or to / outside it
2026-09-21, lilleman; revised 2026-09-30 by lilleman. Serves goal 1. One fixed id per project keeps the session picker at one entry per project and makes any transcript under that id loop-claude's own to delete. A checkout outside ~/code mirroring a path inside it shares that id, and a second loop on it is not refused. Once todo.md item 5 lands, the id comes from the full path, so no two checkouts share one, and loop-claude refuses to start while another session on that id is active. Moving the checkout orphans its open sessions, archive folder and models entry: sessions stay in the picker until the human deletes them, migration code not being worth a one-human audience. Valid while claude takes --session-id and resumes by it.
loop-claude: before an interrupt, it marks the checkout and each of its worktrees trusted in ~/.claude.json
2026-09-21, lilleman; the lost-write risk accepted 2026-09-24 by larv-review. Serves goal 1. A write by another claude inside trust's read-modify-write window is lost.
2026-09-24, lilleman, extending it to every worktree. claude --resume re-enters the worktree the worker last entered, recorded in the transcript's worktree-state entry, and Claude Code asks trust per path, so trusting the checkout alone still lands the human in the dialog; trusting every worktree git worktree list names spares reading which one from the transcript. Valid while resume re-enters a recorded worktree and trust is kept per path.
2026-09-30, lilleman: Claude Code owns and writes that file, so loop-claude is to move out of it, bringing each case that must stay to the human. Stands until todo.md item 6 ends it.
bin/: the tests rerun themselves on a uv-fetched Python at README Install's floor
2026-09-26, larv-review. Serves goal 2. The suite reruns itself on a uv-fetched interpreter of the version Install names: ast.parse(feature_version=) on the host's Python accepts the nested f-string 186181a fixed, a compile check passes a call newer than the floor, like 3.12's itertools.batched, and a python3.N on PATH is installed by hand on every machine and again at each bump. Valid while uv can fetch the floor interpreter and no machine taking the checkout ships an older Python.
bin/: the tools and their tests run on the host's Python, with no container
2026-09-24, larv-review. Serves goals 1 and 2. The tools drive the host's claude CLI and read the host's session files, which a container cannot see; the tests run on the same host Python the tools meet. Valid while claude runs on the host.
comprehension floor: every dimension and the overall at 7.0 or above, and 0.1.0 waits on it
2026-09-27, lilleman, restating the 2026-09-24 target and extending it to the overall. Serves goal 1. Valid while the scoring run keeps its four seats. The decisions to ship under the floor, listed below, stand until todo.md item 62 lifts the project to it.
lilleman decided to ship each of these under the floor on the day listed. Each line gives its last scores (Navigation, Locality, Shape, Self-sufficiency, overall):
- 2026-10-01,
rebuild, merged at8585257: 7.38, 6.75, 7.25, 6.5, 6.88. - 2026-10-01, PR #182: 7.5, 6.5, 6.88, 6.25, 6.38.
- 2026-10-02, PR #191: 7.63, 7.0, 7.25, 6.75, 7.25.
- 2026-10-02, PR #196: 7.5, 7.0, 7.0, 6.75, 7.0.
- 2026-10-02, PR #198: 7.63, 6.88, 7.38, 6.75, 7.13.
- 2026-10-03, PR #202: 7.5, 7.0, 7.0, 6.75, 7.0.
- 2026-10-03, PR #208: 7.5, 7.0, 7.13, 6.63, 6.88.
- 2026-10-04, PR #215: 7.38, 6.63, 7.0, 6.88, 6.88.
- 2026-10-08, PR #224: 7.00, 6.50, 7.00, 6.50, 6.75. lilleman shipped it below the ratchet as well: its 20 lines of skill prose left the code as it was, so the fall is the panel's noise between runs, which
todo.mditem 75 addresses.
loop-claude: each project's model lives in ~/.claude/loop-claude-models.json, which only loop-claude writes
2026-09-26, lilleman. Serves goal 1. Claude Code rewrites the user settings' model whenever one is picked inside a session, so a loop reading settings runs whatever was picked last; ~/.claude/loop-claude-models.json has loop-claude as its one writer, and every claude it starts gets that model as --model. The file is per machine, outside the synced allowlist, since a tracked file the loop writes would dirty the checkout. 2026-10-02, lilleman: goal 2 shares the setup across machines, and a project's model is each machine's own choice, so a new machine asks once per project, which is not asking the same thing twice (goal 1.2). Valid while Claude Code keeps rewriting the settings' model from inside a session.
review: a pass gets at most three rounds per chunk; instead of a fourth, the run asks the human
2026-09-28, lilleman. Serves goal 1. One counter per pass per chunk, so no fix bounces between two passes without end. Valid while one human answers the ask, in the session or from the unmerged PR.
review: a fix for a 🟢 or ❓ re-enters review like any fix
2026-09-30, lilleman. Serves goal 1: no human reads an unattended chunk before it merges, so every change it makes, a nit's wording included, is reviewed. In the 2026-09-30 bench this cost four of nine rounds in one run and drove two passes to the round cap. Valid while a pass is the only reader of a fix before merge.
review: a project decision may suspend the scoring run for the plan items it names
2026-10-04, lilleman. Serves goal 1.4. In a restructure, each step's scoring run measures code the next step deletes. It costs a run and, below the floor, blocks the step, yet says nothing about what the restructure buys. The scoring run after the last step measures that. Valid while such a decision names its items and the plan item that ends it.
review: a pass skips only on a precedent: a decision, or a plan item crediting the pass, that the repo held before the chunk began
2026-09-30, lilleman. Serves goal 1: a decision the chunk writes is the chunk's own and unreviewed, and an unattended run has no human to catch it. Valid while a pass is the only reader of a chunk before merge.
loop-claude: the archive keeps the raw transcript, and a failed archive stops the loop
2026-09-28, lilleman. Serves goals 1 and 3: saving each transcript locally is the first step of backing it up, and it shows afterwards what an unattended run did. A copy of the .jsonl, deduplicated by content hash, with its outcomes beside it; a rendering drops tool results, and a second-resolution stamp names two states within one second as one file. A failed archive exits 1, since a loop that loses its record silently fails the backup goal. Valid while transcripts stay small enough to copy whole.
loop-claude: a claude that cannot start is a failed worker run, retried
2026-09-28, larv-review, declining a product-owner nit to exit at once when claude is missing. Serves goal 1. Claude Code's updater repoints ~/.local/bin/claude at each new version under running loops, and a start that meets it mid-update fails with the same error as a broken install; the retry costs two minutes on the second and saves an unattended loop on the first. Valid while Claude Code updates by repointing its link.
review: an ask no user answers leaves the PR unmerged
2026-09-30, claude. Serves goal 1: the round cap, a BLOCK's restructure, Stage 0's questions and a goal conflict are the human's call, and an unmerged PR is what brings it to them; merging would make the call for them. Where an option reviews more — run the pass, fix under the floor, fix a finding no goal lets the run decline — the run takes it; a ❓, or a fix changing a goal or a decision, is filed in todo.md, which reaches the human without holding the chunk. Valid while a human reads every unmerged PR an unattended run leaves.
loop-claude: every claude it starts bypasses permissions inside its sandbox
2026-09-30, lilleman. Applies "Always grant explicit access to data": the sandbox loop-claude runs in is where access is granted, so the worker and the interrupt run with bypassPermissions. The worker may read ~/.claude/.credentials.json: it holds Claude Code's own credentials, which claude reads to run anyway. Its one seam to production is the forge: what it pushes or merges can publish through CI. Valid while loop-claude runs only in the sandbox README → Install names.
review: /security-review is the security pass of record
2026-09-20, lilleman. Serves goal 1.1. Its value is a tuned exclusion list and a ≥0.8 confidence floor, which a hand-written reviewer would reproduce worse. Valid while /security-review ships both.
review: the premises chunk's whole review is the human's approval
2026-09-20, lilleman. Serves goal 1.1. A reviewer's finding on that chunk could only be declined by citing the goals the chunk exists to write. Valid while every decline must name a goal or a technical principle.
workflow-bench/: the remote may show the bench cases' names and commit SHAs
2026-10-02, lilleman. Serves goal 4, which keeps credentials, transcripts and memory files off the remote; a private project's name and commit ids are none of those. Valid while the bench names only cases and commits, never their code or results.
todo.md: one table of items scored by the formula and goal weights it states, held to its bar, ranked by bin/rank_todo.py
2026-10-02, lilleman. Serves goal 1: findings were filed faster than chunks closed them, so the plan grew without telling what mattered. Each item is scored as CLAUDE.md → "Todo items" says; this repo's formula counts value highest and size least. An item under the bar is not kept; this repo's bar started at 10 and was set to 9 the same day, purging the 17 items under it. An Exempt cell keeps a row past the bar where a rule needs it kept. lilleman retired the two decisions whose plans the purge removed: the stats line in the transcript archive, and three benches before a workflow change merges. A finding under the bar is recorded nowhere, so a later review may raise it again, and the run rescores it. That costs one scoring; a ledger of dropped findings would regrow the list the bar caps. larv-review's "Round cap" → "Done" counts a finding named under the bar as settled, so one raised again holds no pass open. rank_todo.py --check is part of larv-review's gate, since only a check keeps the stored Score from going stale. The format is mandatory in every project, as the premises are (goal 1.3); the formula, bar and weights are each project's own. A script ranks the table so a re-rank after each addition or edit is deterministic and cheap. A 🟡 against a technical principle is exempt as principle, because its audience value scores low and the bar would drop every one. A 🟢 against a principle is scored like any other finding. 2026-10-08, lilleman: the goal weights in todo.md depart from an even spread by position, which would weigh goal 4, leaking nothing, at 0.11. Valid while one human sets the bar and reads the ranking, and while the items marked principle stay few enough to rank.
settings.json: Claude Code runs in auto mode with the dangerous-mode prompt skipped
2026-10-04, lilleman, answering the principles audit of PR #215. Serves goal 1: this setup is meant to run in a sandbox and to work autonomously, so tool access is granted by the sandbox, as "Always grant explicit access to data" in principles/technical-principles.md asks. Valid while every machine taking this checkout is such a sandbox.
the repo may name bender, bender-infra and ai-sandbox
2026-10-04, lilleman, answering the principles audit of PR #215. Serves goal 4, which keeps credentials, transcripts and memory files off the remote; the names of the host, its infrastructure project and the sandbox VM are none of those. Valid while the repo names them without their addresses or credentials.
reading cost: larv-review measures each finished chunk from loop-claude's archive and appends the figure to docs/reading-cost.md in the next chunk's PR
2026-10-08, lilleman. Serves goal 1.1: comprehension measured from real work, at no model cost (goal 1.4). loop-claude archives from the main checkout, outside any PR, so a tracked file it wrote there would dirty that checkout. So bin/reading-cost measures each finished chunk docs/reading-cost.md lacks from the archive, in the next chunk's worktree. The figures keep a file of their own, so docs/comprehension-history.md keeps one writer, the scoring run. A PR that never merges then loses no figure, and loop-claude needs no change. Serves goal 4 by naming only files git tracks, and token counts. Rejected: loop-claude opening a PR of its own, one more PR per chunk and a tie to the forge; the worker measuring its own transcript before merging, which misses the chunk's tail. The figure counts new input tokens, uncached and cache-written, because workers read mostly through Bash and subagents, where parsed paths alone miss what they read. Valid while loop-claude archives every finished chunk with its subagents' transcripts.
reading cost: a rise is the last 5 chunks' median above the 5 before them, and files or refreshes one plan item
2026-10-08, lilleman. Serves goal 1.1: comprehension never falls, so any rise counts. Per-chunk figures are noisy: a flat trend rises about every other chunk. So a rise refreshes the item and never refiles it, and a chunk that sees no rise leaves the item as it is. The chunk that ships the item resets the trend, so later figures do not refile it for work that chunk already did (goal 1.4). A median, because one chunk that ran a panel of readers before its first commit measured 2.99M tokens against a typical 80k–370k, and a mean let it decide the trend alone. No published standard sets this threshold. Valid while figures arrive once per chunk.