Merge pull request 'Audit only the principles that apply, and rerun only the architecture reviewers a fix answers' (#215) from scoped-audit into main

This commit was merged in pull request #215.
This commit is contained in:
2026-10-04 20:28:07 +02:00
16 changed files with 84 additions and 27 deletions
+2
View File
@@ -20,6 +20,8 @@ Decisions live in `docs/decisions.md`:
- review: `/security-review` is the security pass of record
- review: the premises chunk's whole review is the human's approval
- workflow-bench/: the remote may show the bench cases' names and commit SHAs
- settings.json: Claude Code runs in auto mode with the dangerous-mode prompt skipped
- the repo may name bender, bender-infra and ai-sandbox
- todo.md: one table of items scored by the formula and goal weights it states, held to its bar, ranked by `bin/rank_todo.py`
## Working rules
+1
View File
@@ -2,6 +2,7 @@
## Unreleased
- larv-review's principles audit reads only the files under `~/.claude/principles/` that apply to the project, launching a file's auditor when unsure. A file's `Applies to` line says what it covers; one without the line covers every project. The summary names each file left out. After its first round, the architecture pass reruns the scoring run and only the reviewers whose 🔴 or 🟡 the fixes answer, unless the fixes carry an architectural decision.
- When `loop-claude`'s judge rules a chunk unfinished, the resumed worker is shown the passage the judge quoted as the work remaining. A loop started before this change exits 1 at its next reload; rerun it.
- larv-review's architecture pass and full security scan get short names, `Architecture` and `Full scan`. Each round's commit is titled with its pass's name in lower case: `Answer full scan round 1: …`.
- larv-review's comprehension floor now says, without another file open, what the scoring run measures. A project's `docs/decisions.md` keeps the last scoring run's scores, and a later run scoring below them blocks the merge until fixed. After three rounds larv-review asks you; an unattended run leaves the PR unmerged with the question. A PR under the floor that scores no lower than the last run merges once you decide to ship. A decision in `docs/decisions.md` that lets every chunk ship under the floor counts as yours. A project without those scores gets them at its next scoring run.
+1 -1
View File
@@ -152,7 +152,7 @@ The rules every project follows, compose-not-entangle first: `~/.claude/principl
## Vocabulary
- **chunk** — the unit of work, shipped as one PR; "Working loop" says what it holds.
- **cycle** — in `loop-claude`, worker runs and the judge's verdict on each, until the chunk closes or is left for the next cycle. In between, the human answers any interrupt, or the worker resumes with an answer the judge quoted from `README.md`, `AGENTS.md` or `docs/decisions.md`.
- **cycle** — in `loop-claude`, worker runs and the judge's verdict on each, until the chunk closes or is left for the next cycle. In between, the human answers any interrupt, or the worker resumes with an answer the judge quoted from `README.md`, `AGENTS.md`, `docs/decisions.md` or `~/.claude/CLAUDE.md`.
- **gate** — the merge gate: the checks a PR passes before it merges.
- **interrupt** — `loop-claude` handing the terminal to the human, `claude --resume`, for a decision that is theirs.
- **judge** — the headless claude that reads a worker's transcript each cycle and decides whether to interrupt and whether the chunk is finished.
+1 -1
View File
@@ -1,6 +1,6 @@
# Claude Code configuration
My personal `~/.claude`, version controlled: `CLAUDE.md` and `AGENTS.md` for instructions, the words under `CLAUDE.md` → "Vocabulary"; `agents/` and `skills/`; `principles/` for what the reviewer agents hold every project to; `docs/` for decisions; `settings.json` for the harness and `.claude/settings.json` for the harness inside this repo; `CHANGELOG.md` and `todo.md`; the tools in `bin/`; and `workflow-bench/`, the scripts and prompts of the 2026-09-30 bench of larv-review.
My personal `~/.claude`, version controlled: `CLAUDE.md` and `AGENTS.md` for instructions, the words under `CLAUDE.md` → "Vocabulary"; `agents/` and `skills/`; `principles/` for what the reviewer agents hold projects to; `docs/` for decisions; `settings.json` for the harness and `.claude/settings.json` for the harness inside this repo; `CHANGELOG.md` and `todo.md`; the tools in `bin/`; and `workflow-bench/`, the scripts and prompts of the 2026-09-30 bench of larv-review.
## Goals
+1 -1
View File
@@ -19,7 +19,7 @@ You consider internal logic **only** when it directly affects an external surfac
## Your Review Method
Before anything else, **read the shared principles** at `~/.claude/principles/`. Two of them are your territory: `rest-apis.md` and `frontend.md`. `technical-principles.md` applies where it surfaces externally (timestamps communicated as UTC, idempotent writes). Re-read each time — they change.
Before anything else, **read the shared principles** at `~/.claude/principles/`. Your territory is each file whose `Applies to` line names an external surface; `technical-principles.md` applies where it surfaces externally (timestamps communicated as UTC, idempotent writes). Re-read each time — they change.
1. **Identify the change surface**: Read the recent changes and pinpoint what external behavior is affected. If the change is purely internal with no external impact, say so plainly and stop — don't manufacture concerns.
+1 -1
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/` — not just `technical-principles.md`, also `frontend.md`, `logging.md`, and `rest-apis.md`. These are mandatory org guidelines; all code MUST comply. Map the relevant file(s) to the change (frontend PR → `frontend.md`; API PR → `rest-apis.md`; etc.). Re-read each time — they change. Flag violations prominently.
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.
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 in a temp dir, a targeted test run — before reporting it. 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.**
+9 -5
View File
@@ -2,9 +2,13 @@ import dataclasses
import typing
from failure import Failure
from loop_claude.project.records import HUMAN_RULES, RECORD_FILES
RECORD_PLACES = "README.md's Goals or Audience, AGENTS.md, docs/decisions.md, todo.md or a comment"
ANSWERS_RECORDED = f"every answer the human typed in it that a later chunk could need is recorded in {RECORD_PLACES} at the one place it governs"
# 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) + " or " + HUMAN_RULES
# 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"
JUDGE_RULES = (
"Decide whether the human must now be interrupted. interrupt=true when any of these appear:\n"
"- the agent asks the human anything, seeks approval, or says a decision is the human's, and neither "
@@ -31,9 +35,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 "
"where README.md or the records above hold it, ~/.claude/CLAUDE.md included. It also counts where "
f"the transcript shows the agent writing it into {RECORD_PLACES}; writing it into "
"~/.claude/CLAUDE.md does not count. finished=false when work remains that a further run can "
f"where README.md or the records above hold it, {HUMAN_RULES} included. It also counts where "
f"the transcript shows the agent writing it into {ANSWER_DESTINATIONS}; writing it into "
f"{HUMAN_RULES} 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."
)
+1 -2
View File
@@ -6,12 +6,11 @@ from loop_claude.cycle.archive import archive
from loop_claude.claude_code.session import delete_session, Session, session_open, transcript_file
from loop_claude.effects import Effects
from failure import Failure
from loop_claude.cycle.judge_reply import Finished, Interrupt, QuotedAnswer, Unfinished
from loop_claude.cycle.judge_reply import Finished, Interrupt, QUOTE_SOURCES, QuotedAnswer, Unfinished
from loop_claude.cycle.interrupt import interrupt
from loop_claude.cycle.judge import judge
from loop_claude.project.model_choice import Models
from loop_claude.paths import Paths
from loop_claude.project.records import QUOTE_SOURCES
from loop_claude.claude_code.transcript import read_transcript, render
from loop_claude.cycle.retry import retried
from loop_claude.cycle.worker import run_worker, worker_args
+1 -2
View File
@@ -1,10 +1,9 @@
from loop_claude.cycle.judge_reply import ANSWERS_RECORDED, QuotedAnswer
from loop_claude.cycle.judge_reply import ANSWERS_RECORDED, QUOTE_SOURCES, QuotedAnswer
from loop_claude.claude_code.entries import assistant_parts, ends_stream, hit_limit, limit_said, parse_entry, rejected_until
from loop_claude.effects import Effects
from failure import Failure
from loop_claude.cycle.retry import Limited
from loop_claude.claude_code.transcript import part_line
from loop_claude.project.records import QUOTE_SOURCES
from loop_claude.claude_code.session import Session
PRINTED_TOOL_INPUT = 160
+1 -2
View File
@@ -3,10 +3,9 @@ import pathlib
from loop_claude.project.checkout import read_utf8
from loop_claude.stop import Stop
# The records: these project files and HUMAN_RULES; the judge reads them beside the README's premises.
RECORD_FILES = ("AGENTS.md", "docs/decisions.md")
HUMAN_RULES = "~/.claude/CLAUDE.md"
# The files a quoted answer comes 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) + " or " + HUMAN_RULES
def read_records(root: str, claude_md: pathlib.Path) -> str | Stop:
+11 -2
View File
@@ -36,9 +36,9 @@
## comprehension floor: every dimension and the overall at 7.0 or above, and 0.1.0 waits on it
2026-09-27, lilleman, restating the 2026-09-24 target and extending it to the overall. Serves goal 4. Valid while the scoring run keeps its four seats.
2026-09-27, lilleman, restating the 2026-09-24 target and extending it to the overall. Serves goal 4. Valid while the scoring run keeps its four seats. The decisions to ship under the floor, listed below, stand until `todo.md` item 62 lifts the project to it.
The last scoring run, which the next may not score below (`CLAUDE.md` → "Quality"): PR #208, 2026-10-03, Navigation 7.5, Locality 7.0, Shape 7.13, Self-sufficiency 6.63, overall 6.88.
The last scoring run, which the next may not score below (`CLAUDE.md` → "Quality"): PR #215, 2026-10-04, Navigation 7.38, Locality 6.63, Shape 7.0, Self-sufficiency 6.88, overall 6.88.
lilleman decided to ship each of these under the floor on the day listed. Each line gives its last scores (Navigation, Locality, Shape, Self-sufficiency, overall):
@@ -49,6 +49,7 @@ lilleman decided to ship each of these under the floor on the day listed. Each l
- 2026-10-02, PR #198: 7.63, 6.88, 7.38, 6.75, 7.13.
- 2026-10-03, PR #202: 7.5, 7.0, 7.0, 6.75, 7.0.
- 2026-10-03, PR #208: 7.5, 7.0, 7.13, 6.63, 6.88.
- 2026-10-04, PR #215: 7.38, 6.63, 7.0, 6.88, 6.88.
## loop-claude: each project's model lives in `~/.claude/loop-claude-models.json`, which only loop-claude writes
@@ -97,3 +98,11 @@ lilleman decided to ship each of these under the floor on the day listed. Each l
## todo.md: one table of items scored by the formula and goal weights it states, held to its bar, ranked by `bin/rank_todo.py`
2026-10-02, lilleman. Serves goal 4: findings were filed faster than chunks closed them, so the plan grew without telling what mattered. Each item is scored as `CLAUDE.md` → "Todo items" says; this repo's formula counts value highest and size least. An item under the bar is not kept; this repo's bar started at 10 and was set to 9 the same day, purging the 17 items under it. An Exempt cell keeps a row past the bar where a rule needs it kept. lilleman retired the two decisions whose plans the purge removed: the stats line in the transcript archive, and three benches before a workflow change merges. A finding under the bar is recorded nowhere, so a later review may raise it again, and the run rescores it. That costs one scoring; a ledger of dropped findings would regrow the list the bar caps. larv-review's "Round cap" → "Done" counts a finding named under the bar as settled, so one raised again holds no pass open. `rank_todo.py --check` is part of larv-review's gate, since only a check keeps the stored Score from going stale. The format is mandatory in every project, as the premises are (goal 4.3); the formula, bar and weights are each project's own. A script ranks the table so a re-rank after each addition or edit is deterministic and cheap. A 🟡 against a technical principle is exempt as `principle`, because its audience value scores low and the bar would drop every one. A 🟢 against a principle is scored like any other finding. Valid while one human sets the bar and reads the ranking, and while the items marked `principle` stay few enough to rank.
## settings.json: Claude Code runs in auto mode with the dangerous-mode prompt skipped
2026-10-04, lilleman, answering the principles audit of PR #215. Serves goal 4: this setup is meant to run in a sandbox and to work autonomously, so tool access is granted by the sandbox, as "Always grant explicit access to data" in `principles/technical-principles.md` asks. Valid while every machine taking this checkout is such a sandbox.
## the repo may name bender, bender-infra and ai-sandbox
2026-10-04, lilleman, answering the principles audit of PR #215. Serves goal 3, which keeps credentials, transcripts and memory files off the remote; the names of the host, its infrastructure project and the sandbox VM are none of those. Valid while the repo names them without their addresses or credentials.
+2
View File
@@ -1,5 +1,7 @@
# Frontend principles
Applies to a project with a browser frontend.
General principles (KISS, DRY, …) live in `technical-principles.md` and apply here too.
## Foundational stances
+2
View File
@@ -1,5 +1,7 @@
# Logging
Applies to a service that writes logs.
## Levels
Log levels have a standard, RFC5424: { emerg: 0, alert: 1, crit: 2, error: 3, warning: 4, notice: 5, info: 6, debug: 7 }.
+1 -1
View File
@@ -1,6 +1,6 @@
# REST APIs
Conventions for any REST API we build, regardless of product or stack. Existing APIs keep their current shapes until their next major version — reviewers flag deviations on new surfaces, not old ones.
Applies to every REST API we build, regardless of product or stack. Existing APIs keep their current shapes until their next major version — reviewers flag deviations on new surfaces, not old ones.
## URLs & query parameters
+5 -5
View File
@@ -30,7 +30,7 @@ A pass is one kind of review, a row of the table, named by its first column. Its
| Pass | Reviewer | Trigger |
|------|----------|----------------------------------------|
| Architecture | systems-architect, then principles-auditor and the scoring run | carries an architectural decision: a new, restructured or moved component, module, service or boundary; a new dependency or first use of an infrastructure pattern (queue, cron, cache, websocket, …); a new or changed external contract (routes, request/response shapes, events, webhooks, published file formats, CLI flags and exit codes); a schema change beyond an additive column; the chunk shipping its release's last item |
| Architecture | systems-architect, then principles-auditor and the scoring run | ships its release's last item, or carries an architectural decision: a new, restructured or moved component, module, service or boundary; a new dependency or first use of an infrastructure pattern (queue, cron, cache, websocket, …); a new or changed external contract (routes, request/response shapes, events, webhooks, published file formats, CLI flags and exit codes); a schema change beyond an additive column |
| Security | `/security-review` | changes code or config; a fix, only where it opens an untrusted-input boundary or touches authn/authz, secrets or crypto |
| Full scan | the `claude-security` plugin at high effort: `/claude-security scan this branch's changes at high` | touches authn/authz, secrets or crypto, opens an untrusted-input boundary, or adds an external surface |
| Stability | stability-reviewer | changes code, config or tests; a fix, only where it changes behaviour: what the code or its tests do |
@@ -51,10 +51,10 @@ Give a reviewer without Bash the branch diff and `git ls-files`'s output in its
**Round cap.**
- **Round.** A round is one launch of a pass's reviewer: the first, each re-entry, and the rerun after the architect returns Stage 0 questions ("Architecture" below).
- **Architecture round.** The architecture pass's round is the architect (unless skipped), the principles audit and the scoring run, so a fix to any of their findings reruns the whole round.
- **Architecture round.** The architecture pass's first round is the architect (unless skipped), the principles audit and the scoring run. A later round relaunches the scoring run and each reviewer whose 🔴 or 🟡 the previous round's fixes answer. Where those fixes carry an architectural decision, the whole round runs again, the architect included.
- **Auto-reviewer.** The external auto-reviewer (§4) is a pass of its own, each review it posts a round.
- **Count.** Close each round with one commit that holds the round's fixes and is titled `Answer <pass> round <n>: …`, `<pass>` being the pass's name in lower case, such as `full scan`. A round that changed nothing gets an empty commit (`git commit --allow-empty`). Push the commits when §4 runs next, where there is a remote. A pass's count is the highest `<n>` among titles holding `Answer <pass> round <n>:` in `git log origin/<default branch>..HEAD` after a `git fetch`, or in `git log <default branch>..HEAD` with no remote. The auto-reviewer's count is the number of its reviews on the PR.
- **Later rounds.** From round 2, prompt an agent under `~/.claude/agents/` with the previous round's findings verbatim and what changed since: `git diff <the commit the previous round reviewed> HEAD`, since the fixes may be unpushed.
- **Later rounds.** From round 2, prompt an agent under `~/.claude/agents/` with its own last round's findings verbatim and what changed since: `git diff <the commit that round reviewed> HEAD`, since the fixes may be unpushed.
- **Done.** A pass is done when its latest round leaves no 🔴 or 🟡 standing: none was reported, or each was shown factually wrong, declined, filed, or named under the bar per "Findings". Resolve that round's 🟢s and ❓s per "Findings" too.
- **Cap.** A pass takes at most three rounds per chunk. Instead of a fourth, list what is open and ask the user. For the auto-reviewer, ask before the push that would summon its fourth, and hold the fixes unpushed until the answer.
- **Answer.** A yes grants that pass one more round, after which the ask repeats; a no leaves the PR unmerged.
@@ -81,7 +81,7 @@ Launch systems-architect: review the system as a whole entered through this chan
- **Stage 0 questions returned**: relay them to the user, record the answers in the README, re-run once.
- **BLOCK** → confirm with the user first when the restructure materially reshapes their PR; until confirmed, no later pass runs.
Then the principles audit: one principles-auditor per file in `~/.claude/principles/` and one for the README's goals, each over the whole project in every round.
Then the principles audit: one principles-auditor for the README's goals, and one per file in `~/.claude/principles/` whose `Applies to` line the project meets, judged from the README, `git ls-files` and the branch diff. A file without the line applies to every project. Unsure → launch it.
Then the comprehension floor, which the scoring run measures. Four simulated readers — Junior A, Mid A, the maintainability senior and the inherited architect — each read the whole project, not the diff, and score it from 1 to 10 overall and on four dimensions: Navigation, Locality, Shape and Self-sufficiency. A seat's overall may not exceed its lowest dimension by more than 1. Each score is the mean of the four seats, to two decimals. Launch the seats per `~/.claude/skills/comprehension-panel/SKILL.md` → "The scoring run".
@@ -132,4 +132,4 @@ Launch prose-reviewer with what the diff touched and every section this review c
## 6. Wrap up
Summarize: PR URL and final state, every reviewer's verdict, rounds per pass, passes skipped, findings fixed vs answered vs declined vs open — each answer with what settles it, each decline with its reason, a 🟡's with the goal or technical principle it rests on — CI status, decisions recorded (file paths), `todo.md`/`CHANGELOG.md` updated, and any 🔀 escalation left for the user.
Summarize: PR URL and final state, every reviewer's verdict, rounds per pass, passes skipped, principles files left out with why, findings fixed vs answered vs declined vs open — each answer with what settles it, each decline with its reason, a 🟡's with the goal or technical principle it rests on — CI status, decisions recorded (file paths), `todo.md`/`CHANGELOG.md` updated, and any 🔀 escalation left for the user.
+44 -4
View File
@@ -6,7 +6,7 @@
`Bar = 9`
`Next ID = 60`
`Next ID = 71`
| Goal | W |
|---|---|
@@ -24,22 +24,34 @@
| ID | Release | Exempt | Item | R | S | A | G | Goals | Score |
|---|---|---|---|---|---|---|---|---|---|
| 64 | 0.1.0 | security | **Check the `settings.json` diff for secrets before `AGENTS.md`'s working rule pushes it.** | 2 | 2 | 6 | 7 | 3 | 20.4 |
| 1 | 0.1.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 | 2, 3 | 27.8 |
| 23 | 0.1.0 | | **Launch a principles auditor only for a principles file the project shows applies, and rerun only the reviewer whose finding a fix answers.** | 3 | 4 | 7 | 8 | 4.4 | 13.5 |
| 63 | 0.1.0 | | **Give README → Install a command that checks the repo out into the `~/.claude` that Claude Code has already created.** | 2 | 2 | 7 | 8 | 1 | 27.5 |
| 60 | 0.1.0 | | **Rerun the scoring run before merge whenever a fix landed after the last scoring run, and count a score under the floor or the ratchet as the scoring run's 🔴.** | 3 | 3 | 6 | 7 | 4.1 | 16.1 |
| 62 | 0.1.0 | defect | **Lift Locality, Self-sufficiency and the overall to the comprehension floor, at the places the seats name.** | 4 | 6 | 6 | 8 | 4.1 | 15.5 |
| 65 | 0.1.0 | | **Archive each judge reply the loop rejects.** | 3 | 4 | 4 | 5 | 2 | 12.9 |
| 21 | 0.1.0 | | **Give `settings.json`'s model one writer, and sort its keys.** | 3 | 3 | 6 | 7 | 4.3 | 12.9 |
| 49 | 0.1.0 | principle | **Check that `AGENTS.md` lists exactly the titles of `docs/decisions.md`.** | 1 | 2 | 5 | 6 | 4.3 | 12.5 |
| 12 | 0.1.0 | | **Run the test suite in CI on every PR, or record in `docs/decisions.md` why the local run is enough.** | 2 | 4 | 4 | 6 | 4.1 | 11.7 |
| 59 | 0.1.0 | | **Bound a run of unfinished verdicts on one chunk, so a worker and judge that disagree cannot cycle unattended without end.** | 3 | 3 | 6 | 6 | 4.4 | 10.9 |
| 5 | 0.1.0 | decision | **Key a project on its checkout's full path, and refuse to start while another session uses that key.** | 5 | 5 | 5 | 6 | 4.1 | 10.5 |
| 66 | 0.1.0 | principle | **Hold systems-architect's method thresholds only while the comprehension panel finds the flagged code hard.** | 3 | 3 | 4 | 5 | 4.1 | 9.9 |
| 4 | 0.1.0 | | **Name each chunk's archive folder by the chunk's start time, so `<key>/` lists chunks in the order they ran.** | 3 | 2 | 4 | 3 | 2 | 9.8 |
| 50 | 0.1.0 | principle | **Grant the bench's runs only the tools a review needs, in place of skipping every permission.** | 2 | 2 | 3 | 4 | 3 | 9.7 |
| 69 | 0.1.0 | principle | **Measure test coverage, so a chunk that lowers it is seen.** | 3 | 4 | 4 | 5 | 4.1 | 9.6 |
| 29 | 0.1.0 | | **Make the contributor a standing member of every project's audience, unless its `## Audience` says maintainability does not matter.** | 2 | 2 | 3 | 5 | 4.1, 4.4 | 9.1 |
| 68 | 0.1.0 | principle | **Test `workflow-bench/compare.py`'s blinding and `bench.py`'s run plan.** | 2 | 4 | 3 | 5 | 4.1 | 8.6 |
| 67 | 0.1.0 | principle | **Point stability-reviewer at the technical principles in place of its own restatement of them.** | 2 | 3 | 4 | 5 | 4.3 | 8.6 |
| 52 | 0.1.0 | principle | **Record why this checkout lives in Claude Code's own directory, or move it out and link it in.** | 6 | 6 | 3 | 5 | 1 | 8.5 |
| 6 | 0.1.0 | decision | **Move what `loop-claude` writes out of `~/.claude.json`, and ask the human about each write that must stay.** | 5 | 5 | 4 | 5 | 4.1 | 7.4 |
| 51 | 0.1.0 | principle | **Hand loop-claude's terminal output to an injected effect, so no storage or retry function prints.** | 3 | 5 | 3 | 5 | 4.1 | 7.4 |
## Details
### 64. Check the `settings.json` diff for secrets before `AGENTS.md`'s working rule pushes it.
Goal 3, raised by the principles audit of PR #215. Exposure: Claude Code writes `env` and `mcpServers` into `settings.json`, where a token can land. Path: `AGENTS.md` → "Working rules" commits uncommitted changes to that file on a branch, and larv-review §2 pushes it and opens the PR before `/security-review` runs, so a token reaches the remote unchecked.
### 1. Say in README → Install how the transcript archive is backed up, once bender-infra backs up ai-sandbox's data volume.
It lives under `~/.claude`, which `.gitignore` keeps from the remote, so a lost disk loses every unattended run's record. Back it up only to a destination private to me and encrypted at rest: the worker runs with permissions bypassed, so the archived tool results can hold credentials it read.
@@ -48,9 +60,21 @@ It lives under `~/.claude`, which `.gitignore` keeps from the remote, so a lost
The README line covers the bench's transcripts in `workflow-bench/logs/` too (goal 2).
### 23. Launch a principles auditor only for a principles file the project shows applies, and rerun only the reviewer whose finding a fix answers.
### 63. Give README → Install a command that checks the repo out into the `~/.claude` that Claude Code has already created.
On this repo the frontend, REST and logging auditors each read the whole project to report "does not apply", and one 🟢 fix reruns ten whole-project reads.
Goal 1, raised by the principles audit of PR #215: Claude Code creates `~/.claude` on its first run, `git clone` refuses a directory that is not empty, and Install names neither the remote nor another way in.
### 60. Rerun the scoring run before merge whenever a fix landed after the last scoring run, and count a score under the floor or the ratchet as the scoring run's 🔴.
Raised by the systems-architect review of PR #215. A stability, product-owner, prose or auto-reviewer fix reruns no scoring run unless it carries an architectural decision or answers an architecture 🔴 or 🟡. It merges unscored, so the `comprehension floor:` entry records scores for an earlier commit, and the next chunk's ratchet inherits a fall it did not cause. "Round cap" → "Done" and "Re-entry" → "Rerun" count only 🔴 and 🟡, and nothing makes a score under the floor one. A commit that only edits `docs/decisions.md`, `todo.md` or `CHANGELOG.md` needs no rerun.
### 62. Lift Locality, Self-sufficiency and the overall to the comprehension floor, at the places the seats name.
Raised by the principles audit of PR #215 against KISS, in `principles/technical-principles.md`, and goal 4.1: the `comprehension floor:` entry in `docs/decisions.md` lists seven decisions to ship under the floor, and 0.1.0 waits on the floor. PR #215's last run put Locality at 6.63 and Self-sufficiency and the overall at 6.88. Its seats named, under Locality: the judge's contract spread over `cycle/judge_reply.py`, `cycle/worker.py` and `cycle/run.py`; `remaining`, which is `Unfinished.evidence` under another name, threaded through `loop/main.py`, `loop/reload.py`'s `LoopRun`, `cycle/run.py` and `worker_args`; the `quoted_answers` cap held by case order in `cycle/states.py`'s `transition` and restated in `run.py`'s `question_for`; the four outcome texts `run.py` builds inline for `archive`. Under Self-sufficiency: `skills/larv-review/SKILL.md`, which needs `CLAUDE.md` → "Vocabulary" open beside it; the archive layout, defined only in `bin/loop_claude/loop/main.py`'s docstring and not at `cycle/archive.py`; `JUDGE_RULES`' precedence in `cycle/judge_reply.py`, restated by `verdict_from`'s branch order and the `Reply` field descriptions; the `sys.path` insert in `bin/loop-claude` that the `from failure import` lines rely on, unstated at the import sites.
### 65. Archive each judge reply the loop rejects.
Goal 2, raised by the principles audit of PR #215: the judge runs with `--no-session-persistence`, and the first two rejected replies reach only stderr, so the archive cannot answer the 3am question of why the loop rejected a verdict.
### 21. Give `settings.json`'s model one writer, and sort its keys.
@@ -74,6 +98,10 @@ Raised by the product-owner review of PR #211. The resumed worker gets the judge
The key names the project's session, archive folder and models entry. `project_key` drops the leading `/`, so `~/code/a` and `/a` share all three, and one loop can resume or delete the other's session.
### 66. Hold systems-architect's method thresholds only while the comprehension panel finds the flagged code hard.
KISS, in `principles/technical-principles.md`, which keeps a limit only while readers find the flagged code hard. `agents/systems-architect.md` makes cyclomatic 7 and 24 lines gate rules from the first commit, a 🔴 unless a reason is stated.
### 4. Name each chunk's archive folder by the chunk's start time, so `<key>/` lists chunks in the order they ran.
Today the folder is the SHA-256 of the transcript's first timestamped line, which tells the human nothing; that line carries the start time. Drop the fallback to the first line, which every chunk of a project shares, and give the tests' fake transcripts ISO timestamps.
@@ -82,10 +110,22 @@ Today the folder is the SHA-256 of the transcript's first timestamped line, whic
"Always grant explicit access to data", in `principles/technical-principles.md`: `workflow-bench/bench.py` starts claude with `--dangerously-skip-permissions`, and no rule confines it to a sandbox, so a run on the host reaches the host's credentials and other checkouts.
### 69. Measure test coverage, so a chunk that lowers it is seen.
"Test coverage should not decline", in `principles/technical-principles.md`: nothing reports coverage, so a chunk that deletes a test or adds untested code passes unseen.
### 29. Make the contributor a standing member of every project's audience, unless its `## Audience` says maintainability does not matter.
State that in `CLAUDE.md`'s goals-and-audience rule, and have larv-review's comprehension floor name the contributor as the reader it serves. The floor then gates every chunk while the contributor stands, and a project that drops them skips it.
### 68. Test `workflow-bench/compare.py`'s blinding and `bench.py`'s run plan.
"Most, if not all, code should have automated tests", in `principles/technical-principles.md`: `compare.blind()` keeps the comparison blind, and a version name it misses invalidates the bench silently.
### 67. Point stability-reviewer at the technical principles in place of its own restatement of them.
DRY, in `principles/technical-principles.md`: `agents/stability-reviewer.md` restates principles in its own words, and the copy has drifted: it asks for "properly randomised UUIDs" where the principle requires UUID v7.
### 52. Record why this checkout lives in Claude Code's own directory, or move it out and link it in.
"One owner per value" and "Prefer the vendor-neutral option", in `principles/technical-principles.md`: git, Claude Code and loop-claude all write `~/.claude`, kept apart only by the `.gitignore` allowlist, and the repo's records live in a vendor directory.