16 KiB
Decisions
larv-review: a project under the comprehension floor is fixed at the capping dimension
2026-09-20, lilleman. Serves goal 4. Across six projects scored with the four seats, Locality or Self-sufficiency capped every seat and Navigation capped 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 and docs/decisions.md; the worker's own account of which goal settles a choice decides nothing
2026-09-21, lilleman. Serves goal 4. 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 4.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 4.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.
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 4. 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 4. 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 1. 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 4. 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 4. The 2026-09-28 run, Junior A, Mid A, the maintainability senior and the inherited architect at depth 1 over every non-test file, blind to todo.md and this log, scored Navigation 7.25, Locality 6.0, Shape 6.5, Self-sufficiency 6.25, overall 6.25; on 2026-09-26 they were 7.75, 6.25, 7.0, 6.75, 6.75. Every seat scored Locality 6, and three of four named run_cycle's three-way return and larv-review's re-entry rules, split across the passes on 2026-09-28. The same seats on rebuild scored 7.5, 6.63, 6.88, 6.5, 7.0 at 37edc9a, later that day, 7.5, 6.75, 6.88, 6.75, 7.0 at 7f9de5c, 7.38, 6.25, 6.88, 6.75, 6.88 at 2f9ab2f on 2026-09-29, Locality lowest again and every seat naming the reload state and the two retry counters, and 7.5, 7.0, 7.25, 6.75, 7.13 at 2c74bbc later that day, Self-sufficiency lowest and every seat naming the round's definition split across larv-review's two files, and 7.38, 6.75, 7.25, 6.5, 6.88 at 8585257 on 2026-10-01, lowering every dimension but Shape, and the overall, Self-sufficiency lowest and every seat naming larv-review §3's round rules; the places it named under Self-sufficiency and Locality are filed in todo.md under 0.1.0, and a later scoring run may not score any dimension or the overall below its best run on rebuild, 2026-10-01, lilleman. rebuild merged into main under the floor at 8585257's scores, 2026-10-01, lilleman. The 2026-10-01 run on PR #182 (the loop state machine) scored 7.5, 6.5, 6.88, 6.25, 6.38; lilleman shipped that PR under the floor and below rebuild's best run the same day, its places filed in todo.md under 0.1.0. The 2026-10-02 run on PR #187 (loop_claude's names, the exit contract) scored 7.75, 7.25, 7.38, 6.88, 7.25 at 70362d0, every seat naming larv-review §3 under Self-sufficiency, and 7.63, 7.13, 7.38, 7.0, 7.13 at 1971dba later that day, the first run at the floor, with no dimension or the overall below its best run on rebuild. The 2026-10-02 runs on PR #191 (the status line in Python) scored 7.5, 7.0, 7.13, 6.88, 7.13; 7.25, 6.75, 7.25, 6.88, 7.0; 7.63, 6.88, 7.38, 7.0, 7.13; and 7.63, 7.0, 7.25, 6.75, 7.25. Every seat rated the status line easy. The places they named under Locality and Self-sufficiency are filed in todo.md under 0.1.0, except entries.py's heuristics over Claude Code's transcript format, which the seats scored as the problem's own difficulty. lilleman decided the same day to ship that PR under the floor. The 2026-10-02 runs on PR #194 (each cycle's transcript archived) scored 8.0, 7.25, 7.38, 7.13, 7.5 at 6ccd5b1 and 7.75, 7.13, 7.25, 7.0, 7.25 at d104ea0, both at the floor, every seat naming archive as the unit it would least want to modify. On 2026-10-02, applying todo.md's bar deleted every place these scoring runs filed except larv-review §3's round rules and the Claude Code flags no comment explained. The 2026-10-02 runs on PR #196 (todo.md as one scored table) scored 7.63, 6.88, 7.25, 6.88, 7.13 at c0dba66; 7.5, 6.88, 7.13, 6.75, 7.0 at 798dfd7; and 7.5, 7.0, 7.0, 6.75, 7.0 at b712076. Under Self-sufficiency, every seat named larv-review §3 and the agents, which a reader follows only with CLAUDE.md open. lilleman decided the same day to ship that PR under the floor; the place filed was larv-review §3's round rules. The 2026-10-02 run on PR #198 (a usage limit waited out) scored 7.63, 6.88, 7.38, 6.75, 7.13 at 8e85033. Under Self-sufficiency, every seat named larv-review §3; under Locality, they named archive's invariants spread over session.py and run.py, rank_todo.py reaching into premises.sections, and stopped comparing reason strings, each under todo.md's bar and not filed. lilleman decided the same day to ship that PR under the floor.
The 2026-10-03 runs on PR #202 (the judge reads the project's records) scored 7.75, 7.13, 7.25, 7.0, 7.25 in the first round and 7.5, 7.0, 7.0, 6.75, 7.0 in the eighth; between them a dimension moved by up to 0.4 on near-identical code. Under Self-sufficiency every seat named larv-review §3 and the agents leaning on CLAUDE.md, the Claude Code flags left unexplained, and the judge's contract spread over its prompt, schema, parser and --help; under Shape, that "record", "verdict" and "judge" each name two things, and that loop_claude/ holds modules rank_todo.py also uses. lilleman decided the same day to ship that PR under the floor and to fix those places next; all were fixed on 2026-10-03. Valid until the next scoring run, which uses the same four seats.
loop-claude: each project's model lives in ~/.claude/loop-claude-models.json, which only loop-claude writes
2026-09-26, lilleman. Serves goal 4. 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 1 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 4.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 4. 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 4: 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 pass skips only on a precedent, a decision or plan item the repo held before the chunk began
2026-09-30, lilleman. Serves goal 4: 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 2 and 4: 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 4. 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 4: 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 4.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 4.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 3, 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 4: 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 4.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. Valid while one human sets the bar and reads the ranking, and while the items marked principle stay few enough to rank.