diff --git a/CHANGELOG.md b/CHANGELOG.md index 97b7c486..3feadc5a 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,6 +2,7 @@ ## Unreleased +- larv-review's principles audit reads only the files under `~/.claude/principles/` that apply to the project, each file's `Applies to` line saying what it covers; the summary names each file left out. After its first round, the architecture pass reruns only the reviewers whose findings 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. diff --git a/principles/frontend.md b/principles/frontend.md index ec4895eb..284f404e 100644 --- a/principles/frontend.md +++ b/principles/frontend.md @@ -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 diff --git a/principles/logging.md b/principles/logging.md index 236c53e0..85e4dc63 100644 --- a/principles/logging.md +++ b/principles/logging.md @@ -1,5 +1,7 @@ # Logging +Applies to an application 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 }. diff --git a/principles/rest-apis.md b/principles/rest-apis.md index ac879145..aa3d74f2 100644 --- a/principles/rest-apis.md +++ b/principles/rest-apis.md @@ -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 diff --git a/principles/technical-principles.md b/principles/technical-principles.md index 48e67994..f3a58dfd 100644 --- a/principles/technical-principles.md +++ b/principles/technical-principles.md @@ -1,5 +1,7 @@ # Purpose and goals of our principles +Applies to every project. + 1. Efficiently and sustainably deliver technical solutions with fewer bugs that are easier to resolve. 2. Make our technical solutions easier to maintain and further develop. diff --git a/skills/larv-review/SKILL.md b/skills/larv-review/SKILL.md index c41b9695..3f09d159 100644 --- a/skills/larv-review/SKILL.md +++ b/skills/larv-review/SKILL.md @@ -51,7 +51,7 @@ 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 only the reviewers whose findings its fixes answer, or the whole round where the fixes fire the pass's trigger. - **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 round : …`, `` 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 `` among titles holding `Answer round :` in `git log origin/..HEAD` after a `git fetch`, or in `git log ..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 HEAD`, since the fixes may be unpushed. @@ -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, each auditor over the whole project: 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 and `git ls-files`. Unsure → launch it. Name each file left out, and why, in the summary. 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". diff --git a/todo.md b/todo.md index f07556c7..0587a566 100644 --- a/todo.md +++ b/todo.md @@ -25,7 +25,6 @@ | ID | Release | Exempt | Item | R | S | A | G | Goals | Score | |---|---|---|---|---|---|---|---|---|---| | 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 | | 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 | @@ -48,10 +47,6 @@ 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. - -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. - ### 21. Give `settings.json`'s model one writer, and sort its keys. Claude Code rewrites `"model"` in this tracked file whenever a model is picked, so one `/model` dirties the checkout and overrides the synced choice.