Files
claude-config/docs/decisions.md
T

21 KiB
Raw Blame History

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 at 8585257: 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 the paired ruling cancels.
  • 2026-10-08, PR #225: 7.25, 6.75, 7.00, 6.88, 6.88. Above PR #224's run on every score but Shape, which held.
  • 2026-10-08, PR #228: no scoring run; its last paired ruling, against 12d6d75, was worse, 2 votes to 0. lilleman shipped it below the ratchet: the seats blamed the new ratchet's own rules, since moved into the tested bin/larv-review.
  • 2026-10-08, PR #229: no scoring run; its last paired ruling, against 12d6d75, was worse, 2 votes to 0. lilleman shipped it below the ratchet for PR #228's reason: the seats' decisive places were still PR #228's rules, since moved into bin/larv-review.

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 🟡 reruns the pass that found it and each pass whose trigger names fixes like it; a fix for a 🟢, a ❓ or a prose finding reruns none

2026-10-08, lilleman, replacing the 2026-09-30 rule that every fix, a nit's included, re-enters review. Serves goal 1.4. An audit of the four costliest archived chunks (2026-10-08) found nearly every finding that mattered in a pass's first round; later rounds mostly re-checked the last fix, reworded what an earlier round wrote, or contradicted another round on the same line. A round 2 caught real bugs only where a fix changed behaviour, so stability still reruns on every fix that does, and security on every fix that opens an untrusted-input boundary or touches authn/authz, secrets or crypto. Valid while round-2 reviews of nit and prose fixes keep changing nothing a user would notice.

review: a paired ruling against the last measured commit decides the ratchet; the four-seat scoring run checks the floor when a release's items run out or an item names the floor

2026-10-08, lilleman. Serves goals 1.1 and 1.4. Two independent four-seat runs moved up to 0.4 on near-identical code, so a fall within that noise forced rounds that changed nothing (PR #224). A seat reading both versions judges the difference on the same material, so the noise the versions share cancels. No conventional significance level lets a sign test settle with four votes, so the human chose a lead of two votes over every other ruling, same included. Two seats that agree settle it, so a PR that leaves the reading as it was costs two seats. A third seat alone can never settle it, so the third and fourth launch together. The base is the default branch's newest merged change that adds a scoring run to the history, or whose last added paired ruling is better. The human chose the last measured commit on the architect's finding that with a merge base as the base, chunks without an architecture pass, and a suspended restructure's steps, could each lower comprehension unseen. A ruling of same leaves the base where it was, or a run of small falls each ruled same would add up unseen. A scoring run moves it too: otherwise a project never ruled better would compare against its first ruling forever, and a release's floor check is where the human sees the absolute level. Reading the default branch one merged change at a time keeps the rule working for merge commits and squash merges alike: a branch's own early ruling of better never counts, only the merged change's last ruling. The scoring run also runs on a chunk shipping an item that names the floor, so the chunk that lifts a project to the floor can prove it. A chunk that removes a release's last item without shipping it runs it too, so no release ends unmeasured. Valid while seats reading both versions agree more often than two absolute runs do.

review: a project decision may suspend the comprehension check 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. 2026-10-08: the paired ruling replaced the scoring run in most chunks, and the suspension covers it too; the ruling after the last step compares with the commit measured before the first step. 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, except where the full scan runs on the same change and replaces it

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.

2026-10-08, lilleman. Serves goal 1.4: run beside the full scan, /security-review started seconds apart from it each round and returned a near-identical report. Valid while the full scan covers what /security-review reports.

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. A PR that never merges then loses no figure, and loop-claude needs no change. The figures keep a file of their own, so docs/comprehension-history.md keeps one writer, the comprehension check. 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.