Have the worker implement the simplest change without loading the technical principles, and move the rules only reviewers apply to larv-review's standards

This commit is contained in:
2026-10-13 01:15:59 +02:00
parent 8bbc07d9e9
commit 854747f68d
22 changed files with 115 additions and 115 deletions
+2
View File
@@ -61,6 +61,8 @@
!skills/comprehension-panel/*.md
!skills/larv-review/
!skills/larv-review/*.md
!skills/larv-review/standards/
!skills/larv-review/standards/*.md
!workflow-bench/
!workflow-bench/bench.py
!workflow-bench/compare-prompt.md
+3 -2
View File
@@ -3,7 +3,7 @@
Decisions live in `docs/decisions.md`:
- larv-review: a project under the comprehension floor is fixed at the lowest dimension
- loop-claude: a judge decides each interrupt and each quoted answer from the transcript, the README's premises, `AGENTS.md`, `docs/decisions.md`, `~/.claude/CLAUDE.md` and `~/.claude/rules/`, 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
- loop-claude: a judge decides each interrupt and each quoted answer from the transcript, the README's premises, `AGENTS.md`, `docs/decisions.md`, `~/.claude/CLAUDE.md`, `~/.claude/rules/` and larv-review's standards, 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
- loop-claude: one session per project, its id derived from the checkout's path relative to `~/code`, or to `/` outside it
- loop-claude: before an interrupt, it marks the checkout and each of its worktrees trusted in `~/.claude.json`
- bin/: the tests rerun themselves on a `uv`-fetched Python at README Install's floor
@@ -29,7 +29,8 @@ Decisions live in `docs/decisions.md`:
- 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
- reading cost: a rise is the last 5 chunks' median above the 5 before them, and files or refreshes one plan item
- rule-hook: a PreToolUse hook enforces each rule a program can check, a `# rule-override <rule>: <reason>` marker overrides one, and larv-review's overrides pass rules on each override before merge
- rules/: `CLAUDE.md` holds the rules no file path can scope, and each topic's rules live in a `rules/` file that Claude Code loads by its `paths:` frontmatter
- rules/: `CLAUDE.md` holds the worker's rules that no file path can scope, and each topic's rules for the worker live in a `rules/` file that Claude Code loads by its `paths:` frontmatter
- worker: a chunk's worker implements the simplest change that solves its item and reads no technical principle; larv-review's reviewers hold the change to the principles and to the standards in `skills/larv-review/standards/`
## Working rules
+1
View File
@@ -2,6 +2,7 @@
## Unreleased
- A session implements the simplest change that solves its item and reads no technical principle; larv-review's reviewers hold the change to the principles, and each finding names the principle it applies. `CLAUDE.md` keeps a short core of "Prose". "Quality", the rules for comments and READMEs, 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` no longer has "Maintaining this file". The rules for a README's Goals and Audience load from `rules/goals-and-audience.md`.
- `CLAUDE.md` keeps only the rules no file path can scope. The rules for `todo.md` items, comments, decisions and READMEs 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`, and the prose and stability reviewers read them where they once read `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.
+10 -35
View File
@@ -4,44 +4,30 @@
How work proceeds in any repo, unless the repo's `AGENTS.md` says otherwise. The *next release* is the earliest one not yet cut. Other words, such as *chunk*, are defined under "Vocabulary" at the end of this file.
- **Until `README.md` has a `## Goals` and an `## Audience` section, writing them is the only work.** Not even planning in `todo.md`. Both are public: an outside reader judges a project by where it is heading and who it is for. Goals or an audience written anywhere else, such as `AGENTS.md` or `docs/`, do not count. How to write them: `~/.claude/rules/readme.md`.
- **Plan `todo.md` as one scored table**, per `~/.claude/rules/todo-items.md`: every item names the release that ships it. If `todo.md` has another shape, reshaping it is the chunk, and the human approves it.
- **Until `README.md` has a `## Goals` and an `## Audience` section, writing them is the only work.** Not even planning in `todo.md`. Both are public: an outside reader judges a project by where it is heading and who it is for. Goals or an audience written anywhere else, such as `AGENTS.md` or `docs/`, do not count.
- **Plan `todo.md` as one scored table**: every item names the release that ships it. If `todo.md` has another shape, reshaping it is the chunk, and the human approves it.
- **When the next release has no items and no work has landed towards it, plan it as this chunk.** Move the highest-scoring items of later releases into it, and get the human's approval of that set before writing any code.
- **When the next release has no items left and work has landed towards it, it is finished: stop.** Report what it holds and that it is ready to cut. Under `/loop`, this ends the loop. Until the human cuts it, only a security fix lands, into that release; never start a later release's items or plan a new one.
- **Open every chunk with one line:** the last version cut, what is unreleased (`CHANGELOG.md` → `## Unreleased`, or else the log since the last tag), and the release this chunk ships into. A repo that publishes nothing says so once.
- **Work one chunk at a time, and make it as large as one purpose allows.** Every review has a fixed cost, so a chunk takes the next plan item plus every other item for which three things hold: one PR title states what they achieve together, without listing them; they name one release; and they fire the same review passes (`larv-review` §3). Tiny items, a few lines of change each, need neither a shared purpose nor the same passes: bundle up to ten that name one release into one chunk. Split a milestone into items in `todo.md` before starting it. Fix a finding in the chunk's own change within the chunk. File a finding about anything else in `todo.md`. An item marked `question` waits for the human; take the next item.
- **Ask, don't guess.** First check whether the goals already answer the question. If they nearly do, propose a change to the goals and show how it answers this case: an answer settles one question, a goal settles every question like it. Write every answer once, where it belongs, never only in chat: a goal in `README.md`, a working rule in `AGENTS.md`, a standing choice in a comment at the one place it governs, or in `docs/decisions.md` once made in more than one place (`~/.claude/rules/decisions.md`). When an answer holds a goal and a choice, write the goal in the README, and record as a choice only what the goal leaves open.
- **Ask, don't guess.** First check whether the goals already answer the question. If they nearly do, propose a change to the goals and show how it answers this case: an answer settles one question, a goal settles every question like it. Write every answer once, where it belongs, never only in chat: a goal in `README.md`, a working rule in `AGENTS.md`, a standing choice in a comment at the one place it governs, or in `docs/decisions.md` once made in more than one place. When an answer holds a goal and a choice, write the goal in the README, and record as a choice only what the goal leaves open.
- **Bench a syntax with the people who write it.** Before a new or changed spelling of something users read or write ships — markdown, HTML, a config key, a CLI flag — a panel of fresh-context readers, seated as those users from the README's `## Audience`, picks it.
- **Ship every chunk with `/larv-review`.**
- **Implement the simplest change that solves the item, and ship it with `/larv-review`.** Its reviewers hold the change to the technical principles, each finding naming the principle it applies, and you fix what they find. Read no file under `~/.claude/principles/` unless the item changes it.
- **Remove a finished item's row and detail from `todo.md`, and revise any decision that cites it.** If the repo publishes something others consume — a package, an image, an API — reword the item for them and move it to `CHANGELOG.md` under `## Unreleased`. A changelog is for the public, never for the next agent. Otherwise delete it; git history is the record.
- **Releases are the human's.** The version bump and the publishing credentials are theirs, whatever another rule says. Prepare everything else, so cutting a release is one decision.
- **Releases follow semver read strictly** (`~/.claude/principles/technical-principles.md`).
- **Open each `todo.md` item or ticket with a bold one-sentence tagline**, so the taglines alone say what a release holds. The tagline states the target state, checkable when done: an imperative verb plus what holds afterwards. A present-tense fact reads as the current state and says nothing about what to do. Add "today X" only where the direction is otherwise ambiguous. GOOD: `**Accept undefined in MetadataValue and drop such keys on output.**` BANNED: `MetadataValue accepts undefined; such keys are dropped on output`.
- **File a security finding the moment it is found.** A security finding — a leaked credential, secret or PII, an auth bypass, an injection — goes under the next release, marked `security`, naming the exposure and the path it reaches. `~/.claude/bin/rank_todo.py` ranks it first in its release. Never among additive or nice-to-have items, never only in a chunk's summary, and never as a question about where it belongs: file it, say you did, and I will unmark it if I disagree. Fixing it inside an unrelated change is a separate call — say whether it is in the blast radius.
## Quality
Quality is proven by review. Every change is reviewed as a diff. The whole project is measured when a change carries an architectural decision, and before each release, because a project can drift from the principles one clean diff at a time. `larv-review` §3 says which review runs when. Quality has three parts. When two pull against each other, the earlier one wins.
1. **Correct.** The work does what the goals and the plan say, and tests prove it.
2. **True to the technical principles** (`~/.claude/principles/technical-principles.md`). `larv-review`'s comprehension check (§3 → "Architecture") measures KISS.
3. **Plainly written**, per "Prose".
### A false claim is a bug
Docs, comments and what a program prints — `--help`, an error, a log line — assert checkable things: a command, a resolution rule, a path, a limit. Verify one before you repeat or build on it. When it is wrong, correct it in the same change: the claim — or the code, when consumers already rely on what the claim promises. Never work around it or record the discrepancy elsewhere.
## Prose
Everything written — chat, commit messages, comments, docs, code — is in **English**. Prose meets four priorities, in this order. When two pull against each other, the higher one wins.
1. **Easy to understand.** A reader with little time gets it on one read. Keep each sentence to one idea. Explain a term before using it, or use a plainer word. Never fold a clause into a noun phrase to save words. BANNED: `An empty earliest unreleased release with nothing shipped toward it is planned as this chunk`. GOOD: `When the next release has no items and no work has landed towards it, plan it.`
2. **Most important first**, judged by what this document's reader wants to know first. Put the most important section first. Within each section, put the most important paragraph first, and within each list the most important item. Order matters most in long documents; in a short one, don't spend a fix on it.
3. **Default to delete.** Keep a line, of prose or code, only if a reader needs it and nothing else already says it. Adding words is a deliberate act: name what a reader could not understand without them.
1. **Easy to understand.** A reader with little time gets it on one read: one idea per sentence, and each term explained before it is used.
2. **Most important first**, judged by what the reader wants to know first.
3. **Default to delete.** Keep a line, of prose or code, only if a reader needs it and nothing else already says it.
4. **Short.** Cut whatever does not clearly help 1–3.
- **Write the thing, not an introduction to it.** A sentence announcing what follows, or flagging that it deserves attention, carries nothing — if it matters, it is in what follows. A bare label is fine. BANNED: `Here's the new audience text, which is the part that needs your eye:`, `One thing I changed that deserves your attention.`, `One judgment call I'd flag rather than bury.`, `Three things came along that would otherwise have been left false.` GOOD: `New audience text:`, or the list alone.
- **No contrastive tail.** `X rather than Y`, `not Y but X`, `instead of Y`: state X and stop. The rejected alternative is noise unless naming it stops a reader doing Y. BANNED: `verified in CI rather than asserted`. GOOD: `verified in CI`.
Write the thing, not an introduction to it. State what holds and stop, without the alternative you rejected.
## Public API specs
- Text in public API specs (OpenAPI `description`/`title` fields, in a spec file or in code, and the generated api-docs) is read by external consumers. Never leak internal references: no ticket IDs, internal URLs, repo/system code-names, "see ticket X". Describe behaviour in consumer terms. GOOD: `Deprecated alias for paymentAccountId`. BANNED: `…will be removed (ABC-123)`.
@@ -51,9 +37,8 @@ Everything written — chat, commit messages, comments, docs, code — is in **E
Claude Code loads a rule file when a session reads or writes a file its `paths:` frontmatter matches, and after a write only once the write is done. Read a rule file before you create a file it covers.
- Comments, where a choice goes, and what earns a place in a doc: `~/.claude/rules/comments.md`.
- The decision log: `~/.claude/rules/decisions.md`.
- README goals and audience, and what a README or a package's README holds: `~/.claude/rules/readme.md`.
- README goals and audience: `~/.claude/rules/goals-and-audience.md`.
- `todo.md` items, their scores and Exempt reasons: `~/.claude/rules/todo-items.md`.
## Working with the codebase
@@ -62,23 +47,17 @@ Claude Code loads a rule file when a session reads or writes a file its `paths:`
- Run a project's language runtime, package manager, and task runner through its container/tooling setup, never directly on the host unless a decision puts them there. Example: `docker compose run --rm app <tool> …`.
- Tear down test containers after a run.
- Give a subagent only the access its job needs, and state the limits in its prompt. One that only reads, such as a prose review, gets no shell and no edits. One that probes a build tags the image as throwaway and removes it afterwards, writes only to the session scratchpad, and removes no image or file it did not create.
- Check `README.md` first for build, test, install, and codegen commands; one that misbehaves is fixed per "A false claim is a bug". Refresh `README.md` whenever you change what it describes (`~/.claude/rules/readme.md`).
- Sort wherever order carries no meaning (`~/.claude/principles/technical-principles.md`) — attributes, array and object keys, enum members, imports, table rows and line-based file lists. Exception: `id` goes first.
- Check `README.md` first for build, test, install, and codegen commands, and fix one that misbehaves in the same change. Refresh `README.md` whenever you change what it describes.
- Where `~/.claude/bin/rule-hook` does not check it, such as an image named in test code, a Kubernetes manifest, a `docker run` line or a file a Bash command writes, pin a container image to its full patch version and a GitHub Action to a semver tag.
## Naming files & folders
- Name by what's inside. BANNED: `scripts`, `utils`, `helpers`, `misc`, `common`, `lib`, `stuff`. GOOD: `e2e-tests/`, `db-migrations/`, `release-tooling/`.
- Group related artifacts by purpose — e2e compose files, e2e Dockerfile, and e2e test scripts all belong in `e2e-tests/`.
## Technical principles
The rules every project follows, compose-not-entangle first: `~/.claude/principles/technical-principles.md`. Read it before writing, designing or reviewing code.
## Git, commits, and PRs
- Mark no commit, PR, issue comment or file as the work of Claude, Anthropic or an agent.
- Commit message and PR title: **one line**, prefixed with the ticket ID when the work has one. Example: `ABC-123 - Regression tests for GET /v4/clients`. Never include the repo/project name (like "twu-4") — we're already in that context.
- PR summary: short and concise. No test plan (it lives in the ticket), no link to the ticket (it's in the title).
- When the work has a ticket, read it before starting: verify the change matches it and pull useful context from it.
- Branch for a ticket: exactly the ticket ID, nothing more. `ABC-123`, never `ABC-123-some-description`.
- Use `gh` on GitHub remotes and `tea` on Gitea remotes (e.g. `gitea.larvit.se`) — same command shape: `tea pr list|create`, `tea issue`, `tea release`, `tea api`. Everything in this section applies to both.
@@ -90,10 +69,6 @@ The rules every project follows, compose-not-entangle first: `~/.claude/principl
- **A list or threshold a consumer relies on is sourced.** Deny-lists, defaults, limits: follow a published standard or a widely deployed tool, and cite it in the decision recording the choice; where none exists, ask. Never assemble one from names that seem plausible.
- When a page renders client-side and comes back empty/blocked, use the Playwright renderer at `~/code/playwright-for-agents/` — `./pw <url> [options]` (see its README). Don't use claude-in-chrome for this.
## Maintaining this file
- When you spot a pattern in how I work that isn't written here or under `~/.claude/rules/` — a preference I've repeated, a correction I've given more than once, a convention you inferred from my code — tell me and ask me to write it up here or under `~/.claude/rules/`. Don't add it silently, and don't just keep it in a memory file.
- After every change to this file or a file under `~/.claude/rules/`, re-read all of them and restructure them: merge overlapping rules, cut prose that restates a rule, move each rule to the file and section it belongs in, drop what's now covered elsewhere. Same information, easier to read and shorter.
## Vocabulary
- **chunk** — the unit of work, shipped as one PR; "Working loop" says what it holds.
+2 -2
View File
@@ -6,7 +6,7 @@ tools: Read, Grep, Glob
You read the prose as someone who did not write it: you see only what it says, never what the author meant.
The bar: `~/.claude/CLAUDE.md` → "Prose" and "Public API specs", and every file under `~/.claude/rules/` whose `paths:` frontmatter matches a file the diff changes. Read them each time — they change. Verdict, severities and rounds: ~/.claude/skills/larv-review/review-findings.md.
The bar: `~/.claude/CLAUDE.md` → "Prose" and "Public API specs"; every file under `~/.claude/skills/larv-review/standards/` but `quality.md`, whose "A false claim is a bug" alone applies; and every file under `~/.claude/rules/` whose `paths:` frontmatter matches a file the diff changes. Read them each time — they change. Verdict, severities and rounds: ~/.claude/skills/larv-review/review-findings.md.
## Checks, in priority order
@@ -14,7 +14,7 @@ Run them in this order. A fix for a later check never breaks an earlier one.
1. **Easy to understand.** Read each sentence once, cold. A sentence you had to reread, a term used before it is explained, or an "it" or "them" that could point at two things is a finding. Fix: **Rewrite**, giving the plain sentence.
2. **Most important first.** Name the document's reader and what they want to know first. Check that the sections run in that order, then the paragraphs within each section, then the items within each list. If not, fix: **Reorder**, naming the new order. A section so long that a reader has to search it gets sub-headings or an index. Fix: **Split**.
3. **Default to delete.** A line the reader does not need fails. Fix: **Delete** what the code, a type, a test name, the README or another rule already says. Fix: **Move** a choice made in one place to a comment there, one made in more places to `docs/decisions.md` with its title in `AGENTS.md`, and a goal to the README. A pointer standing where a definition belongs (`~/.claude/rules/comments.md` → "Links and pointers", "A pointer is not a definition") gets the fix **Move back**: inline the definition, and leave the reasoning where it is.
3. **Default to delete.** A line the reader does not need fails. Fix: **Delete** what the code, a type, a test name, the README or another rule already says. Fix: **Move** a choice made in one place to a comment there, one made in more places to `docs/decisions.md` with its title in `AGENTS.md`, and a goal to the README. A pointer standing where a definition belongs (`~/.claude/skills/larv-review/standards/comments.md` → "Links and pointers", "A pointer is not a definition") gets the fix **Move back**: inline the definition, and leave the reasoning where it is.
4. **Short.** Words that do not clearly help 1–3 fail. Fix: **Cut**.
Also report a sentence contradicting another, a claim the code shows false, and a word used against `CLAUDE.md` → "Vocabulary".
+3 -3
View File
@@ -10,7 +10,7 @@ You are an elite stability-focused code reviewer with deep expertise in defensiv
## First Steps
1. **Scope the change.** You review every PR; a fresh invocation has no prior context, so determine the diff yourself. Diff the PR branch against its base (`gh pr diff`, or `git merge-base <base> HEAD` then `git diff`), and review the changed lines **plus enough surrounding code and callers** to judge correctness — read the whole changed file when practical; a diff alone hides whether a caller breaks. Read the PR description and, when the project uses an issue tracker (project-specific — check its docs) and the change references a ticket, that ticket: the diff is judged against its stated intent, and a scope mismatch in either direction is a finding — claimed-but-unimplemented, and implemented-but-unasked (#2).
2. **Read every file in the shared principles** at `~/.claude/principles/`. These are mandatory org guidelines; all code MUST comply with each that applies. A file's `Applies to` line says what it covers; one without the line covers every change. Re-read each time — they change. Flag violations prominently.
2. **Read every file in the shared principles**, and `~/.claude/skills/larv-review/standards/quality.md`, at `~/.claude/principles/`. These are mandatory org guidelines; all code MUST comply with each that applies. A file's `Applies to` line says what it covers; one without the line covers every change. Re-read each time — they change. Flag violations prominently.
3. **Read README.md, AGENTS.md and `docs/decisions.md`** in the current project for project-specific conventions, build instructions, tooling, and the accepted trade-offs a reviewer should honor rather than re-flag. Note the documented test, lint, and static-analysis commands — you will run them.
4. **Verify, don't just read.** Run the test suite and static analysis/linters through the project's container tooling, unless a decision puts them on the host; tear down test containers afterwards. A full-suite run catches broken callers that diff-reading misses. When a suspected bug is cheap to confirm, reproduce it — a scratch script, a targeted test run — before reporting it. Put scratch work in a directory you create for this run, and delete it when done; delete nothing else, since a directory the prompt names may hold other agents' files. Leave the working tree exactly as you found it. Anything you could not run goes in Coverage & Verification, never silently skipped.
5. **Two passes minimum, then hunt absences.**
@@ -110,9 +110,9 @@ Every PR gets at least this sweep.
- Is naming precise and unambiguous?
- **Does every name in the diff still match its (possibly changed) contents?** When a change meaningfully shifts what a file/folder/package/service/variable does, its name must be updated in the same change — flag a stale name left behind by a content/purpose shift (e.g. a `webhook` test helper reworked into a JWT verifier but still called `webhook`/`WEBHOOK_URL`). The rename belongs in the PR, not "later."
- Are magic numbers/strings replaced with named constants?
- **Judge every comment and prose line the diff adds against every file under `~/.claude/rules/` whose `paths:` frontmatter matches its file**; report a density breach with the ratio and the files driving it.
- **Judge every comment and prose line the diff adds against `~/.claude/skills/larv-review/standards/comments.md`, against `readme.md` beside it for a README, and against every file under `~/.claude/rules/` whose `paths:` frontmatter matches its file**; report a density breach with the ratio and the files driving it.
- **Flag a caveat the diff has outlived**, anywhere in the repo: report the sentence's `file:line` and the behaviour that replaced it.
- **Flag a pointer standing where a definition belongs** — `~/.claude/rules/comments.md` → "Links and pointers", "A pointer is not a definition".
- **Flag a pointer standing where a definition belongs** — `~/.claude/skills/larv-review/standards/comments.md` → "Links and pointers", "A pointer is not a definition".
- **Never propose new documentation as a "nice to have".** Suggesting a doc paragraph is proposing bulk someone must maintain. Raise it as a 🟡 only when its absence would actively mislead someone, and say which mistake it prevents; otherwise don't raise it at all. Deleting redundant prose is always the cheaper fix.
- **Never let documentation stand in for a fix.** A finding is not closed by describing the defect in a README, and neither is one of yours: if the only available remedy is telling the reader, say so and mark it a decision for the human, so it lands in the PR or ticket where a decision record belongs. Naming a residual risk is your job; choosing to publish it in the repo is not yours to hand out.
+3 -3
View File
@@ -7,7 +7,7 @@ from loop_claude.cycle.prompts import ANSWER_DESTINATIONS, ANSWERS_RECORDED
from loop_claude.effects import Effects
from failure import Failure
from claude_code.entries import hit_limit, limit_said, parse_entry, structured_output
from loop_claude.project.records import HUMAN_RULES, HUMAN_RULES_DIR
from loop_claude.project.records import HUMAN_RULE_NAMES
from loop_claude.cycle.retry import Limited, retried
from loop_claude.stop import Stop
@@ -39,9 +39,9 @@ JUDGE_RULES = (
"The chunk is the piece of work the agent is on, shipped as one pull request. "
"finished=true when the chunk is complete: merged, or nothing remains that the agent could do on "
f"its own. Even then, it is finished only once {ANSWERS_RECORDED}. An answer counts as recorded "
f"where README.md or the records above hold it, {HUMAN_RULES} and {HUMAN_RULES_DIR} included. It also counts where "
f"where README.md or the records above hold it, {', '.join(HUMAN_RULE_NAMES)} included. It also counts where "
f"the transcript shows the agent writing it into {ANSWER_DESTINATIONS}; writing it into "
f"{HUMAN_RULES} or {HUMAN_RULES_DIR} does not count. finished=false when work remains that a further run can "
f"{' or '.join(HUMAN_RULE_NAMES)} does not count. finished=false when work remains that a further run can "
"continue: an open PR, a review not yet run, CI not yet reported, an answer not yet recorded."
)
+2 -2
View File
@@ -1,8 +1,8 @@
from loop_claude.project.records import HUMAN_RULES, HUMAN_RULES_DIR, RECORD_FILES
from loop_claude.project.records import HUMAN_RULE_NAMES, RECORD_FILES
from markdown_text import quoted
# Where the judge may quote an answer from, named as the human and the worker see them; of README.md the judge sees only the premises.
QUOTE_SOURCES = "README.md's Goals and Audience, " + ", ".join(RECORD_FILES + (HUMAN_RULES,)) + " or " + HUMAN_RULES_DIR
QUOTE_SOURCES = "README.md's Goals and Audience, " + ", ".join(RECORD_FILES + HUMAN_RULE_NAMES[:-1]) + " or " + HUMAN_RULE_NAMES[-1]
# Where the worker may write an answer the human typed, so it counts as recorded.
ANSWER_DESTINATIONS = "README.md's Goals or Audience, " + ", ".join(RECORD_FILES) + ", todo.md or a comment"
ANSWERS_RECORDED = f"every answer the human typed in it that a later chunk could need is recorded in {ANSWER_DESTINATIONS} at the one place it governs"
+5 -5
View File
@@ -5,8 +5,8 @@ usage: loop-claude <task>
Run it anywhere inside a project checkout whose README.md has ## Goals and ## Audience, the
premises; the task runs at the checkout root. Each cycle a worker runs the task. A judge then reads
the transcript's end, the premises, and the records: the project's AGENTS.md and docs/decisions.md,
and the human's ~/.claude/CLAUDE.md and ~/.claude/rules/*.md, where they exist. It rules whether the
chunk, the work of one PR, is finished. A chunk stays unfinished until each answer the human typed in it that a later chunk
and the human's ~/.claude/CLAUDE.md, ~/.claude/rules/*.md and
~/.claude/skills/larv-review/standards/*.md, where they exist. It rules whether the chunk, the work of one PR, is finished. A chunk stays unfinished until each answer the human typed in it that a later chunk
could need is recorded: the premises or the records hold it, or the transcript shows the worker
writing it into the premises, AGENTS.md, docs/decisions.md, todo.md or a code comment. A choice the
worker made that the premises or the records settle is not asked about. When the worker asks a
@@ -44,8 +44,8 @@ loop-claude --help succeeds: the loop reloads into the edited script.
Exit 1, saying why, when:
- no task is given
- git cannot start or finds no checkout
- README.md, or AGENTS.md, docs/decisions.md, ~/.claude/CLAUDE.md or ~/.claude/rules/*.md where they
exist, cannot be read or is not UTF-8
- README.md, or AGENTS.md, docs/decisions.md, ~/.claude/CLAUDE.md, ~/.claude/rules/*.md or
~/.claude/skills/larv-review/standards/*.md where they exist, cannot be read or is not UTF-8
- README.md holds no premises
- the models file cannot be read or written
- claude leaves no transcript
@@ -118,7 +118,7 @@ def run_loop(argv: list[str], env: typing.Mapping[str, str], paths: Paths, launc
premises = read_premises(loop_run.root)
if isinstance(premises, Stop):
return premises
records = read_records(loop_run.root, paths.claude_md, paths.rules_dir)
records = read_records(loop_run.root, paths.claude_dir)
if isinstance(records, Stop):
return records
models = get_or_ask_models(key, paths, env, effects)
+2 -4
View File
@@ -6,11 +6,10 @@ import pathlib
class Paths:
claude_code_transcripts: pathlib.Path
claude_json: pathlib.Path
claude_md: pathlib.Path
claude_dir: pathlib.Path
home: pathlib.Path
model_catalog: pathlib.Path
models_file: pathlib.Path
rules_dir: pathlib.Path
def paths_from(home: pathlib.Path) -> Paths:
@@ -18,9 +17,8 @@ def paths_from(home: pathlib.Path) -> Paths:
return Paths(
claude_code_transcripts=claude / "projects",
claude_json=home / ".claude.json",
claude_md=claude / "CLAUDE.md",
claude_dir=claude,
home=home,
model_catalog=claude / "cache" / "model-catalog",
models_file=claude / "loop-claude-models.json",
rules_dir=claude / "rules",
)
+8 -5
View File
@@ -5,14 +5,17 @@ from loop_claude.stop import Stop
# The records: these project files and the human's rules; the judge reads them beside the README's premises.
RECORD_FILES = ("AGENTS.md", "docs/decisions.md")
HUMAN_RULES = "~/.claude/CLAUDE.md"
HUMAN_RULES_DIR = "~/.claude/rules/"
# The human's rules for every project, under ~/.claude: CLAUDE.md, then each .md file in these folders.
HUMAN_RULES = "CLAUDE.md"
HUMAN_RULE_DIRS = ("rules", "skills/larv-review/standards")
HUMAN_RULE_NAMES = tuple(f"~/.claude/{name}" for name in (HUMAN_RULES, *(f"{folder}/" for folder in HUMAN_RULE_DIRS)))
def read_records(root: str, claude_md: pathlib.Path, rules_dir: pathlib.Path) -> str | Stop:
def read_records(root: str, claude_dir: pathlib.Path) -> str | Stop:
"""The project's record files, then the human's rules for every project, CLAUDE.md first, each headed by its name; a file that does not exist is left out."""
sources = [(root, name, name) for name in RECORD_FILES] + [(str(claude_md.parent), claude_md.name, HUMAN_RULES)]
sources += [(str(rules_dir), rule.name, HUMAN_RULES_DIR + rule.name) for rule in sorted(rules_dir.glob("*.md"))]
rules = [claude_dir / HUMAN_RULES] + [rule for folder in HUMAN_RULE_DIRS for rule in sorted((claude_dir / folder).glob("*.md"))]
sources = [(root, name, name) for name in RECORD_FILES]
sources += [(str(rule.parent), rule.name, f"~/.claude/{rule.relative_to(claude_dir)}") for rule in rules]
records = []
for folder, name, heading in sources:
if not pathlib.Path(folder, name).exists():
+18 -15
View File
@@ -156,7 +156,7 @@ class Transitions(unittest.TestCase):
class QuestionFor(unittest.TestCase):
def test_puts_an_interrupts_question_as_asked_and_a_quoted_answer_past_the_cap_with_its_quote(self):
self.assertEqual(run.question_for(Interrupt("e", "Which one?")), "Which one?")
self.assertEqual(run.question_for(QuotedAnswer("e", "Which one?", "A.")), "Which one?\n\nREADME.md's Goals and Audience, AGENTS.md, docs/decisions.md, ~/.claude/CLAUDE.md or ~/.claude/rules/ says:\nA.\n\nThose files have answered 3 questions this cycle, the most allowed, so this one comes to you.")
self.assertEqual(run.question_for(QuotedAnswer("e", "Which one?", "A.")), "Which one?\n\nREADME.md's Goals and Audience, AGENTS.md, docs/decisions.md, ~/.claude/CLAUDE.md, ~/.claude/rules/ or ~/.claude/skills/larv-review/standards/ says:\nA.\n\nThose files have answered 3 questions this cycle, the most allowed, so this one comes to you.")
class Cycles(unittest.TestCase):
@@ -255,12 +255,12 @@ class Cycles(unittest.TestCase):
with contextlib.redirect_stderr(io.StringIO()) as said, contextlib.redirect_stdout(io.StringIO()) as printed:
self.assertEqual(run.run_cycle(self.cycle(fake, records="From AGENTS.md:\nUse A.")), Stop(2, "the human is needed to answer the question above, but the interrupt ended with nothing typed"))
resumed = fake.made("stream_claude")[1]
self.assertEqual(resumed[resumed.index("-p") + 1], "Your question: Which one?\n\nREADME.md's Goals and Audience, AGENTS.md, docs/decisions.md, ~/.claude/CLAUDE.md or ~/.claude/rules/ answers it:\n\nUse *A*.\n\nContinue the task.")
self.assertEqual(resumed[resumed.index("-p") + 1], "Your question: Which one?\n\nREADME.md's Goals and Audience, AGENTS.md, docs/decisions.md, ~/.claude/CLAUDE.md, ~/.claude/rules/ or ~/.claude/skills/larv-review/standards/ answers it:\n\nUse *A*.\n\nContinue the task.")
self.assertEqual(len(fake.made("stream_claude")), 4)
self.assertEqual(printed.getvalue().count("=== README.md's Goals and Audience, AGENTS.md, docs/decisions.md, ~/.claude/CLAUDE.md or ~/.claude/rules/ answered: Which one? ===\nUse *A*."), 3)
self.assertIn("Which one?\n\nREADME.md's Goals and Audience, AGENTS.md, docs/decisions.md, ~/.claude/CLAUDE.md or ~/.claude/rules/ says:\nUse *A*.\n\nThose files have answered 3 questions this cycle", said.getvalue())
quoted = "2026-09-21T14:13:20Z Verdict: quoted answer\n\nWhich one?\n\nREADME.md's Goals and Audience, AGENTS.md, docs/decisions.md, ~/.claude/CLAUDE.md or ~/.claude/rules/ says:\n> Use *A*.\n\nEvidence:\n> working\n"
self.assertEqual(self.archived_outcomes(), [f"Task: Do it.\n\n2026-09-21T14:13:20Z Verdict: interrupt\n\nWhich one?\n\nREADME.md's Goals and Audience, AGENTS.md, docs/decisions.md, ~/.claude/CLAUDE.md or ~/.claude/rules/ says:\nUse *A*.\n\nThose files have answered 3 questions this cycle, the most allowed, so this one comes to you.\n\nEvidence:\n> working\n\n2026-09-21T14:13:20Z Stopped: the human is needed to answer the question above, but the interrupt ended with nothing typed\n", *[f"Task: Do it.\n\n{quoted}"] * 3])
self.assertEqual(printed.getvalue().count("=== README.md's Goals and Audience, AGENTS.md, docs/decisions.md, ~/.claude/CLAUDE.md, ~/.claude/rules/ or ~/.claude/skills/larv-review/standards/ answered: Which one? ===\nUse *A*."), 3)
self.assertIn("Which one?\n\nREADME.md's Goals and Audience, AGENTS.md, docs/decisions.md, ~/.claude/CLAUDE.md, ~/.claude/rules/ or ~/.claude/skills/larv-review/standards/ says:\nUse *A*.\n\nThose files have answered 3 questions this cycle", said.getvalue())
quoted = "2026-09-21T14:13:20Z Verdict: quoted answer\n\nWhich one?\n\nREADME.md's Goals and Audience, AGENTS.md, docs/decisions.md, ~/.claude/CLAUDE.md, ~/.claude/rules/ or ~/.claude/skills/larv-review/standards/ says:\n> Use *A*.\n\nEvidence:\n> working\n"
self.assertEqual(self.archived_outcomes(), [f"Task: Do it.\n\n2026-09-21T14:13:20Z Verdict: interrupt\n\nWhich one?\n\nREADME.md's Goals and Audience, AGENTS.md, docs/decisions.md, ~/.claude/CLAUDE.md, ~/.claude/rules/ or ~/.claude/skills/larv-review/standards/ says:\nUse *A*.\n\nThose files have answered 3 questions this cycle, the most allowed, so this one comes to you.\n\nEvidence:\n> working\n\n2026-09-21T14:13:20Z Stopped: the human is needed to answer the question above, but the interrupt ended with nothing typed\n", *[f"Task: Do it.\n\n{quoted}"] * 3])
def test_stops_when_a_quoted_answer_cannot_be_archived(self):
self.archive.parent.mkdir(parents=True)
@@ -397,29 +397,31 @@ class Records(unittest.TestCase):
def test_heads_each_record_by_its_name_the_humans_rules_last(self):
with tempfile.TemporaryDirectory() as root:
claude_md = pathlib.Path(root, "home", ".claude", "CLAUDE.md")
self.assertEqual(records.read_records(root, claude_md, claude_md.parent / "rules"), "")
self.assertEqual(records.read_records(root, claude_md.parent), "")
claude_md.parent.mkdir(parents=True)
claude_md.write_text("# Global\n")
self.assertEqual(records.read_records(root, claude_md, claude_md.parent / "rules"), "From ~/.claude/CLAUDE.md:\n# Global")
self.assertEqual(records.read_records(root, claude_md.parent), "From ~/.claude/CLAUDE.md:\n# Global")
pathlib.Path(root, "docs").mkdir()
pathlib.Path(root, "docs", "decisions.md").write_text("# Decisions\n")
pathlib.Path(root, "AGENTS.md").write_text("\n# Rules\n")
self.assertEqual(records.read_records(root, claude_md, claude_md.parent / "rules"), "From AGENTS.md:\n# Rules\n\nFrom docs/decisions.md:\n# Decisions\n\nFrom ~/.claude/CLAUDE.md:\n# Global")
self.assertEqual(records.read_records(root, claude_md.parent), "From AGENTS.md:\n# Rules\n\nFrom docs/decisions.md:\n# Decisions\n\nFrom ~/.claude/CLAUDE.md:\n# Global")
pathlib.Path(claude_md.parent, "rules").mkdir()
pathlib.Path(claude_md.parent, "rules", "todo-items.md").write_text("# Todo\n")
pathlib.Path(claude_md.parent, "rules", "readme.md").write_text("# Readme\n")
pathlib.Path(claude_md.parent, "rules", "notes.txt").write_text("not a rule\n")
self.assertTrue(records.read_records(root, claude_md, claude_md.parent / "rules").endswith("From ~/.claude/CLAUDE.md:\n# Global\n\nFrom ~/.claude/rules/readme.md:\n# Readme\n\nFrom ~/.claude/rules/todo-items.md:\n# Todo"))
pathlib.Path(claude_md.parent, "skills", "larv-review", "standards").mkdir(parents=True)
pathlib.Path(claude_md.parent, "skills", "larv-review", "standards", "comments.md").write_text("# Comments\n")
self.assertTrue(records.read_records(root, claude_md.parent).endswith("From ~/.claude/CLAUDE.md:\n# Global\n\nFrom ~/.claude/rules/readme.md:\n# Readme\n\nFrom ~/.claude/rules/todo-items.md:\n# Todo\n\nFrom ~/.claude/skills/larv-review/standards/comments.md:\n# Comments"))
def test_stops_on_a_record_it_cannot_read(self):
with tempfile.TemporaryDirectory() as root:
claude_md = pathlib.Path(root, "home", ".claude", "CLAUDE.md")
claude_md.mkdir(parents=True)
self.assertEqual(records.read_records(root, claude_md, claude_md.parent / "rules"), Stop(1, f"CLAUDE.md in {claude_md.parent}: Is a directory - the judge cannot read the records."))
self.assertEqual(records.read_records(root, claude_md.parent), Stop(1, f"CLAUDE.md in {claude_md.parent}: Is a directory - the judge cannot read the records."))
pathlib.Path(root, "docs", "decisions.md").mkdir(parents=True)
self.assertEqual(records.read_records(root, claude_md, claude_md.parent / "rules"), Stop(1, f"docs/decisions.md in {root}: Is a directory - the judge cannot read the records."))
self.assertEqual(records.read_records(root, claude_md.parent), Stop(1, f"docs/decisions.md in {root}: Is a directory - the judge cannot read the records."))
pathlib.Path(root, "AGENTS.md").write_bytes(b"# Rules\n\xff\n")
self.assertEqual(records.read_records(root, claude_md, claude_md.parent / "rules"), Stop(1, f"AGENTS.md in {root} is not UTF-8 on line 2 - the judge cannot read the records."))
self.assertEqual(records.read_records(root, claude_md.parent), Stop(1, f"AGENTS.md in {root} is not UTF-8 on line 2 - the judge cannot read the records."))
def test_stops_on_a_rule_it_cannot_read(self):
@@ -428,7 +430,7 @@ class Records(unittest.TestCase):
rules = pathlib.Path(claude_md.parent, "rules")
rules.mkdir(parents=True)
pathlib.Path(rules, "todo-items.md").write_bytes(b"\xff\n")
self.assertEqual(records.read_records(root, claude_md, claude_md.parent / "rules"), Stop(1, f"todo-items.md in {rules} is not UTF-8 on line 1 - the judge cannot read the records."))
self.assertEqual(records.read_records(root, claude_md.parent), Stop(1, f"todo-items.md in {rules} is not UTF-8 on line 1 - the judge cannot read the records."))
class JudgePrompt(unittest.TestCase):
def test_shows_the_transcripts_tail_and_returns_what_it_showed(self):
@@ -513,7 +515,8 @@ class ExitContract(unittest.TestCase):
def test_every_exit_1_stop_has_its_clause_in_help(self):
read, git, premises_ = "a transcript cannot be read or archived", "git cannot start or finds no checkout", "README.md holds no premises"
models_ = "the models file cannot be read or written"
unreadable = f"README.md, or {', '.join(records.RECORD_FILES + (records.HUMAN_RULES,))} or {records.HUMAN_RULES_DIR}*.md where they exist, cannot be read or is not UTF-8"
names = (*records.RECORD_FILES, records.HUMAN_RULE_NAMES[0], *(f"{folder}*.md" for folder in records.HUMAN_RULE_NAMES[1:]))
unreadable = f"README.md, or {', '.join(names[:-1])} or {names[-1]} where they exist, cannot be read or is not UTF-8"
# Every Stop whose code is not a literal 0, 2 or 130, in source order: path, function, code, start of reason, its --help clause.
clauses = [
("cycle/interrupt.py", "interrupt", "1", "entries.reason", read),
+1 -1
View File
@@ -8,7 +8,7 @@ sys.path.insert(0, str(pathlib.Path(__file__).resolve().parents[1]))
from repo_checks.test_python_floor import ROOT
CITATION = re.compile(r'`?(?:~/\.claude/)?(CLAUDE\.md|rules/[\w-]+\.md)`? → ("[^"]+"(?:,? (?:and )?"[^"]+")*)')
CITATION = re.compile(r'`?(?:~/\.claude/)?(CLAUDE\.md|rules/[\w-]+\.md|skills/larv-review/standards/[\w-]+\.md)`? → ("[^"]+"(?:,? (?:and )?"[^"]+")*)')
HEADING = re.compile(r"^#+ (.+?)(?: \(.*\))?$", re.MULTILINE)
LEAD = re.compile(r"^(?:- )?\*\*(.+?)(?:\*\*|[:.](?=\*\*| )| —)", re.MULTILINE)
NAME = re.compile(r'"([^"]+)"')
+14 -4
View File
@@ -4,7 +4,7 @@
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`, `~/.claude/CLAUDE.md` and `~/.claude/rules/`, 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
## loop-claude: a judge decides each interrupt and each quoted answer from the transcript, the README's premises, `AGENTS.md`, `docs/decisions.md`, `~/.claude/CLAUDE.md`, `~/.claude/rules/` and larv-review's standards, 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.
@@ -12,10 +12,12 @@
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.
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: the rules for every project are the human's. 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.
2026-10-13, implementing todo item 95: the judge reads each file under `~/.claude/rules/` whole too, as the `rules/:` decision moved topic rules there, for the reason it reads `CLAUDE.md` whole, and a worker's write to one does not count as recording an answer, as a write to `CLAUDE.md` does not.
2026-10-13, implementing todo item 104: the judge reads each file under `~/.claude/skills/larv-review/standards/` whole too, for the same reason, as the `worker:` decision moved rules there.
## 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.
@@ -141,12 +143,20 @@ lilleman decided to ship each of these under the floor on the day listed. Each l
2026-10-12, lilleman. Serves goals 1.2 and 1.3. Anthropic's best-practices page calls `CLAUDE.md` advisory and hooks deterministic, so a rule that must hold every time moves into `bin/rule-hook`, and `CLAUDE.md` keeps it only where the hook cannot check it. A Claude Code hook ties the check to one vendor ("Prefer the vendor-neutral option", `principles/technical-principles.md`), which is the target itself here: this repo configures Claude Code. What the tie buys: the hook blocks before a write lands, Edit and Write calls included, in every project with no per-repo install; a git `commit-msg` hook sees only commits, and CI sees them only after the push. The hook checks each write, so the agent fixes the line it just wrote; checking the staged diff at commit time would also cover files a Bash command writes, at the cost of later feedback. The marker's spelling was picked by a panel of three fresh readers, two to one. Each override is logged in the checkout's git directory, which is never pushed (goal 4). The plan had loop-claude's judge to rule on overrides inside a loop; lilleman approved larv-review's overrides pass in every run, because it rules before merge and an outrageous override still reaches the human through its ask. Valid while a PreToolUse hook that exits 2 blocks the call and hands its stderr to the model, and while an agent commits through Claude Code's Bash tool.
## rules/: `CLAUDE.md` holds the rules no file path can scope, and each topic's rules live in a `rules/` file that Claude Code loads by its `paths:` frontmatter
## rules/: `CLAUDE.md` holds the worker's rules that no file path can scope, and each topic's rules for the worker live in a `rules/` file that Claude Code loads by its `paths:` frontmatter
2026-10-13, lilleman through todo item 95, implemented by claude. Serves goals 1.3 and 1.4. Every session loaded `CLAUDE.md` whole, about 4,200 words. Anthropic's memory docs (code.claude.com/docs/en/memory) say a longer file "reduce[s] adherence", and IFScale (arxiv.org/abs/2507.11538) measures adherence falling as the instruction count grows. A rule goes in `CLAUDE.md` when no file path marks the moment it is needed: the working loop, prose that chat follows, commits, and API spec text, which may sit in code. Every other topic gets a file under `rules/` whose `paths:` name the files that topic is about.
`rules/comments.md` matches every file. A session that opens no file, such as one answering in chat, leaves it out. A session that writes a file has read one first, since Edit needs a Read, except for a new file written before any read; the "Topic rules" line says to read the rule file first there.
A session that writes a file has read one first, since Edit needs a Read, except for a new file written before any read; the "Topic rules" line says to read the rule file first there. 2026-10-13, todo item 104: the rules a reviewer applies and the worker need not load, those for comments and READMEs among them, moved out of `rules/`, per the `worker:` decision.
Claude Code's user-level rules tie this repo to Claude Code, which "Prefer the vendor-neutral option" (`principles/technical-principles.md`) allows here because this repo configures Claude Code itself. The tie buys topic rules that load without a pointer the session must follow.
Valid while Claude Code loads `~/.claude/rules/*.md` in every project, a path-scoped one when a session reads, writes or edits a matching file, or reads one with a single-file Bash command such as `cat`, and after a write only once the write is done. On 2026-10-13 a smoke test confirmed both triggers: a rule in `~/.claude/rules/` with `paths: ["**/smoke-target.txt"]` held a secret word. `claude -p` in a project under `/tmp` printed the word after reading the target with the Read tool, and after creating it with the Write tool. A control run that opened no file printed none. Per the docs, a path-scoped rule leaves the context at compaction and returns at the next matching read.
## worker: a chunk's worker implements the simplest change that solves its item and reads no technical principle; larv-review's reviewers hold the change to the principles and to the standards in `skills/larv-review/standards/`
2026-10-13, lilleman through todo item 104, implemented by claude. Serves goals 1.4 and 1.5. Like red, green, refactor: the worker makes the item work, and the review passes raise it to the bar. A loop-claude worker loaded `CLAUDE.md` and every file under `rules/`, 4,247 words, and `CLAUDE.md` told it to read `technical-principles.md` too, 2,426 words more. The reviewers read the principles anyway, and each finding names the principle it applies.
The worker keeps what it needs to write its own work. Each project's decision titles stay in its `AGENTS.md`, since a worker that misses a decision builds the wrong behaviour. A core of "Prose" stays in `CLAUDE.md`, since no reviewer reads the worker's chat. lilleman chose both on 2026-10-13. The rules for writing Goals and Audience, `todo.md` items and decisions stay in `rules/`, since writing those is the worker's job. `bin/rule-hook` stays: it blocks what a program can check, at no context cost. "Quality", the rules for comments and READMEs, and the examples behind "Prose" moved to `skills/larv-review/standards/`, which no path loads. The prose and stability reviewers read them, and so does loop-claude's judge.
Valid while review rounds per pass do not rise. A principle found late, such as functional core, can cost a rewrite within a pass's three rounds. `todo.md` item 105 compares rounds per pass and reading cost in loop-claude's archive for the five chunks before and after this one.
+1 -1
View File
@@ -62,7 +62,7 @@
- Defaults live at the program's edge: a CLI, a config file, a library's public API. A library still asks for every input that can change between runs, such as data, the clock and randomness; only the code that wires a program together, such as its CLI, defaults those, as "Functional core, imperative shell" asks.
- BANNED: a CLI that refuses to run until given `--data-path` and `--seed`, when nearly every run wants the shipped data and fresh randomness. GOOD: it uses the shipped data and fresh randomness unless a flag overrides them, and `--help` names those flags.
* Deterministic order wherever order carries no meaning.
- Sort it, on a key that does not move: the name a line introduces, never where it came from. A sorted list is searchable, its diff shows only what changed, and two edits to it conflict only where they mean to.
- Sort it, on a key that does not move: the name a line introduces, never where it came from. Exception: `id` goes first. A sorted list is searchable, its diff shows only what changed, and two edits to it conflict only where they mean to.
- An import sorts on its first binding, not its path, so moving or renaming a module reorders nothing. Where lines already group by kind — type imports, host packages — the key sorts within each group.
* Keep It Simple, Stupid (KISS): keep solutions simple, so a reader new to the project understands each part on one read.
- Keep a size or complexity limit only while the comprehension panel's readers (`~/.claude/skills/comprehension-panel/`) find the code it flags hard.
+9
View File
@@ -0,0 +1,9 @@
---
paths:
- "**/README.md"
---
# Goals and Audience
- **Goals** state the project's aim and intent, not promises: one numbered line each, like slogans, in priority order; a sub-goal is indented under its goal — "1. Blazing fast performance. 2. Correctness is more important than many features." A goal names no step of the work, such as a check to run first, and rarely an implementation. How a goal is met goes in a method section further down the README and names the goal it serves. BANNED as a goal: `Kill weak candidates early, with the cheap checks first.` GOOD: the goal `Keep research on a budget, so it scales in both time and cost.`, with the cheap checks moved to the method section, naming that goal.
- **Audience** names who depends on the project and what they may rely on.
+2 -2
View File
@@ -9,7 +9,7 @@ You orchestrate, fix, and ship; reviewers only report. Run every reviewer synchr
**Forge-neutral.** Five PR operations recur below: read a PR's diff, open a draft PR, read check status, mark ready, merge. Resolve the tooling from the remote per `~/.claude/CLAUDE.md` → "Git, commits, and PRs"; on any other forge, achieve the same intents through its CLI or API — discover how rather than assuming. A forge without a native draft state gets the closest equivalent (a `WIP:`/`Draft:` title prefix); note any approximation in the summary.
Words: `~/.claude/CLAUDE.md` → "Vocabulary". What a reviewer reports: ~/.claude/skills/larv-review/review-findings.md; how you resolve it: §3 → "Findings".
The bar a chunk is reviewed to: ~/.claude/skills/larv-review/standards/quality.md. Words: `~/.claude/CLAUDE.md` → "Vocabulary". What a reviewer reports: ~/.claude/skills/larv-review/review-findings.md; how you resolve it: §3 → "Findings".
**An ask** holds only what it asks about; the rest runs on while it waits. No user reachable (a headless run) → finish the rest, then leave the PR unmerged with the question and your recommendation in the summary, unless the ask's rule names another branch.
@@ -82,7 +82,7 @@ Give a reviewer without Bash the branch diff and `git ls-files`'s output in its
- **Outside the chunk.** A finding outside the chunk's change, whatever its pass or severity, is scored and filed in `todo.md` per `~/.claude/rules/todo-items.md`. A 🔴 is marked `defect`. A 🟡 against a file under `~/.claude/principles/` is marked `principle`, its detail naming the principle, where no other reason fits. One under the bar and not exempt is named in the summary with its score. A verified security HIGH is handled per "Security".
- **Goal or decision.** A fix that would change a goal, or a `docs/decisions.md` entry the repo held before the chunk began, is asked; no user reachable → filed, marked `question`, the goal or decision left as is.
- **🔴.** A 🔴 is fixed, or shown factually wrong, and what disproved it recorded per `~/.claude/rules/comments.md` → "Where a choice goes": in a comment at the code the finding concerns, or in `docs/decisions.md` when it concerns more than one place. Never declined.
- **🔴.** A 🔴 is fixed, or shown factually wrong, and what disproved it recorded per `~/.claude/skills/larv-review/standards/comments.md` → "Where a choice goes": in a comment at the code the finding concerns, or in `docs/decisions.md` when it concerns more than one place. Never declined.
- **🟡.** A 🟡 is fixed, shown factually wrong like a 🔴, or declined. Decline one only where the reason is sound, consistent with the goals and the technical principles, and confidence is very high; the decline and its reason are recorded the same way. A reason neither speaks to is a gap in the goals: fix the finding, or ask per `~/.claude/CLAUDE.md` → "Working loop", "Ask, don't guess"; no user reachable → fix. Never drop one silently, and never decline one for convenience or the size of the fix.
- **🟢 and ❓.** A 🟢 or ❓ is fixed, answered, declined in the summary with its reason, or filed. Answer one where the code, a test, a goal or a decision the repo held before the chunk began settles it, and quote what in the summary. A ❓ only the user can answer is asked; no user reachable → filed, marked `question`.
- **🔀.** A 🔀 runs the named reviewer's pass once the current pass is done.
@@ -1,8 +1,3 @@
---
paths:
- "**/*"
---
# Comments and documentation
## What earns a place
+10
View File
@@ -0,0 +1,10 @@
# Prose, in detail
How a reviewer applies each priority of `~/.claude/CLAUDE.md` → "Prose".
1. **Easy to understand.** Never fold a clause into a noun phrase to save words. Explain a term before using it, or use a plainer word. BANNED: `An empty earliest unreleased release with nothing shipped toward it is planned as this chunk`. GOOD: `When the next release has no items and no work has landed towards it, plan it.`
2. **Most important first.** Put the most important section first. Within each section, put the most important paragraph first, and within each list the most important item. Order matters most in long documents; in a short one, don't spend a fix on it.
3. **Default to delete.** Adding words is a deliberate act: name what a reader could not understand without them.
- **Write the thing, not an introduction to it.** A sentence announcing what follows, or flagging that it deserves attention, carries nothing — if it matters, it is in what follows. A bare label is fine. BANNED: `Here's the new audience text, which is the part that needs your eye:`, `One thing I changed that deserves your attention.`, `One judgment call I'd flag rather than bury.`, `Three things came along that would otherwise have been left false.` GOOD: `New audience text:`, or the list alone.
- **No contrastive tail.** `X rather than Y`, `not Y but X`, `instead of Y`: state X and stop. The rejected alternative is noise unless naming it stops a reader doing Y. BANNED: `verified in CI rather than asserted`. GOOD: `verified in CI`.
+11
View File
@@ -0,0 +1,11 @@
# Quality
Quality is proven by review. Every change is reviewed as a diff. The whole project is measured when a change carries an architectural decision, and before each release, because a project can drift from the principles one clean diff at a time. `SKILL.md` §3 says which review runs when. Quality has three parts. When two pull against each other, the earlier one wins.
1. **Correct.** The work does what the goals and the plan say, and tests prove it.
2. **True to the technical principles** (`~/.claude/principles/technical-principles.md`). The comprehension check (`SKILL.md` §3 → "Architecture") measures KISS.
3. **Plainly written**, per `~/.claude/CLAUDE.md` → "Prose" and `prose.md`.
## A false claim is a bug
Docs, comments and what a program prints — `--help`, an error, a log line — assert checkable things: a command, a resolution rule, a path, a limit. Verify one before you repeat or build on it. When it is wrong, correct it in the same change: the claim — or the code, when consumers already rely on what the claim promises. Never work around it or record the discrepancy elsewhere.
@@ -1,18 +1,8 @@
---
paths:
- "**/README.md"
---
# Goals and Audience
- **Goals** state the project's aim and intent, not promises: one numbered line each, like slogans, in priority order; a sub-goal is indented under its goal — "1. Blazing fast performance. 2. Correctness is more important than many features." A goal names no step of the work, such as a check to run first, and rarely an implementation. How a goal is met goes in a method section further down the README and names the goal it serves. BANNED as a goal: `Kill weak candidates early, with the cheap checks first.` GOOD: the goal `Keep research on a budget, so it scales in both time and cost.`, with the cheap checks moved to the method section, naming that goal.
- **Audience** names who depends on the project and what they may rely on.
# README
**A README covers what a reader needs *before* opening the code**: how it meets its goals, and how to build, test, run, and deploy it. It does **not** narrate an individual symbol, file, or test case — whoever wants to know what a test asserts opens the test, where the answer is exact and cannot drift.
**"Refresh `README.md` to match" means keep it true, not longer.** A change that alters a build/test/run/deploy step, a required env var, or a prerequisite makes the README a false claim by omission, fixed per `~/.claude/CLAUDE.md` → "Quality", "A false claim is a bug". Otherwise most changes need no README edit at all. GOOD: `run-tests.sh` gained a required `--profile` flag → update the documented command. BANNED: the change added a test case → add a paragraph describing it.
**"Refresh `README.md` to match" means keep it true, not longer.** A change that alters a build/test/run/deploy step, a required env var, or a prerequisite makes the README a false claim by omission, fixed per `~/.claude/skills/larv-review/standards/quality.md` → "A false claim is a bug". Otherwise most changes need no README edit at all. GOOD: `run-tests.sh` gained a required `--profile` flag → update the documented command. BANNED: the change added a test case → add a paragraph describing it.
## Package README (what someone finds on npm or GitHub)
- The public API is the contract, so the README documents it: options, results, events, everything exported. The rule against narrating a file or test case still holds.
+7 -15
View File
@@ -6,7 +6,7 @@
`Bar = 9`
`Next ID = 105`
`Next ID = 106`
| Goal | W |
|---|---|
@@ -24,7 +24,6 @@
| ID | Release | Exempt | Item | R | S | A | G | Goals | Score |
|---|---|---|---|---|---|---|---|---|---|
| 104 | 0.1.0 | | **Have a chunk's worker implement the simplest change that solves its item, loading no technical principle, and have the reviewers refactor it until it meets them.** | 6 | 5 | 8 | 8 | 1.4, 1.5 | 24.1 |
| 98 | 0.1.0 | | **Score R and S from a measurement wherever one exists, and calibrate each guessed score against the finished chunk's measured outcome.** | 2 | 5 | 6 | 7 | 1.1, 1.4 | 22.6 |
| 99 | 0.1.0 | | **Drop the comprehension panel as a merge gate, and keep recording its scores and the places in the code its seats found hard, for later measurement and for other reviewers and agents to improve.** | 4 | 5 | 7 | 7 | 1.1, 1.4, 1.5 | 22.6 |
| 87 | 0.1.0 | | **Score every `todo.md` item's complexity C from 1 to 10, and have `rank_todo.py` fail on an item without one.** | 3 | 4 | 6 | 7 | 1.1, 1.4 | 21.9 |
@@ -34,6 +33,7 @@
| 88 | 0.2.0 | | **Define one routing ladder of (model, effort) rungs ordered by a published ranking of their competence, and map a task's R + C to a rung relative to the project's model.** | 3 | 4 | 6 | 7 | 1.4 | 21.4 |
| 90 | 0.2.0 | | **Route each reviewer by the chunk's R + C, once a replay of past chunks shows the routed reviewer finds the 🔴 and 🟡 findings on record.** | 4 | 5 | 6 | 7 | 1.4 | 20.2 |
| 91 | 0.2.0 | | **Start each chunk's worker on the rung its item's R + C picks, never below the project's model, and step it one rung up after two unfinished verdicts on one chunk.** | 4 | 5 | 6 | 7 | 1.4 | 20.2 |
| 105 | 0.2.0 | decision | **Compare review rounds per pass and reading cost for the five chunks before and after item 104 moved the principles out of the worker's context, and file an item if either rose.** | 1 | 2 | 5 | 6 | 1.4 | 20.0 |
| 92 | 0.2.0 | | **Have the worker route each subagent by its task's R + C, and delegate a task only when the worker needs just its conclusion.** | 2 | 2 | 5 | 6 | 1.4 | 19.0 |
| 89 | 0.2.0 | | **Run the judge on the rung its chunk's R + C picks, once a replay of archived transcripts shows it returns the verdicts on record.** | 3 | 4 | 5 | 6 | 1.4 | 17.5 |
| 1 | 0.3.0 | question | **Say in README → Install how the transcript archive is backed up, once bender-infra backs up ai-sandbox's data volume.** | 3 | 5 | 8 | 9 | 3, 4 | 27.0 |
@@ -65,18 +65,6 @@
## Details
### 104. Have a chunk's worker implement the simplest change that solves its item, loading no technical principle, and have the reviewers refactor it until it meets them.
Like red, green, refactor: the worker makes the item work, and the review passes raise it to the bar. Today `CLAUDE.md` → "Technical principles" tells every session to read `technical-principles.md` before writing code, and a loop-claude worker loads every file under `rules/`: 263 sentences (4,246 words), above the 254 that `CLAUDE.md` held before item 95, which cut it to 181.
- Replace "Read it before writing, designing or reviewing code" with: implement the simplest change that solves the item; the reviewers apply the principles. No worker reads a file under `~/.claude/principles/`. Point every other reference to them in `CLAUDE.md` at the reviewer that applies it, or drop it.
- Move "Quality" to `larv-review`, and the comment, README and doc rules to files the prose and stability reviewers read, loaded by no path. Keep the rules for writing Goals and Audience and `rules/todo-items.md` loading with their files: writing them is the worker's job.
- Keep frontloaded each project's decision titles in its `AGENTS.md`, since a worker that misses a decision builds the wrong behaviour, and a core of about five lines of "Prose", since no reviewer reads the worker's chat. The human chose both on 2026-10-13.
- Keep `rule-hook`: it blocks what a program can check, at no context cost.
- Have loop-claude's judge read each rule where it now lives.
- Record the split in `docs/decisions.md`, serving goals 1.4 and 1.5, valid while review rounds per pass do not rise. A principle such as functional core, found late, can cost a rewrite within a pass's three rounds: compare rounds per pass and reading cost in loop-claude's archive for the five chunks before and after, and file an item if they rise. The PR states the sentences a worker loads before and after.
- Cut too what Claude follows unasked, the working loop's per-topic pointers that repeat "Topic rules", and "Maintaining this file".
### 98. Score R and S from a measurement wherever one exists, and calibrate each guessed score against the finished chunk's measured outcome.
A score that can be computed from the code it touches, such as the files an item names, comes from that computation. Otherwise size and risk are estimated from finished work, the way reference-class forecasting estimates a project from earlier projects like it. When a chunk merges, record its measured outcome beside the item's guessed R and S: lines and files changed, review rounds, 🔴 and 🟡 findings, and fixes the code needed later. Show the scorer, when it files an item, the finished items whose guessed scores sat nearest and what they measured. Once enough chunks are recorded, report how far each guess was from its outcome, so a scorer whose S runs high can be corrected. Item 87's C is scored and calibrated the same way.
@@ -129,6 +117,10 @@ loop-claude reads the top item of the next release with `rank_todo.py` before st
Needs 88.
### 105. Compare review rounds per pass and reading cost for the five chunks before and after item 104 moved the principles out of the worker's context, and file an item if either rose.
The `worker:` decision is valid while review rounds per pass do not rise. Count the rounds from each PR's `Answer <pass> round <n>:` commits, and take reading cost from `docs/reading-cost.md`. Run it once five chunks have merged after the one that recorded the decision.
### 92. Have the worker route each subagent by its task's R + C, and delegate a task only when the worker needs just its conclusion.
State in `CLAUDE.md` when the worker delegates: a search or read that spans many files whose conclusion is all it needs, and work independent enough to run in parallel. Edits and anything the worker must verify line by line stay in the main thread, since a delegated diff is read again to check it. The worker scores R and C for each delegated task as it would for an item, and passes the rung's model and effort. In item 73's measurement, reports cost a median 8% of the worker's peak context, and `sed -n` and `grep` output made up 41% of its Bash results, so delegating searches saves the most context. The Agent tool sets a subagent's effort only when instructions ask, so the rule names both model and effort.
@@ -207,7 +199,7 @@ Found by the principles audit of PR #242, against "Functional core, imperative s
### 29. Make the contributor a standing member of every project's audience, unless its `## Audience` says maintainability does not matter.
State that in `~/.claude/rules/readme.md` → "Goals and Audience", and have larv-review's comprehension floor name the contributor as the reader it serves. The floor's block then applies to a project whose audience includes the contributor, and a project that drops them skips it.
State that in `~/.claude/rules/goals-and-audience.md` → "Goals and Audience", and have larv-review's comprehension floor name the contributor as the reader it serves. The floor's block then applies to a project whose audience includes the contributor, and a project that drops them skips it.
### 68. Test `workflow-bench/compare.py`'s blinding and `bench.py`'s run plan.