Hand reviewers the review standards from the folder a project's config names
CI / tests (pull_request) Successful in 1m48s
CI / tests (pull_request) Successful in 1m48s
This commit is contained in:
@@ -46,7 +46,7 @@ Write the thing, not an introduction to it. State what holds and stop; name a re
|
||||
|
||||
Write negations as people say them: after a verb, or after its preposition, write `doesn't <verb> anything` or `anyone`, never `<verb> nothing` or `no one`. BANNED: `stops nothing`, `depends on no one`, `so answering in time costs nothing`. GOOD: `doesn't stop anything`, `doesn't depend on anyone`, `so answering in time doesn't cost anything`.
|
||||
|
||||
Reviewers hold prose to the full rules, with examples: `~/.claude/skills/larv-review/standards/prose.md`.
|
||||
Reviewers hold prose to the full rules, with examples: `prose.md` in the project's review standards.
|
||||
|
||||
## 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)`.
|
||||
@@ -60,7 +60,7 @@ Claude Code loads a rule file when a session writes a file its `paths:` frontmat
|
||||
- Goals and audience: `~/.claude/rules/goals-and-audience.md`.
|
||||
- Plan items, their scores and Exempt reasons: `~/.claude/rules/todo-items.md`. Read it before you file, score, edit or move an item: a session that runs `todo-item` never opens `todo.md` itself, so the rule doesn't load.
|
||||
|
||||
The rules only reviewers apply, for quality, comments, READMEs and prose, live in `~/.claude/skills/larv-review/standards/`.
|
||||
The rules only reviewers apply, for quality, comments, READMEs and prose, are the project's review standards: the folder its config sets as `standards`, which `~/.claude/bin/project-config standards` prints.
|
||||
|
||||
## Working with the codebase
|
||||
- Always start a new git worktree when doing something in a codebase, and clean it up when done. Unless told otherwise, branch it off a freshly-updated default branch (`git fetch origin`, then base on `origin/main`), not whatever happens to be checked out.
|
||||
@@ -78,7 +78,7 @@ The rules only reviewers apply, for quality, comments, READMEs and prose, live i
|
||||
1. A re-score of the item's L, made on the project's rung or above, picks a rung above yours.
|
||||
2. The same failing test or finding survives two fix attempts.
|
||||
3. A pass reports a 🔴 in round 2.
|
||||
4. A review rules the work below standard: systems-architect's BLOCK, a finding against larv-review's `standards/quality.md`, or a vote `record-ruling` counts as worse, in the report that stands after any relaunch one rung up (`larv-review` §3 → "Rung up"). It doesn't fire where the fix changes only prose (`larv-review` §3 says what is prose): fix that on your own rung.
|
||||
4. A review rules the work below standard: systems-architect's BLOCK, a finding against the review standards' `quality.md`, or a vote `record-ruling` counts as worse, in the report that stands after any relaunch one rung up (`larv-review` §3 → "Rung up"). It doesn't fire where the fix changes only prose (`larv-review` §3 says what is prose): fix that on your own rung.
|
||||
|
||||
When one fires, hand the hard part, edits included, to a subagent on the rung loop-claude's prompt names, one above yours. Open the subagent's prompt with the marker loop-claude's prompt gives, then the trigger's evidence. Each later subagent on that task runs on that rung or higher, and each further escalation trigger moves the task one rung higher, up to the highest rung loop-claude's prompt names. Ask the human before going higher. Where loop-claude's prompt names no escalation, as on the ladder's top rung or off it, keep the task in your own thread.
|
||||
- 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. A reviewer under `~/.claude/agents/` writes only its report, under `~/.local/state/larv-review/`, and rule-hook refuses it every other Write, every Edit and every MultiEdit. One that probes a build tags the image as throwaway and removes it afterwards, writes only to a folder it makes under the chunk's review folder (`~/.claude/bin/larv-review review-folder` prints it), and removes no image or file it did not create.
|
||||
@@ -130,7 +130,7 @@ Claude Code reads this section by its heading when it compacts a conversation. K
|
||||
- **goals file** — the file holding a project's `## Goals` and `## Audience`: the one its config names as `goals-and-audience`. Read it in the file `~/.claude/bin/project-record open goals-and-audience` prints. It is `README.md`, unless a client's project keeps it in the config's folder, or in a Jira epic's description, which the loop only reads.
|
||||
- **interrupt** — `loop-claude` asking the human, on its terminal, for a decision that is theirs. They type a one-line answer there, or `/talk` to open the worker's session there with `claude --resume`. A release ready to cut opens that session at once. A routing call opens claude on that terminal too, in `~/code/claude-config`, the checkout where this setup is developed.
|
||||
- **judge** — the headless claude that reads a worker's transcript each cycle and decides whether to interrupt and whether the chunk is finished.
|
||||
- **judge's records** — the files the judge reads beside the premises: the project's `AGENTS.md` and `docs/decisions.md`, then the human's `~/.claude/CLAUDE.md` and the `.md` files in `~/.claude/rules/` and `~/.claude/skills/larv-review/standards/`.
|
||||
- **judge's records** — the files the judge reads beside the premises: the project's `AGENTS.md` and `docs/decisions.md`, then the human's `~/.claude/CLAUDE.md` and the `.md` files in `~/.claude/rules/`, then those in the project's review standards.
|
||||
- **paired ruling** — the seats vote whether the project reads better, the same or worse at the branch's head than at the base, the commit `larv-review ruling-base` prints; `larv-review --help` says how the votes make the ruling.
|
||||
- **pass** — one kind of review a chunk may take, run in rounds by its reviewers until clean; `larv-review` §3 lists them.
|
||||
- **place** — the smallest addressable unit, such as a function or a section heading, that a seat names with its `path:line` when it judges how hard the project is to read there.
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# Claude Code configuration
|
||||
|
||||
My personal `~/.claude`, version controlled: `CLAUDE.md` and `rules/` for instructions, the words under `CLAUDE.md` → "Vocabulary"; `.claude/rules/` for the rules that load in this repo alone; `agents/` and `skills/`; `principles/` and `skills/larv-review/standards/` for what the reviewer agents hold projects to; `docs/` for decisions and the comprehension history; `settings.json` for the harness and `.claude/settings.json` for the harness inside this repo; `CHANGELOG.md` and `todo.md`; the tools in `bin/`; `workflow-bench/`, the scripts and prompts of the 2026-09-30 bench of larv-review and of the 2026-11-12 bench of the advisor tool; `reviewer-merge-trials/`, the 2026-11-09 trials of merging reviewers, with their method, results and scripts; `judge-field-trials/`, the 2026-11-11 trials of which facts code could read in place of loop-claude's judge, with their results and scripts; `stability-skip-count/`, the 2026-11-12 count of archived stability rounds, with its script, from which larv-review took when to skip a stability round 2; and `presentation/`, a page that explains this setup to newcomers, with the script that prints it to PDF.
|
||||
My personal `~/.claude`, version controlled: `CLAUDE.md` and `rules/` for instructions, the words under `CLAUDE.md` → "Vocabulary"; `.claude/rules/` for the rules that load in this repo alone; `agents/` and `skills/`; `principles/` and `skills/larv-review/standards/` for what the reviewer agents hold projects to, where a project's config names them as `principles` and `standards`; `docs/` for decisions and the comprehension history; `settings.json` for the harness and `.claude/settings.json` for the harness inside this repo; `CHANGELOG.md` and `todo.md`; the tools in `bin/`; `workflow-bench/`, the scripts and prompts of the 2026-09-30 bench of larv-review and of the 2026-11-12 bench of the advisor tool; `reviewer-merge-trials/`, the 2026-11-09 trials of merging reviewers, with their method, results and scripts; `judge-field-trials/`, the 2026-11-11 trials of which facts code could read in place of loop-claude's judge, with their results and scripts; `stability-skip-count/`, the 2026-11-12 count of archived stability rounds, with its script, from which larv-review took when to skip a stability round 2; and `presentation/`, a page that explains this setup to newcomers, with the script that prints it to PDF.
|
||||
|
||||
## Goals
|
||||
|
||||
@@ -92,6 +92,7 @@ reading-cost = "checkout:docs/reading-cost.md"
|
||||
changelog = "checkout:CHANGELOG.md"
|
||||
goals-and-audience = "checkout:README.md"
|
||||
principles = "~/.claude/principles"
|
||||
standards = "~/.claude/skills/larv-review/standards"
|
||||
```
|
||||
|
||||
A project may also set `env-file`, the file of `KEY=value` credentials its tools read, such as `env-file = "~/.claude-projects/log.env"`. It is a path that starts with `/` or `~/`, outside the checkout and the config's folder, so that no git remote receives it. A tool that needs a key fails and names each one the file lacks. No failure message, prompt, log line or archived loop output holds a token from the file. rule-hook refuses a Read or a Grep of the file and a Bash command that names it or searches a folder holding it with `ag`, `grep -r` or `rg`, unless the tool skips the file as hidden or ignored, so a worker doesn't read it in passing; `rule-hook --help` says which calls it checks. A project without the setting has no credentials, and never reads another project's. `project-config env-file` prints the path.
|
||||
|
||||
@@ -9,13 +9,13 @@ You read the prose as someone who did not write it: you see only what it says, n
|
||||
|
||||
The bar, read each time, since it changes:
|
||||
|
||||
- every file under `~/.claude/skills/larv-review/standards/`, of `quality.md` only "A false claim is a bug";
|
||||
- every file in the folder your prompt's `Review standards:` line names, of `quality.md` only "A false claim is a bug";
|
||||
- `~/.claude/CLAUDE.md` → "Public API specs";
|
||||
- each file under `~/.claude/rules/` whose `paths:` frontmatter matches a file the diff changes.
|
||||
|
||||
Verdict, severities and rounds: ~/.claude/skills/larv-review/review-findings.md.
|
||||
|
||||
Your prompt's `Prose language:` line names the language the project's config sets. Apply every check below to prose in that language, by that language's grammar and idiom. The bar's examples are English: find the same fault in the other language, never the same English words. Prose in another language is a finding, except what `standards/prose.md` says stays English. Write your report in English.
|
||||
Your prompt's `Prose language:` line names the language the project's config sets. Apply every check below to prose in that language, by that language's grammar and idiom. The bar's examples are English: find the same fault in the other language, never the same English words. Prose in another language is a finding, except what `prose.md` in the review standards says stays English. Write your report in English.
|
||||
|
||||
## Checks, in priority order
|
||||
|
||||
@@ -23,7 +23,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` unless a project principle there covers it, 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.
|
||||
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` unless a project principle there covers it, and a goal to the README. A pointer standing where a definition belongs (the 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 list whose order carries no meaning and is not sorted (the technical principles' "Deterministic order", in the folder your prompt's `Technical principles:` line names; without one, open your report by saying so), a sentence contradicting another, a claim the code shows false, and a word used against `CLAUDE.md` → "Vocabulary".
|
||||
|
||||
@@ -11,7 +11,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 folder your prompt's `Technical principles:` line names**, and `~/.claude/skills/larv-review/standards/quality.md`. These are mandatory 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. Where your prompt has no such line, without one, open your report by saying so.
|
||||
2. **Read every file in the folder your prompt's `Technical principles:` line names**, and `quality.md` in the folder its `Review standards:` line names. These are mandatory 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. Where your prompt lacks either line, open your report by saying so.
|
||||
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 run them unless your prompt hands you a passing run on the head (step 4).
|
||||
4. **Verify, don't just read.** Where your prompt hands you the commit on which the worker's run of the test suite and static analysis last passed, and it is the head, don't run them again, and say so in Coverage & Verification. Otherwise run the test suite and static analysis/linters through the project's container tooling, unless `~/.claude/bin/project-config tooling-on-host` prints true or a decision puts them on the host; tear down test containers afterwards. Run the full suite under `~/.claude/bin/run-heavy`. Run it in the background or with the Bash tool's longest timeout: that timeout includes the wait for a slot. 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. Make scratch work with Bash, since Write is for your report alone. Put it in a directory you create for this run, and delete it when done; don't delete anything 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. **Judge the surviving mutants.** Your prompt hands you what the project's mutation command printed on the change, with the commit it ran on: the mutants of changed lines that no test kills, or the message of a run that failed. Ignore a surviving mutant that leaves behaviour unchanged, or changes only message or log text no caller or user depends on. Report one 🟡 per test to add or strengthen, naming the surviving mutants it would catch. Where the prompt doesn't hand you any output, or names a commit other than the head, run the command yourself in the change's checkout, through run-heavy as in step 4: the one the project's README documents, else `~/.claude/bin/run-heavy ~/.claude/bin/mutate-changes --prefix '<how the project runs its tools>'`. `~/.claude/bin/mutate-changes --help` says which tool it runs for each language, how to set `--jobs`, and what it prints. Mutation-test the changed code that no run mutated, in a language mutate-changes doesn't cover or where a run failed, with a widely deployed mutation tool limited to the changed lines, else with mutants you make by hand. Report the wall time and mutant count in Coverage & Verification, or why nothing was mutated.
|
||||
|
||||
@@ -130,16 +130,16 @@ reviewer-header takes the name of a pass that an agent under agents/ reviews, sp
|
||||
prints it, such as stability. It prints the header of the prompt that launches the pass's reviewer
|
||||
in its next round: the pass and round, the branch's open pull request at its pushed head, the
|
||||
worktree and branch, the merge base of HEAD and the default branch, and the paths of the reviewer's
|
||||
report, the branch diff, the folder of technical principles the project's config sets, the goals
|
||||
and the plan and, for architecture and stability, the places. For a reviewer whose
|
||||
report, the branch diff, the folders of technical principles and review standards the project's
|
||||
config sets, the goals and the plan and, for architecture and stability, the places. For a reviewer whose
|
||||
definition under ~/.claude/agents/ has `omitClaudeMd: true`, it then names the file that holds the
|
||||
project principles and decision titles, where the project keeps one. It writes the diff, from
|
||||
that base to HEAD, into the chunk's review folder as branch-<short HEAD>.diff, writes what
|
||||
places prints into places.md, and lists the plan's items into
|
||||
plan.md, whatever store holds the plan; a file whose text is unchanged is left as it is. With --rerun, the
|
||||
header names the report of a relaunch one rung up, in the same round, and the report that asked for
|
||||
it. It exits 1 when the pass takes no more rounds, when `project-config` fails in the checkout, when the
|
||||
principles folder it names is not a folder with a file in it, or, with --rerun, when the report that
|
||||
it. It exits 1 when the pass takes no more rounds, when `project-config` fails in the checkout, when
|
||||
either folder it names is not a folder with a file in it, or, with --rerun, when the report that
|
||||
asked is missing.
|
||||
|
||||
reviewer-context is the SubagentStart hook. It reads the hook's input on stdin. For a reviewer
|
||||
|
||||
@@ -34,6 +34,7 @@ class Launch:
|
||||
folder: pathlib.Path
|
||||
diff: pathlib.Path
|
||||
principles: pathlib.Path
|
||||
standards: pathlib.Path
|
||||
goals: pathlib.Path
|
||||
# The plan's listing, for a reviewer that reads files, whatever store holds the plan.
|
||||
plan: pathlib.Path
|
||||
@@ -59,6 +60,7 @@ class Launch:
|
||||
f"Report: write it to {report}.",
|
||||
f"Diff: {self.diff}",
|
||||
f"Technical principles: {self.principles}",
|
||||
f"Review standards: {self.standards}",
|
||||
f"Goals and audience: {self.goals}",
|
||||
f"Plan: {self.plan}",
|
||||
f"Prose language: {self.language}.",
|
||||
@@ -97,10 +99,11 @@ def reviewer_header(default: str, pass_: str, rerun: bool, home: pathlib.Path) -
|
||||
config = located(None, home)
|
||||
if isinstance(config, Failure):
|
||||
return config
|
||||
principles = config.paths["principles"]
|
||||
# A typo in the config would otherwise hand every reviewer an empty folder, and the review would run with no principles.
|
||||
if not principles.is_dir() or not any(principles.iterdir()):
|
||||
return Failure(f"{principles} is not a folder with a file in it; {config.folder / 'config.toml'} sets it as `principles`")
|
||||
principles, standards = config.paths["principles"], config.paths["standards"]
|
||||
# A typo in the config would otherwise hand every reviewer an empty folder, and the review would run with no principles or standards.
|
||||
empty = next((setting for setting in ("principles", "standards") if not config.paths[setting].is_dir() or not any(config.paths[setting].iterdir())), None)
|
||||
if empty is not None:
|
||||
return Failure(f"{config.paths[empty]} is not a folder with a file in it; {config.folder / 'config.toml'} sets it as `{empty}`")
|
||||
decisions = local_file(store(config, "decisions"), folder / "decisions.md")
|
||||
if isinstance(decisions, Failure):
|
||||
return decisions
|
||||
@@ -108,7 +111,7 @@ def reviewer_header(default: str, pass_: str, rerun: bool, home: pathlib.Path) -
|
||||
goals = local_file(goals_store(config), folder / "goals.md")
|
||||
if isinstance(goals, Failure):
|
||||
return goals
|
||||
launch = Launch(pass_, round_, rerun, pull_named(worktree, branch), worktree, branch, base, default, folder, folder / f"branch-{head}.diff", principles, goals, folder / "plan.md", starts_bare(next((agent for name, agent in REVIEWERS.items() if name == pass_), ""), home), config.paths["working-rules"], decisions, config.language)
|
||||
launch = Launch(pass_, round_, rerun, pull_named(worktree, branch), worktree, branch, base, default, folder, folder / f"branch-{head}.diff", principles, standards, goals, folder / "plan.md", starts_bare(next((agent for name, agent in REVIEWERS.items() if name == pass_), ""), home), config.paths["working-rules"], decisions, config.language)
|
||||
if rerun and not launch.asked().exists():
|
||||
return Failure(f"no report asked for a rerun of {pass_}'s round {round_}: {launch.asked()} is missing; relaunch before you commit the round's answers")
|
||||
written = write_inputs(launch, base, home, plan_listing(plan_store(config)))
|
||||
|
||||
@@ -483,6 +483,7 @@ reading-cost = "checkout:docs/reading-cost.md"
|
||||
changelog = "checkout:CHANGELOG.md"
|
||||
goals-and-audience = "checkout:README.md"
|
||||
principles = "~/principles"
|
||||
standards = "~/standards"
|
||||
"""
|
||||
|
||||
|
||||
@@ -505,6 +506,8 @@ class LarvReviewTool(unittest.TestCase):
|
||||
self.config.write_text(PROJECT_CONFIG)
|
||||
(root / "principles").mkdir()
|
||||
(root / "principles" / "technical-principles.md").write_text("# Principles\n")
|
||||
(root / "standards").mkdir()
|
||||
(root / "standards" / "quality.md").write_text("# Quality\n")
|
||||
|
||||
def git(self, *args):
|
||||
return subprocess.run(["git", "-c", "user.name=t", "-c", "user.email=t@t", *args], cwd=self.checkout, check=True, env=self.env, capture_output=True, text=True).stdout
|
||||
@@ -1128,6 +1131,7 @@ class LarvReviewTool(unittest.TestCase):
|
||||
f"Report: write it to {folder}/stability-round-1.md.\n"
|
||||
f"Diff: {folder}/branch-{short}.diff\n"
|
||||
f"Technical principles: {self.checkout.parent}/principles\n"
|
||||
f"Review standards: {self.checkout.parent}/standards\n"
|
||||
f"Goals and audience: {self.checkout}/README.md\n"
|
||||
f"Plan: {folder}/plan.md\n"
|
||||
"Prose language: English.\n"
|
||||
@@ -1220,6 +1224,9 @@ class LarvReviewTool(unittest.TestCase):
|
||||
def test_reviewer_header_names_the_principles_folder_the_projects_config_sets(self):
|
||||
self.assertEqual(self.header_line("Technical principles:", "prose"), f"Technical principles: {self.checkout.parent}/principles")
|
||||
|
||||
def test_reviewer_header_names_the_review_standards_folder_the_projects_config_sets(self):
|
||||
self.assertEqual(self.header_line("Review standards:", "prose"), f"Review standards: {self.checkout.parent}/standards")
|
||||
|
||||
def test_reviewer_header_names_the_language_and_counts_rounds_through_the_commit_title_the_projects_config_sets(self):
|
||||
self.config.write_text(PROJECT_CONFIG + 'language = "Swedish"\ncommit-title = "PAY-{id} - {summary}"\n')
|
||||
self.commit("PAY-7 - Answer prose round 1: 0 🔴, 1 🟡 (0 misread); a")
|
||||
@@ -1248,11 +1255,13 @@ class LarvReviewTool(unittest.TestCase):
|
||||
self.assertEqual((ran.returncode, ran.stdout), (1, ""))
|
||||
self.assertIn("cannot read the epic ABC-12", ran.stderr)
|
||||
|
||||
def test_reviewer_header_fails_with_the_configs_message_where_it_sets_no_principles_folder(self):
|
||||
self.config.write_text(PROJECT_CONFIG.replace('principles = "~/principles"\n', ""))
|
||||
ran = self.run_tool("reviewer-header", "prose")
|
||||
self.assertEqual((ran.returncode, ran.stdout), (1, ""))
|
||||
self.assertIn("`principles` is missing", ran.stderr)
|
||||
def test_reviewer_header_fails_with_the_configs_message_where_it_sets_no_principles_or_standards_folder(self):
|
||||
for setting in ("principles", "standards"):
|
||||
with self.subTest(setting=setting):
|
||||
self.config.write_text(PROJECT_CONFIG.replace(f'{setting} = "~/{setting}"\n', ""))
|
||||
ran = self.run_tool("reviewer-header", "prose")
|
||||
self.assertEqual((ran.returncode, ran.stdout), (1, ""))
|
||||
self.assertIn(f"`{setting}` is missing", ran.stderr)
|
||||
|
||||
def test_reviewer_header_fails_where_no_config_names_the_checkout(self):
|
||||
self.config.unlink()
|
||||
@@ -1260,15 +1269,19 @@ class LarvReviewTool(unittest.TestCase):
|
||||
self.assertEqual((ran.returncode, ran.stdout), (1, ""))
|
||||
self.assertIn(f"no config names the checkout {self.checkout}", ran.stderr)
|
||||
|
||||
def test_reviewer_header_fails_where_the_principles_folder_is_missing_or_empty(self):
|
||||
folder = self.checkout.parent / "principles"
|
||||
(folder / "technical-principles.md").unlink()
|
||||
empty = self.run_tool("reviewer-header", "prose")
|
||||
folder.rmdir()
|
||||
missing = self.run_tool("reviewer-header", "prose")
|
||||
for ran in (empty, missing):
|
||||
self.assertEqual((ran.returncode, ran.stdout), (1, ""))
|
||||
self.assertIn(f"{folder} is not a folder with a file in it; {self.config} sets it as `principles`", ran.stderr)
|
||||
def test_reviewer_header_fails_where_the_principles_or_standards_folder_is_missing_or_empty(self):
|
||||
for setting, file in (("principles", "technical-principles.md"), ("standards", "quality.md")):
|
||||
with self.subTest(setting=setting):
|
||||
folder = self.checkout.parent / setting
|
||||
(folder / file).unlink()
|
||||
empty = self.run_tool("reviewer-header", "prose")
|
||||
folder.rmdir()
|
||||
missing = self.run_tool("reviewer-header", "prose")
|
||||
folder.mkdir()
|
||||
(folder / file).write_text("# Restored\n")
|
||||
for ran in (empty, missing):
|
||||
self.assertEqual((ran.returncode, ran.stdout), (1, ""))
|
||||
self.assertIn(f"{folder} is not a folder with a file in it; {self.config} sets it as `{setting}`", ran.stderr)
|
||||
|
||||
def test_reviewer_header_gives_the_architect_the_places(self):
|
||||
folder = self.checkout.parent / ".local" / "state" / "larv-review" / "proj"
|
||||
|
||||
@@ -57,7 +57,7 @@ FINISHED_RULES = (
|
||||
"finished=true when the chunk is complete: merged, or nothing remains that the worker could do on "
|
||||
f"its own. Even then, it is finished only once {ANSWERS_RECORDED}.\n\n"
|
||||
"An answer counts as recorded where the premises or the records above already hold it, the human's rules "
|
||||
"(~/.claude/CLAUDE.md, ~/.claude/rules/, ~/.claude/skills/larv-review/standards/) included. "
|
||||
"(~/.claude/CLAUDE.md, ~/.claude/rules/, the project's review standards) included. "
|
||||
f"It also counts where the transcript shows the worker writing it into {ANSWER_DESTINATIONS}, "
|
||||
"but not into one of the human's rules.\n\n"
|
||||
"finished=false when work remains that a further run can "
|
||||
|
||||
@@ -10,20 +10,20 @@ first worker prompt also quotes the premises. They, with code health (~/.claude/
|
||||
"Shared goal") ranked first unless the goals file voids it, choose between ways to deliver the
|
||||
chunk's todo.md items, or else the task, and never widen them. 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, ~/.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 question they answer, the judge quotes the
|
||||
answer, loop-claude prints it, and the worker resumes with it. A quote they do not hold word for
|
||||
word is dropped, and the question goes to the human. So does a question asked again after its
|
||||
answer. A question the human answered earlier in the chunk goes back to the worker with that answer,
|
||||
unless the question quotes the words of the answer that leave it open. The fourth question they
|
||||
answer in one cycle goes to the human too, with the quote. An unfinished chunk resumes its session
|
||||
next cycle, and the worker is shown the passage the judge quoted as the work remaining. The next
|
||||
chunk starts a fresh session. Cycles continue until an exit below or Ctrl-C. Words:
|
||||
~/.claude/CLAUDE.md → "Vocabulary".
|
||||
~/.claude/CLAUDE.md and ~/.claude/rules/*.md, then the .md files in the folder of review standards
|
||||
the project's config sets, 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 question they
|
||||
answer, the judge quotes the answer, loop-claude prints it, and the worker resumes with it. A quote
|
||||
they do not hold word for word is dropped, and the question goes to the human. So does a question
|
||||
asked again after its answer. A question the human answered earlier in the chunk goes back to the
|
||||
worker with that answer, unless the question quotes the words of the answer that leave it open. The
|
||||
fourth question they answer in one cycle goes to the human too, with the quote. An unfinished chunk
|
||||
resumes its session next cycle, and the worker is shown the passage the judge quoted as the work
|
||||
remaining. The next chunk starts a fresh session. Cycles continue until an exit below or Ctrl-C.
|
||||
Words: ~/.claude/CLAUDE.md → "Vocabulary".
|
||||
|
||||
A question only the human can answer is an interrupt (bin/loop_claude/cycle/interrupt.py).
|
||||
loop-claude prints the question on its terminal, where the human answers it:
|
||||
@@ -96,7 +96,7 @@ Exit 1, saying why, when:
|
||||
- no task is given
|
||||
- git cannot start or finds no checkout
|
||||
- the goals file, 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
|
||||
the project's review standards where they exist, cannot be read or is not UTF-8
|
||||
- no config names the checkout, its config cannot be read, or the goals file holds no premises
|
||||
- the models file cannot be read or written
|
||||
- claude leaves no transcript
|
||||
|
||||
@@ -9,26 +9,26 @@ from record_store.stores import store
|
||||
RECORD_FILES = ("AGENTS.md", "docs/decisions.md")
|
||||
# The setting in the project's config that places each of RECORD_FILES.
|
||||
RECORD_SETTINGS = ("working-rules", "decisions")
|
||||
# The human's rules for every project, under ~/.claude: CLAUDE.md, then each .md file in these folders, which a repo check keeps present.
|
||||
# The human's rules: under ~/.claude, CLAUDE.md, then each .md file in the rules folder; then each .md file in the folder of review standards the project's config sets.
|
||||
HUMAN_RULES_FILE = "CLAUDE.md"
|
||||
HUMAN_RULE_DIRS = ("rules", "skills/larv-review/standards")
|
||||
HUMAN_RULE_NAMES = (f"~/.claude/{HUMAN_RULES_FILE}", *(f"~/.claude/{folder}/" for folder in HUMAN_RULE_DIRS))
|
||||
HUMAN_RULE_DIR = "rules"
|
||||
HUMAN_RULE_NAMES = (f"~/.claude/{HUMAN_RULES_FILE}", f"~/.claude/{HUMAN_RULE_DIR}/", "the project's review standards")
|
||||
|
||||
|
||||
CONSEQUENCE = "the judge cannot read the records"
|
||||
|
||||
|
||||
def read_records(root: str, home: pathlib.Path, claude_dir: pathlib.Path) -> str | Failure:
|
||||
"""The project's `AGENTS.md` and decision log, then the human's rules for every project, CLAUDE.md first, each headed by its name; one that does not exist, or is empty, is left out.
|
||||
"""The project's `AGENTS.md` and decision log, then the human's rules, CLAUDE.md first, each headed by its name; one that does not exist, or is empty, is left out.
|
||||
|
||||
`AGENTS.md` is read where the config under home of root's project puts it, and the decision log from the store that config names. Each is headed by its name in RECORD_FILES wherever it is kept."""
|
||||
config = located(root, home)
|
||||
if isinstance(config, Failure):
|
||||
return Failure(f"{config.reason} - {CONSEQUENCE}.")
|
||||
rules = [claude_dir / HUMAN_RULES_FILE] + [rule for folder in HUMAN_RULE_DIRS for rule in sorted((claude_dir / folder).glob("*.md"))]
|
||||
rules = [claude_dir / HUMAN_RULES_FILE, *sorted((claude_dir / HUMAN_RULE_DIR).glob("*.md")), *sorted(config.paths["standards"].glob("*.md"))]
|
||||
decisions = store(config, RECORD_SETTINGS[1]).read()
|
||||
texts = [(RECORD_FILES[0], file_text(config.paths[RECORD_SETTINGS[0]])), (RECORD_FILES[1], Failure(f"{decisions.reason} - {CONSEQUENCE}.") if isinstance(decisions, Failure) else decisions)]
|
||||
texts += [(f"~/.claude/{rule.relative_to(claude_dir)}", file_text(rule)) for rule in rules]
|
||||
texts += [(named(rule, home, claude_dir), file_text(rule)) for rule in rules]
|
||||
records = []
|
||||
for heading, text in texts:
|
||||
if isinstance(text, Failure):
|
||||
@@ -41,3 +41,10 @@ def read_records(root: str, home: pathlib.Path, claude_dir: pathlib.Path) -> str
|
||||
def file_text(path: pathlib.Path) -> str | Failure:
|
||||
"""path's text, empty where no such file exists."""
|
||||
return read_utf8(str(path.parent), path.name, CONSEQUENCE) if path.exists() else ""
|
||||
|
||||
|
||||
def named(rule: pathlib.Path, home: pathlib.Path, claude_dir: pathlib.Path) -> str:
|
||||
"""rule's path as the human writes it: under ~/.claude, or ~/ for the rest of home, or else in full."""
|
||||
if rule.is_relative_to(claude_dir):
|
||||
return f"~/.claude/{rule.relative_to(claude_dir)}"
|
||||
return f"~/{rule.relative_to(home)}" if rule.is_relative_to(home) else str(rule)
|
||||
|
||||
@@ -250,7 +250,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\nthe goals file'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.")
|
||||
self.assertEqual(run.question_for(QuotedAnswer("e", "Which one?", "A.")), "Which one?\n\nthe goals file's Goals and Audience, AGENTS.md, docs/decisions.md, ~/.claude/CLAUDE.md, ~/.claude/rules/ or the project's 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):
|
||||
@@ -491,12 +491,12 @@ Spent since 2026-09-21T14:13:20Z, in tokens of input, cache write 5m, cache writ
|
||||
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 nothing was typed"))
|
||||
resumed = fake.made("stream_claude")[1]
|
||||
self.assertEqual(resumed[resumed.index("-p") + 1], "Your question: Which one?\n\nthe goals file'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(resumed[resumed.index("-p") + 1], "Your question: Which one?\n\nthe goals file's Goals and Audience, AGENTS.md, docs/decisions.md, ~/.claude/CLAUDE.md, ~/.claude/rules/ or the project's review standards answers it:\n\nUse *A*.\n\nContinue the task.")
|
||||
self.assertEqual(len(fake.made("stream_claude")), 4)
|
||||
self.assertEqual(printed.getvalue().count("=== the goals file'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\nthe goals file'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 = f"2026-09-21T14:13:20Z Verdict: quoted answer\n\nWhich one?\n\nthe goals file'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\nConfig: {CONFIG}\nJudge: judge-model\nWorker: {OFF_LADDER}\n"
|
||||
self.assertEqual(self.archived_outcomes(), [f"Task: Do it.\n\n2026-09-21T14:13:20Z Verdict: interrupt\n\nWhich one?\n\nthe goals file'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\nConfig: {CONFIG}\nJudge: judge-model\nWorker: {OFF_LADDER}\n\n2026-09-21T14:13:20Z Stopped: the human is needed to answer the question above, but nothing was typed\n\nWorker: {OFF_LADDER}\n", *[f"Task: Do it.\n\n{quoted}"] * 3])
|
||||
self.assertEqual(printed.getvalue().count("=== the goals file's Goals and Audience, AGENTS.md, docs/decisions.md, ~/.claude/CLAUDE.md, ~/.claude/rules/ or the project's review standards answered: Which one? ===\nUse *A*."), 3)
|
||||
self.assertIn("Which one?\n\nthe goals file's Goals and Audience, AGENTS.md, docs/decisions.md, ~/.claude/CLAUDE.md, ~/.claude/rules/ or the project's review standards says:\nUse *A*.\n\nThose files have answered 3 questions this cycle", said.getvalue())
|
||||
quoted = f"2026-09-21T14:13:20Z Verdict: quoted answer\n\nWhich one?\n\nthe goals file's Goals and Audience, AGENTS.md, docs/decisions.md, ~/.claude/CLAUDE.md, ~/.claude/rules/ or the project's review standards says:\n> Use *A*.\n\nEvidence:\n> working\n\nConfig: {CONFIG}\nJudge: judge-model\nWorker: {OFF_LADDER}\n"
|
||||
self.assertEqual(self.archived_outcomes(), [f"Task: Do it.\n\n2026-09-21T14:13:20Z Verdict: interrupt\n\nWhich one?\n\nthe goals file's Goals and Audience, AGENTS.md, docs/decisions.md, ~/.claude/CLAUDE.md, ~/.claude/rules/ or the project's 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\nConfig: {CONFIG}\nJudge: judge-model\nWorker: {OFF_LADDER}\n\n2026-09-21T14:13:20Z Stopped: the human is needed to answer the question above, but nothing was typed\n\nWorker: {OFF_LADDER}\n", *[f"Task: Do it.\n\n{quoted}"] * 3])
|
||||
|
||||
def test_a_quoted_answer_that_cites_an_escalation_trigger_steps_the_worker_up_before_it_resumes_and_archives_the_step(self):
|
||||
fake = FakeEffects(streams=[Worker(self.paths.claude_code_transcripts.parent)] * 2, claude=[judged("quoted", answer="Use A.", escalation="working"), judged("finished")])
|
||||
@@ -1469,6 +1469,10 @@ class Records(unittest.TestCase):
|
||||
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.parents[1], claude_md.parent).endswith("From ~/.claude/CLAUDE.md:\n# Global\n\nFrom ~/.claude/rules/goals-and-audience.md:\n# Goals\n\nFrom ~/.claude/rules/todo-items.md:\n# Todo\n\nFrom ~/.claude/skills/larv-review/standards/comments.md:\n# Comments"))
|
||||
config.write_text(config.read_text().replace('"~/.claude/skills/larv-review/standards"', '"~/review-standards"'))
|
||||
pathlib.Path(claude_md.parents[1], "review-standards").mkdir()
|
||||
pathlib.Path(claude_md.parents[1], "review-standards", "quality.md").write_text("# Ours\n")
|
||||
self.assertTrue(records.read_records(root, claude_md.parents[1], claude_md.parent).endswith("From ~/.claude/rules/todo-items.md:\n# Todo\n\nFrom ~/review-standards/quality.md:\n# Ours"), "the config's standards folder replaces the default")
|
||||
|
||||
config.write_text(config.read_text().replace('"checkout:AGENTS.md"', '"folder:AGENTS.md"').replace('"checkout:docs/decisions.md"', '"folder:log/decisions.md"'))
|
||||
self.assertTrue(records.read_records(root, claude_md.parents[1], claude_md.parent).startswith("From ~/.claude/CLAUDE.md:\n# Global"), "the checkout's AGENTS.md and docs/decisions.md are its owners'")
|
||||
@@ -1925,7 +1929,7 @@ 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", "no config names the checkout, its config cannot be read, or the goals file holds no premises"
|
||||
models_ = "the models file cannot be read or written"
|
||||
names = (*records.RECORD_FILES, records.HUMAN_RULE_NAMES[0], *(f"{folder}*.md" for folder in records.HUMAN_RULE_NAMES[1:]))
|
||||
names = (*records.RECORD_FILES, records.HUMAN_RULE_NAMES[0], f"{records.HUMAN_RULE_NAMES[1]}*.md", records.HUMAN_RULE_NAMES[2])
|
||||
unreadable = f"the goals file, 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 = [
|
||||
|
||||
@@ -20,6 +20,7 @@ starts with / or ~/. In a worktree, a "checkout:" path is the worktree's own fil
|
||||
changelog = "checkout:CHANGELOG.md"
|
||||
goals-and-audience = "folder:goals.md"
|
||||
principles = "folder:principles"
|
||||
standards = "~/.claude/skills/larv-review/standards"
|
||||
|
||||
`plan` may name a Jira Cloud epic in place of a path, as "jira:" and the epic's address:
|
||||
"jira:https://acme.atlassian.net/browse/ABC-12". The plan is then the epic's open child issues, in
|
||||
|
||||
@@ -15,7 +15,7 @@ from project_config import templates
|
||||
PROJECTS = ".claude-projects"
|
||||
CONFIG = "config.toml"
|
||||
# Every path a project sets, by its role. Three readers, seated as the human who writes the config, picked the spelling from four candidates. They picked role names over file names, which a client's project doesn't share.
|
||||
SETTINGS = ("plan", "working-rules", "decisions", "score-anchors", "comprehension-history", "reading-cost", "changelog", "goals-and-audience", "principles")
|
||||
SETTINGS = ("plan", "working-rules", "decisions", "score-anchors", "comprehension-history", "reading-cost", "changelog", "goals-and-audience", "principles", "standards")
|
||||
# They also picked a prefix over bare relative paths: each line says its own place, and a relative path with no prefix fails instead of landing somewhere by default.
|
||||
SPELLING = '"checkout:<path>" for a path in the checkout, "folder:<path>" for one in the config\'s folder, or a path that starts with / or ~/'
|
||||
# A path setting a project may leave out: the file of KEY=value credentials its tools read. It has no default either: a project without it asks for no credentials, and never reads another project's.
|
||||
|
||||
@@ -27,6 +27,7 @@ reading-cost = "folder:docs/reading-cost.md"
|
||||
changelog = "checkout:CHANGELOG.md"
|
||||
goals-and-audience = "folder:goals.md"
|
||||
principles = "~/.claude/principles"
|
||||
standards = "~/.claude/skills/larv-review/standards"
|
||||
"""
|
||||
|
||||
JIRA_PLAN = "jira:https://acme.atlassian.net/browse/ABC-12"
|
||||
@@ -86,6 +87,7 @@ class LoadTest(ConfigCase):
|
||||
self.assertEqual(found.paths["decisions"], folder / "docs" / "decisions.md")
|
||||
self.assertEqual(found.paths["changelog"], self.checkout / "CHANGELOG.md")
|
||||
self.assertEqual(found.paths["principles"], self.home / ".claude" / "principles")
|
||||
self.assertEqual(found.paths["standards"], self.home / ".claude" / "skills" / "larv-review" / "standards")
|
||||
self.assertEqual(tuple(found.paths), SETTINGS)
|
||||
|
||||
def test_a_plan_spelt_as_a_jira_epic_is_no_path(self) -> None:
|
||||
@@ -240,10 +242,10 @@ class LoadTest(ConfigCase):
|
||||
self.assertIn("~/.claude-projects/<key>/config.toml", reason)
|
||||
|
||||
def test_every_missing_setting_is_named(self) -> None:
|
||||
kept = "".join(line + "\n" for line in CLIENT.splitlines() if not line.startswith(("plan", "changelog", "principles")))
|
||||
kept = "".join(line + "\n" for line in CLIENT.splitlines() if not line.startswith(("plan", "changelog", "principles", "standards")))
|
||||
self.write("acme", kept)
|
||||
reason = self.failure()
|
||||
for name in ("plan", "changelog", "principles"):
|
||||
for name in ("plan", "changelog", "principles", "standards"):
|
||||
with self.subTest(name=name):
|
||||
self.assertIn(f"`{name}` is missing", reason)
|
||||
self.assertNotIn("`decisions` is", reason)
|
||||
@@ -335,7 +337,7 @@ class LoadTest(ConfigCase):
|
||||
(folder / "config.toml").write_text(CLIENT + 'touch-predictions = "folder:docs/touch-predictions.md"\n', encoding="utf-8")
|
||||
found = load(self.checkout, self.checkout, self.home)
|
||||
assert isinstance(found, ProjectConfig)
|
||||
self.assertEqual(list(found.places)[-2:], ["principles", "touch-predictions"])
|
||||
self.assertEqual(list(found.places)[-2:], ["standards", "touch-predictions"])
|
||||
self.assertEqual(found.paths["touch-predictions"], folder / "docs/touch-predictions.md")
|
||||
self.assertIsNone(found.tracked("touch-predictions"))
|
||||
(folder / "config.toml").write_text(CLIENT + 'touch-predictions = "docs/touch-predictions.md"\n', encoding="utf-8")
|
||||
|
||||
@@ -6,11 +6,18 @@ import unittest
|
||||
|
||||
sys.path.insert(0, str(pathlib.Path(__file__).resolve().parents[1]))
|
||||
|
||||
from loop_claude.project.records import HUMAN_RULE_DIRS
|
||||
from loop_claude.project.records import HUMAN_RULE_DIR
|
||||
from repo_checks import ROOT
|
||||
|
||||
RULE_PATH = rf"(?:{'|'.join(map(re.escape, HUMAN_RULE_DIRS))})/[\w-]+\.md"
|
||||
CITATION = re.compile(rf'`?(?:~/\.claude/)?(CLAUDE\.md|{RULE_PATH})`? → ("[^"]+"(?:,? (?:and )?"[^"]+")*)')
|
||||
# The review standards this repo ships, which a project's config names as `standards` where it keeps them.
|
||||
STANDARDS = "skills/larv-review/standards"
|
||||
# The folders whose files a citation names by path: the judge reads both, the standards where a project's config names them.
|
||||
RULE_DIRS = (HUMAN_RULE_DIR, STANDARDS)
|
||||
RULE_PATH = rf"(?:{'|'.join(map(re.escape, RULE_DIRS))})/[\w-]+\.md"
|
||||
NAMES = r'("[^"]+"(?:,? (?:and )?"[^"]+")*)'
|
||||
CITATION = re.compile(rf'`?(?:~/\.claude/)?(CLAUDE\.md|{RULE_PATH})`? → {NAMES}')
|
||||
# A citation of a file in whichever folder the project's config names as `standards`, checked against the folder this repo ships.
|
||||
STANDARD_CITATION = re.compile(rf"the review standards' `([\w-]+\.md)` → {NAMES}")
|
||||
HEADING = re.compile(r"^#+ (.+?)(?: \(.*\))?$", re.MULTILINE)
|
||||
LEAD = re.compile(r"^(?:- )?\*\*(.+?)(?:\*\*|[:.](?=\*\*| )| —)", re.MULTILINE)
|
||||
DECISION_CITATION = re.compile(r"`?docs/decisions\.md`? → `([^`]+)`")
|
||||
@@ -27,6 +34,7 @@ class Citations(unittest.TestCase):
|
||||
texts = [(path, (ROOT / path).read_text()) for path in filter(None, tracked)]
|
||||
self.assertEqual([f"{path}: {stray}" for path, text in texts for stray in STRAY.findall(text)], [], 'spell a citation `CLAUDE.md` → "Vocabulary"')
|
||||
cited = [(path, file, NAME.findall(run)) for path, text in texts for file, run in CITATION.findall(text)]
|
||||
cited += [(path, f"{STANDARDS}/{file}", NAME.findall(run)) for path, text in texts for file, run in STANDARD_CITATION.findall(text)]
|
||||
self.assertTrue(cited)
|
||||
unresolved = []
|
||||
for path, file, names in cited:
|
||||
@@ -47,8 +55,8 @@ class Citations(unittest.TestCase):
|
||||
topic_rules = (ROOT / "CLAUDE.md").read_text().split("## Topic rules\n")[1].split("\n## ")[0]
|
||||
self.assertEqual(sorted(set(RULE_FILE.findall(topic_rules))), sorted(f"rules/{rule.name}" for rule in (ROOT / "rules").glob("*.md")))
|
||||
|
||||
def test_every_folder_the_judge_reads_rules_from_exists(self):
|
||||
self.assertEqual([folder for folder in HUMAN_RULE_DIRS if not (ROOT / folder).is_dir()], [])
|
||||
def test_the_rules_folder_and_the_review_standards_this_repo_ships_exist(self):
|
||||
self.assertEqual([folder for folder in RULE_DIRS if not (ROOT / folder).is_dir()], [])
|
||||
|
||||
def test_every_decision_title_the_log_lists_at_its_head_is_a_title_in_it(self):
|
||||
log = (ROOT / "docs/decisions.md").read_text()
|
||||
|
||||
+3
-3
@@ -120,9 +120,9 @@ Valid while `~/.claude` is a checkout of this repo.
|
||||
|
||||
2026-10-03, lilleman. Serves goals 1.2 and 1.4. 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, so an answer recorded there is not asked again. 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: 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 they 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. Serves goal 1.2. The judge reads `~/.claude/CLAUDE.md`, each file under `~/.claude/rules/` and each file under `~/.claude/skills/larv-review/standards/` whole. The worker follows them, so a question they answer should not reach the human. Reading whole is safe, because the judge may quote only words that appear in them, and a list of sections would need keeping current.
|
||||
2026-10-03, lilleman. Serves goal 1.2. The judge reads `~/.claude/CLAUDE.md`, each file under `~/.claude/rules/` and each file in the project's review standards, the folder its config sets as `standards`, whole. The worker follows them, so a question they answer should not reach the human. Reading whole is safe, because the judge may quote only words that appear in them, and a list of sections would need keeping current.
|
||||
|
||||
2026-10-03, lilleman. Serves goal 1.2. 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. Claude settled two choices lilleman's 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`, `~/.claude/rules/` or `~/.claude/skills/larv-review/standards/` does not count: the judge reads the live `~/.claude`, which holds the write only once it merges and the checkout is pulled. 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" doesn't hold anything open. The worker's resume prompt states the rule, so a worker whose chunk is held open knows it.
|
||||
2026-10-03, lilleman. Serves goal 1.2. 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. Claude settled two choices lilleman's 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`, `~/.claude/rules/` or the project's review standards does not count: the judge reads the live copy, which holds the write only once it merges and the checkout is pulled. 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" doesn't hold anything open. The worker's resume prompt states the rule, so a worker whose chunk is held open knows it.
|
||||
|
||||
2026-10-17, lilleman, todo item 168. The human answers an interrupt on loop-claude's terminal, and the worker resumes headless with the answer in a `-p` prompt. The judge reads that answer as a `[human]` line, not a `[loop]` one, so it holds the chunk open until the answer is recorded, as it does for an answer typed in claude.
|
||||
|
||||
@@ -328,7 +328,7 @@ Messages keep each file's usual name, such as `todo.md`, as its label, since the
|
||||
|
||||
2026-10-15, lilleman asked for it through todo item 144, implemented by claude. Serves goal 1.1: a cheap reviewer that finds the work below standard can have a more capable one check that ruling, and work below standard gets a more capable rung to fix it, unless the fix changes only prose.
|
||||
|
||||
The work is below standard where systems-architect returns BLOCK, a reviewer reports a finding against larv-review's `standards/quality.md`, or `record-ruling` counts a comprehension seat's vote in a paired ruling as worse. That reviewer or seat may ask, and the worker then relaunches it on the rung loop-claude's prompt names, one above the rung it ran on. `bin/loop_claude/cycle/prompts.py`'s `reruns` names it: the seats run on the project's rung, and the reviewers on the highest of the worker's rung and the one their item's E + I picks. Off the ladder, or for a reviewer or seat already on the top rung, the prompt names none, and its report stands.
|
||||
The work is below standard where systems-architect returns BLOCK, a reviewer reports a finding against the review standards' `quality.md`, or `record-ruling` counts a comprehension seat's vote in a paired ruling as worse. That reviewer or seat may ask, and the worker then relaunches it on the rung loop-claude's prompt names, one above the rung it ran on. `bin/loop_claude/cycle/prompts.py`'s `reruns` names it: the seats run on the project's rung, and the reviewers on the highest of the worker's rung and the one their item's E + I picks. Off the ladder, or for a reviewer or seat already on the top rung, the prompt names none, and its report stands.
|
||||
|
||||
A reviewer's relaunch gets the report that asked and confirms or dismisses each of its findings with a reason, so no finding goes unanswered; a seat's relaunch reads afresh, since a seat reports no findings. The relaunch's report stands in place of the one that asked, in the same round, so it adds no round, and a relaunch cannot ask again. So the round cap still bounds a pass, and one round launches a reviewer at most twice. The ruling that stands is the fourth escalation trigger in `CLAUDE.md`, except where the fix changes only prose: the worker fixes that on its own rung. lilleman ruled that on 2026-11-08 through todo item 276, after PR #432's two quality findings were false claims, one in a docstring and one in a sentence of this file. lilleman also ruled that no ruling raises the judge's rung, which `routing: on a model judge-replay covered` sets.
|
||||
|
||||
|
||||
@@ -9,7 +9,7 @@ You orchestrate, fix, and ship; reviewers only report. Run every reviewer in the
|
||||
|
||||
**Forge-neutral.** Five PR operations recur below: read a PR's diff, open a draft PR, read check status, mark ready, merge. On GitHub and Gitea, `~/.claude/bin/chunk-pr` opens the draft PR, marks it ready and merges it. Read the diff and the checks with the forge's own CLI, `gh` or `tea` per `~/.claude/CLAUDE.md` → "Git, commits, and PRs". On any other forge, achieve all five 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.
|
||||
|
||||
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".
|
||||
The bar a chunk is reviewed to: `quality.md` in the project's review standards, the folder `~/.claude/bin/project-config standards` prints. 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.
|
||||
|
||||
@@ -65,7 +65,7 @@ Give a reviewer without Bash `git ls-files`'s output in its prompt, since some h
|
||||
|
||||
`~/.claude/bin/larv-review` holds this section's mechanical rules: the chunk's review folder, the round count, the paired ruling's base and vote count, the scoring run's trigger; the history's format, its latest places and its count of how often seats agree; and the header of each reviewer's prompt. Run it in the chunk's worktree; `~/.claude/bin/larv-review --help` states each rule. On exit 1, repair what its message names and run it again; when you cannot, ask the user.
|
||||
|
||||
**Reports.** Run `~/.claude/bin/larv-review reviewer-header <pass>` in the chunk's worktree, and open each prompt to an agent under `~/.claude/agents/` with what it prints; then say in a few lines what the change does and which files it touches. The command makes the chunk's review folder and writes the branch diff and the plan's listing into it. The header names that diff, the reviewer's full report, `<pass>-round-<n>.md`, in the folder, the folder of technical principles the project's config sets, the listing, and for architecture and stability the places too. For a reviewer whose definition starts it without `CLAUDE.md`, the header's last line names the file that holds the project principles and decision titles, which the reviewer reads first. For a relaunch one rung up, add `--rerun`: the report becomes `<pass>-round-<n>-rerun.md`, and the header names the report that asked. Before you answer a 🔴 or 🟡, read its entry: Grep the report for the finding's place, with the lines after it, rather than Read the whole report. rule-hook refuses a reviewer's Edit and MultiEdit, and any Write outside `~/.local/state/larv-review/`. Keep the folder after the merge: `review-replay` replays a round from the reports its prompt names.
|
||||
**Reports.** Run `~/.claude/bin/larv-review reviewer-header <pass>` in the chunk's worktree, and open each prompt to an agent under `~/.claude/agents/` with what it prints; then say in a few lines what the change does and which files it touches. The command makes the chunk's review folder and writes the branch diff and the plan's listing into it. The header names that diff, the reviewer's full report, `<pass>-round-<n>.md`, in the folder, the folders of technical principles and review standards the project's config sets, the listing, and for architecture and stability the places too. For a reviewer whose definition starts it without `CLAUDE.md`, the header's last line names the file that holds the project principles and decision titles, which the reviewer reads first. For a relaunch one rung up, add `--rerun`: the report becomes `<pass>-round-<n>-rerun.md`, and the header names the report that asked. Before you answer a 🔴 or 🟡, read its entry: Grep the report for the finding's place, with the lines after it, rather than Read the whole report. rule-hook refuses a reviewer's Edit and MultiEdit, and any Write outside `~/.local/state/larv-review/`. Keep the folder after the merge: `review-replay` replays a round from the reports its prompt names.
|
||||
|
||||
**Precedent, then ask** — for the full scan:
|
||||
|
||||
@@ -104,7 +104,7 @@ A fix meets every row it fits. Prose has no row, so a comment or doc edit inside
|
||||
|
||||
**What a round reviews.** An agent under `~/.claude/agents/` reviews the branch in round 1. From round 2 it reviews only the answers to its last round's findings, and each fix from another pass that re-entered its pass. Prompt it with the path of its last round's report and each finding's answer: the fix's diff, or the reason it was dismissed. Give it each other pass's fix as `git diff <the commit before that fix> <the fix's commit>`, since the fixes may be unpushed, with the finding it answered. It reports only an answer that is plainly wrong or worse than the change it answered, so its pass converges in its second round. Other reviewers review the branch as their tool does.
|
||||
|
||||
**Rung up.** A reviewer rules the work below standard when its report holds systems-architect's BLOCK or a finding against `standards/quality.md`. A comprehension seat does when `record-ruling` counts one of its votes as worse.
|
||||
**Rung up.** A reviewer rules the work below standard when its report holds systems-architect's BLOCK or a finding against the review standards' `quality.md`. A comprehension seat does when `record-ruling` counts one of its votes as worse.
|
||||
|
||||
- **Ask.** Such a reviewer or seat may end its report asking for a rerun one rung up. Relaunch it only on the rung loop-claude's prompt names for it; where the prompt names none, the report stands.
|
||||
- **Relaunch.** Relaunch a reviewer on that rung with the same prompt, except for its header, made with `--rerun` per "Reports"; its report stands in place of the report that asked, in the same round. Relaunch a seat with the same prompt alone; its line replaces the one that asked in the votes file, before `record-ruling` runs. A relaunch cannot ask again.
|
||||
@@ -115,7 +115,7 @@ A fix meets every row it fits. Prose has no row, so a comment or doc edit inside
|
||||
- **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 in the config's principles folder 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". In the release review the whole project is the chunk's change, so nothing lies outside it; "Release review" → "Findings" says which of its findings are filed.
|
||||
- **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.
|
||||
- **New decision.** Each decision a fix or an answer records in `docs/decisions.md` is checked against the project principles per `~/.claude/rules/decisions.md` → "Decisions: one home, each linked to a goal or a technical principle", "Check each new decision against the project's principles", before the commit that records it.
|
||||
- **🔴.** 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, or shown factually wrong, and what disproved it recorded per the 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.
|
||||
|
||||
@@ -12,7 +12,7 @@ A reviewer reads and reports; it doesn't edit anything. It writes no file but it
|
||||
- ❓ **question** for the author: a finding you could not confirm goes here, not above.
|
||||
- 🔀 **escalation** — names the reviewer whose concern it is (`product-owner-reviewer`, `systems-architect` or `/security-review`) and why, in one line.
|
||||
|
||||
A finding against a technical principle names it and the file in the config's principles folder it lives in. A finding against `~/.claude/skills/larv-review/standards/quality.md` names that file and the rule it breaks.
|
||||
A finding against a technical principle names it and the file in the config's principles folder it lives in. A finding against `quality.md`, in the folder your prompt's `Review standards:` line names, names that file and the rule it breaks.
|
||||
|
||||
## Misread
|
||||
|
||||
@@ -28,14 +28,14 @@ A review's first line, derived from the findings:
|
||||
|
||||
## Rung up
|
||||
|
||||
Where your report holds a finding against `~/.claude/skills/larv-review/standards/quality.md`, or you are systems-architect and return BLOCK, you may end it with the line `Rerun one rung up` when you want a more capable reviewer to check that ruling.
|
||||
Where your report holds a finding against `quality.md`, or you are systems-architect and return BLOCK, you may end it with the line `Rerun one rung up` when you want a more capable reviewer to check that ruling.
|
||||
|
||||
## Report
|
||||
|
||||
Write your full report with the Write tool to the file your prompt names. The file is the worker's input, which it searches for each finding's entry, so write it even where your harness says to return findings directly. It holds the verdict, then every finding with its place, its evidence and its fix, as your agent file shapes them. Then return only:
|
||||
|
||||
- the verdict line
|
||||
- one line per finding, in this order: its severity mark, `[misread]` where you marked the finding so, its place, and what is wrong, in one sentence. Where the finding breaks `standards/quality.md` or a file in the config's principles folder, end the line with that file's name. For a 🔀, end it with the reviewer it names. Example: ``🟡 `bin/example.py:42` `parse`: an empty line raises IndexError (technical-principles.md)``
|
||||
- one line per finding, in this order: its severity mark, `[misread]` where you marked the finding so, its place, and what is wrong, in one sentence. Where the finding breaks the review standards' `quality.md` or a file in the config's principles folder, end the line with that file's name. For a 🔀, end it with the reviewer it names. Example: ``🟡 `bin/example.py:42` `parse`: an empty line raises IndexError (technical-principles.md)``
|
||||
- for stability-reviewer, whether the tests passed, and at which commit
|
||||
- `Rerun one rung up`, where your report ends with it
|
||||
- the report's path
|
||||
|
||||
@@ -2,7 +2,7 @@
|
||||
|
||||
**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` only to keep it true.** 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.
|
||||
**Refresh `README.md` only to keep it true.** 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 the 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.
|
||||
|
||||
Reference in New Issue
Block a user