Run the architecture and principles passes only in a release review before each cut
This commit is contained in:
@@ -26,7 +26,7 @@ Decisions live in `docs/decisions.md`:
|
||||
- review: `/security-review` is the security pass of record, except where the full scan runs on the same change and replaces it
|
||||
- review: a comment is prose in any file; a branch changing only Markdown no agent follows runs only the prose pass and, for README or docs an outside reader lands on, the product-owner pass; plan rows a chunk files from a finding, re-scores or moves get no review
|
||||
- review: a fix for a 🔴 reruns the pass that found it, unless that pass is at its cap, and each pass whose row in `larv-review` §3's re-entry table the fix meets; from round 2 a pass reviews only the answers to its last round's findings and any other pass's fix that re-entered it; a fix for a 🟡, a 🟢, a ❓ or a prose finding reruns none
|
||||
- review: a pass gets at most two rounds per chunk, with no third and no ask for one; the fixes answering round 2 merge once the gate passes
|
||||
- review: a pass gets at most two rounds per chunk, and the release review's architecture and principles passes five, with no more and no ask for more; the fixes answering a pass's last round merge once the gate passes
|
||||
- review: a pass skips only on a precedent: a decision, or a plan item crediting the pass, that the repo held before the chunk began
|
||||
- review: a project decision may opt every chunk out of the architect, the product-owner pass or the comprehension check, and a project opting out of the comprehension check voids code health
|
||||
- review: a project decision may suspend the comprehension check for the plan items it names
|
||||
@@ -35,9 +35,10 @@ Decisions live in `docs/decisions.md`:
|
||||
- review: an ask no user answers leaves the PR unmerged
|
||||
- review: each reviewer under `agents/` writes its full report into the chunk's review folder under `~/.local/state/larv-review/` and returns the worker its verdict and one line per finding; rule-hook refuses its Edit and MultiEdit, and any Write outside `~/.local/state/larv-review/`
|
||||
- review: stability and product-owner report only a defect, a broken requirement of the plan or the goals, a breach of a technical principle, or for stability a hard place the change touches; each architect finding names a later change the PR makes harder; prose runs only on a chunk that changes prose
|
||||
- review: the comprehension check records how hard a project is to read and blocks no merge: a paired ruling against the last measured commit where the architecture pass ran, and the four-seat scoring run, once when an item names the floor and twice on one head when a release's items run out
|
||||
- review: the architecture and principles passes run only in the release review, a release's last chunk, which must land before the release is ready to cut; between releases the product-owner pass reviews changes to what consumers rely on
|
||||
- review: the comprehension check records how hard a project is to read and blocks no merge: a paired ruling against the last measured commit in the release review, and the four-seat scoring run, once when an item names the floor and twice on one head when a release's items run out
|
||||
- review: the premises chunk's whole review is the human's approval
|
||||
- review: the principles audit runs on every chunk that changes code, config or tests, reads the project whole with one auditor checking the goals and every principles file that applies, and runs on no other chunk
|
||||
- review: the principles audit runs only in the release review, and reads the project whole with one auditor checking the goals and every principles file that applies
|
||||
- review: the stability pass mutation-tests the lines a chunk changes, in place of measuring test coverage
|
||||
- routing: a chunk's worker runs on the rung its item's L picks, below the project's rung too; its reviewers run on the highest of the worker's rung, the project's and the one picked by the highest E + I among the chunk's items, unless a replay lowered their pass or the branch changes only Markdown no agent follows, which reviews on the project's rung; the seats and the security pass always on the project's
|
||||
- routing: a review pass runs below the project's rung only on a rung that a replay of its rounds shows finding every 🔴 and 🟡 the project's rung finds, and only where the E + I steps no review up and the worker runs no higher than the project's rung, then even below the worker's; no pass has such a rung
|
||||
|
||||
@@ -2,6 +2,10 @@
|
||||
|
||||
## Unreleased
|
||||
|
||||
- larv-review's architecture and principles passes now run only in a new release review: the chunk that runs once a release holds no item and changes are unreleased, before the release is ready to cut. Each reads the whole project, may refactor boldly and takes up to five rounds; their fixes take the stability, security, overrides and prose passes, two rounds each. No other chunk runs either pass, so a chunk that changes code no longer waits on the principles audit. Between releases, the product-owner pass now also reviews changes to routes, request and response shapes, events, webhooks, published file formats, CLI flags and exit codes, which the architecture trigger used to cover. The comprehension check's paired ruling moves to the release review too.
|
||||
- `chunk-preflight` now reports a release review due where it reported a release ready to cut, until a commit titled `Release review of <release>` follows the newest `v*` tag on the default branch. Open the review's branch with that commit.
|
||||
- rule-hook's `round-cap` and `larv-review round-count` allow the architecture and principles passes five rounds.
|
||||
|
||||
- Haiku 5.5 is off the routing ladder, which now runs from Sonnet 5.5 at high to Fable 5.1 at max. A Sonnet 5.5 project's L 1 and L 2 workers now run on Sonnet 5.5 at high, where they ran on Haiku 5.5 at max: such a chunk took more than two hours and 3.1 million output tokens on a README change. A review replay can now lower a pass only to Sonnet 5.5 at high. `subagent-rung`, `review-replay` and `judge-replay` treat Haiku 5.5 as a model off the ladder.
|
||||
- larv-review runs fewer reviews on changes that hold no code:
|
||||
- A fix for a 🟡 no longer reruns the pass that found it. Only a 🔴 fix does, with each pass whose re-entry row the fix meets.
|
||||
|
||||
@@ -7,7 +7,7 @@ How work proceeds in any repo, unless the repo's `AGENTS.md` says otherwise. The
|
||||
- **Until `README.md` has a `## Goals` and an `## Audience` section, writing them is the only work.** Not even planning in `todo.md`. Both are public: an outside reader judges a project by where it is heading and who it is for. Goals or an audience written anywhere else, such as `AGENTS.md` or `docs/`, do not count; the one exception is code health, which "Shared goal" below states for every project.
|
||||
- **Plan `todo.md` as one scored table, in the shape whose example `~/.claude/bin/rank_todo.py --help` shows**: every item names the release that ships it. Until `todo.md` has that shape, reshaping it is the only work, and the human approves it.
|
||||
- **When the next release has no items and no work has landed towards it, plan it as this chunk.** Move the highest-scoring items of later releases into it, and get the human's approval of that set before writing any code.
|
||||
- **When the next release has no items left and work has landed towards it, it is finished: stop.** Report what it holds and that it is ready to cut. Under `/loop`, this ends the loop. Until the human cuts it, only a security fix lands, into that release; never start a later release's items or plan a new one.
|
||||
- **When the next release has no items left and work has landed towards it, its release review is the chunk** (`larv-review` §3 → "Release review"). **Once that has merged, the release is finished: stop.** Report what it holds and that it is ready to cut. Under `/loop`, this ends the loop. Until the human cuts it, only a security fix lands, into that release; never start a later release's items or plan a new one.
|
||||
- **Open every chunk with one line:** the last version cut, how many changes are unreleased (the entries under `CHANGELOG.md` → `## Unreleased`, or else the commits since the last tag), and the release this chunk ships into. A repo that publishes nothing says so once.
|
||||
- **Read the README's `## Goals` and `## Audience` before starting a chunk, unless your prompt quotes them.** The chunk's items set its scope. The goals choose between ways to deliver those items, and never add to them.
|
||||
- **Read the plan and the decisions only as far as the chunk needs.** Where your prompt quotes `chunk-preflight`'s facts, they hold the next item's L, E + I, tagline and detail, and the items that may join it; read further only what they leave out. Otherwise run `grep -n '^## Details' todo.md`, then read `todo.md` with the Read tool up to the line it prints, or whole when it prints none. Then read the details of only the items the chunk takes. `AGENTS.md` lists every decision's title. Read the entry under a title in `docs/decisions.md` only where the title leaves open what the chunk or the review needs.
|
||||
@@ -132,6 +132,7 @@ Claude Code reads this section by its heading when it compacts a conversation. K
|
||||
- **premises** — the goals and audience under `## Goals` and `## Audience` in the project's `README.md`, with code health ("Shared goal") first among the goals unless the README voids it.
|
||||
- **project's rung** — the cheapest rung on loop-claude's routing ladder of the project's model, which is the model loop-claude's prompt names as the project's, or else your own.
|
||||
- **release** — a semver version the human cuts.
|
||||
- **release review** — a release's last chunk: the architecture and principles passes over the whole project, before the release is ready to cut; `larv-review` §3 → "Release review".
|
||||
- **reviewer** — a reporter of findings: an agent under `~/.claude/agents/`, `/security-review` or a forge's auto-reviewer.
|
||||
- **round cap** — the rounds one pass may take per chunk; `larv-review` §3 → "Round cap".
|
||||
- **scoring run** — each seat scores the project from 1 to 10, overall and on each dimension. `larv-review` §3 → "Comprehension check" says which seats score and when one is due.
|
||||
|
||||
@@ -35,4 +35,4 @@ The prompt hands you these. Beyond them, read only what a finding needs checking
|
||||
|
||||
1. **What the diff touched**: every markdown line, comment and printed text, such as help or an error, that the diff adds or changes.
|
||||
2. **What the review cited**: each section the prompt names, with the code it governs.
|
||||
3. **Every prose file the repo owns**, when the prompt says the architecture pass's trigger fired. This sweep catches files that grew a paragraph per chunk, which no single diff shows.
|
||||
3. **Every prose file the repo owns**, when the prompt says the chunk is a release review. This sweep catches files that grew a paragraph per chunk, which no single diff shows.
|
||||
|
||||
+26
-6
@@ -18,6 +18,8 @@ class LastCut:
|
||||
commits: int | Failure
|
||||
# todo.md's text at the tag and at each later commit that changed it, oldest first, as named_releases reads them; empty without a tag.
|
||||
todos_since: list[str] | Failure
|
||||
# Whether a release review has landed since the tag, as release_reviewed reads it.
|
||||
reviewed: bool | Failure = False
|
||||
|
||||
|
||||
@dataclasses.dataclass(frozen=True)
|
||||
@@ -53,6 +55,13 @@ class ReadyToCut:
|
||||
release: tuple[int, int, int] | None
|
||||
|
||||
|
||||
@dataclasses.dataclass(frozen=True)
|
||||
class ReviewDue:
|
||||
"""The next release holds no item and work has landed towards it, but no release review has landed since the cut: `~/.claude/skills/larv-review/SKILL.md` → "Release review"."""
|
||||
# The next release, None where todo.md has named none since the cut.
|
||||
release: tuple[int, int, int] | None
|
||||
|
||||
|
||||
@dataclasses.dataclass(frozen=True)
|
||||
class Unplanned:
|
||||
"""The next release holds no item, and no work has landed towards it."""
|
||||
@@ -66,7 +75,7 @@ class Unknown:
|
||||
|
||||
|
||||
# How the plan stands to the last cut, with the item the next chunk takes first where there is one.
|
||||
Pick = Next | Cut | ReadyToCut | Unplanned | Unknown
|
||||
Pick = Next | Cut | ReadyToCut | ReviewDue | Unplanned | Unknown
|
||||
|
||||
|
||||
@dataclasses.dataclass(frozen=True)
|
||||
@@ -81,7 +90,14 @@ def default_plan(root: str, ref: str) -> DefaultPlan:
|
||||
"""What ref, the default branch as last fetched, holds for the pick, read in the checkout at root."""
|
||||
tag = newest_release_tag(ref, root)
|
||||
commits = tag if isinstance(tag, Failure) else commits_since(tag, ref, root)
|
||||
return DefaultPlan(file_at(ref, "todo.md", root), LastCut(tag, file_at(ref, "CHANGELOG.md", root), commits, todos_since(tag, ref, root)))
|
||||
reviewed = tag if isinstance(tag, Failure) else release_reviewed(tag, ref, root)
|
||||
return DefaultPlan(file_at(ref, "todo.md", root), LastCut(tag, file_at(ref, "CHANGELOG.md", root), commits, todos_since(tag, ref, root), reviewed))
|
||||
|
||||
|
||||
def release_reviewed(tag: str | None, ref: str, cwd: str) -> bool | Failure:
|
||||
"""Whether ref holds, after tag or in all where tag is None, a commit titled as a release review opens: `Release review of <release>`."""
|
||||
titles = git("log", "--format=%s", f"{tag}..{ref}" if tag else ref, cwd=cwd)
|
||||
return titles if isinstance(titles, Failure) else any(title.startswith("Release review of ") for title in titles.splitlines())
|
||||
|
||||
|
||||
def todos_since(tag: str | None | Failure, ref: str, cwd: str) -> list[str] | Failure:
|
||||
@@ -103,7 +119,7 @@ def todos_since(tag: str | None | Failure, ref: str, cwd: str) -> list[str] | Fa
|
||||
def chunk_item(found: list[Item], cut: LastCut) -> Pick:
|
||||
"""The pick from todo.md's items, weighed against the last cut. Routing and chunk-preflight both pick with it, so they name one item."""
|
||||
upcoming = next_release(found, cut)
|
||||
return standing(upcoming, next_item(found)) if isinstance(upcoming, Upcoming) else upcoming
|
||||
return standing(upcoming, next_item(found), cut.reviewed) if isinstance(upcoming, Upcoming) else upcoming
|
||||
|
||||
|
||||
def next_release(found: list[Item], cut: LastCut) -> Upcoming | Cut | Unknown:
|
||||
@@ -139,16 +155,20 @@ def landed(cut: LastCut) -> bool | Failure:
|
||||
return changes if isinstance(changes, Failure) else changes > 0
|
||||
|
||||
|
||||
def standing(upcoming: Upcoming, first: Item | None) -> Next | ReadyToCut | Unplanned | Unknown:
|
||||
def standing(upcoming: Upcoming, first: Item | None, reviewed: bool | Failure) -> Next | ReadyToCut | ReviewDue | Unplanned | Unknown:
|
||||
"""How the plan stands to upcoming, the next release. first is next_item's pick, which the pick holds where it is Next.
|
||||
|
||||
Unknown where the next release holds no item and the unreleased changes cannot be counted.
|
||||
Unknown where the next release holds no item and the unreleased changes cannot be counted, or work has landed and git cannot say whether a release review has.
|
||||
"""
|
||||
if upcoming.is_earliest:
|
||||
return Next(upcoming.release, first)
|
||||
if isinstance(upcoming.landed, Failure):
|
||||
return Unknown()
|
||||
return ReadyToCut(upcoming.release) if upcoming.landed else Unplanned(upcoming.release)
|
||||
if not upcoming.landed:
|
||||
return Unplanned(upcoming.release)
|
||||
if isinstance(reviewed, Failure):
|
||||
return Unknown()
|
||||
return ReadyToCut(upcoming.release) if reviewed else ReviewDue(upcoming.release)
|
||||
|
||||
|
||||
def unreleased_changes(cut: LastCut) -> int | Failure:
|
||||
|
||||
@@ -2,7 +2,7 @@
|
||||
import pathlib
|
||||
import re
|
||||
|
||||
from chunk_pick import chunk_item, Cut, LastCut, ReadyToCut, Unknown, Unplanned
|
||||
from chunk_pick import chunk_item, Cut, LastCut, ReadyToCut, ReviewDue, Unknown, Unplanned
|
||||
from failure import Failure
|
||||
from chunk_preflight.gathered import Forge, NoItem, Plan
|
||||
from todo_table import item_details, items, NoItemsTable, version
|
||||
@@ -26,10 +26,12 @@ def planned(todo: str | Failure, cut: LastCut, default: str) -> Plan | NoItem:
|
||||
return NoItem(f"{where} files items under release {version(pick.release)}, which is not after the last cut, {cut.tag}; ask the human which release they belong to.")
|
||||
if isinstance(pick, Unknown):
|
||||
return NoItem(f"{where} may hold no item for the next release after the last cut, {cut.tag}: todo.md's texts since then, or the count of changes since then, cannot be read. Find the next release yourself.")
|
||||
if isinstance(pick, ReadyToCut | Unplanned):
|
||||
if isinstance(pick, ReadyToCut | ReviewDue | Unplanned):
|
||||
upcoming = f"release {version(pick.release)}, the next after the last cut, {cut.tag}" if pick.release else f"the next release after the last cut, {cut.tag}"
|
||||
if isinstance(pick, ReviewDue):
|
||||
return NoItem(f"{where} holds no item for {upcoming}, and changes are unreleased, so that release's release review is due: no commit titled `Release review of <release>` has landed since the cut. This chunk is that review, as `~/.claude/skills/larv-review/SKILL.md` → \"Release review\" says; once it merges, the release is ready to cut.")
|
||||
if isinstance(pick, ReadyToCut):
|
||||
return NoItem(f"{where} holds no item for {upcoming}, and changes are unreleased, so that release is finished and ready to cut. The working loop stops here. If todo.md renamed that release instead, add `- <old release> renamed to <new release>` to todo.md's `## Renamed` section.")
|
||||
return NoItem(f"{where} holds no item for {upcoming}, and changes are unreleased, and its release review has landed, so that release is finished and ready to cut. The working loop stops here. If todo.md renamed that release instead, add `- <old release> renamed to <new release>` to todo.md's `## Renamed` section.")
|
||||
return NoItem(f"{where} holds no item for {upcoming}, and no change is unreleased, so that release is to be planned first.")
|
||||
first = pick.item
|
||||
if first is None:
|
||||
|
||||
@@ -16,8 +16,9 @@ holds it, the plan loop-claude routes on. It prints:
|
||||
x.y.z that todo.md has named at that tag or since, less a release its ## Renamed section marks
|
||||
renamed. Otherwise it is todo.md's earliest release.
|
||||
Where the next release holds no item, it says so, naming it where todo.md named it since the tag:
|
||||
finished and ready to cut where changes are unreleased (the ## Unreleased entries, or else the
|
||||
commits since the tag), and else to be planned first.
|
||||
its release review due where changes are unreleased (the ## Unreleased entries, or else the
|
||||
commits since the tag) and no commit titled `Release review of <release>` followed the tag,
|
||||
finished and ready to cut once one did, and else to be planned first.
|
||||
Where todo.md's earliest release is x.y.z or earlier, it says todo.md files items under a release
|
||||
already cut;
|
||||
- the item's worktree: a sibling of the checkout named <checkout>-item-<ID>, on the branch
|
||||
|
||||
@@ -155,11 +155,13 @@ class ChunkPreflightTool(unittest.TestCase):
|
||||
self.assertNotIn("`gone.py`:", done.stdout)
|
||||
|
||||
def test_names_no_item_and_makes_no_worktree_where_the_release_after_the_last_cut_has_emptied(self):
|
||||
for changelog, fact in ((CHANGELOG, "finished and ready to cut"), ("# Changelog\n\n## Unreleased\n\n## 0.1.0\n\n- Old.\n", "planned first")):
|
||||
for changelog, reviewed, fact in ((CHANGELOG, False, "release review is due"), (CHANGELOG, True, "finished and ready to cut"), ("# Changelog\n\n## Unreleased\n\n## 0.1.0\n\n- Old.\n", False, "planned first")):
|
||||
with self.subTest(fact=fact):
|
||||
repo = Repo(self, changelog=changelog)
|
||||
repo.write(repo.root, "todo.md", LATER)
|
||||
repo.commit(repo.root, "ship 0.2.0")
|
||||
if reviewed:
|
||||
repo.git(repo.root, "commit", "--quiet", "--allow-empty", "-m", "Release review of 0.2.0")
|
||||
repo.git(repo.root, "push", "--quiet", "origin", "main")
|
||||
done = repo.preflight()
|
||||
self.assertEqual(done.returncode, 0, done.stderr)
|
||||
@@ -168,7 +170,7 @@ class ChunkPreflightTool(unittest.TestCase):
|
||||
self.assertFalse((repo.temp / "proj-item-9").exists())
|
||||
|
||||
def test_takes_the_next_item_where_the_plan_marks_the_release_after_the_last_cut_renamed_and_calls_it_finished_where_it_does_not(self):
|
||||
for mark, fact, absent in (("\n## Renamed\n\n- 0.2.0 renamed to 0.3.0\n", "item 3", "finished"), ("", "finished and ready to cut", "item 3")):
|
||||
for mark, fact, absent in (("\n## Renamed\n\n- 0.2.0 renamed to 0.3.0\n", "item 3", "release review"), ("", "release review is due", "item 3")):
|
||||
with self.subTest(mark=mark):
|
||||
repo = Repo(self)
|
||||
repo.write(repo.root, "todo.md", TODO.replace("| 0.3.0 |", "| 0.4.0 |").replace("| 0.2.0 |", "| 0.3.0 |") + mark)
|
||||
@@ -183,7 +185,7 @@ class ChunkPreflightTool(unittest.TestCase):
|
||||
"""Each case's plans: before the tag, at it, on a side branch merged after it, and after it, each committed in turn where given."""
|
||||
cases = (
|
||||
("a release named only before the cut", TODO, LATER, None, None, "item 9"),
|
||||
("a release named at the cut", None, TODO, None, LATER, "finished and ready to cut"),
|
||||
("a release named at the cut", None, TODO, None, LATER, "release review is due"),
|
||||
("a release named only on a side branch", None, LATER, TODO, None, "item 9"),
|
||||
)
|
||||
for name, before, at, side, after, fact in cases:
|
||||
@@ -431,16 +433,17 @@ class Plans(unittest.TestCase):
|
||||
named = "release 0.2.0, the next after the last cut, v0.1.0"
|
||||
unnamed = "the next release after the last cut, v0.1.0"
|
||||
cases = (
|
||||
(LATER, 4, [TODO], "finished and ready to cut", named),
|
||||
(LATER, 0, [TODO], "planned first", named),
|
||||
(EMPTY, 4, [TODO], "finished and ready to cut", named),
|
||||
(EMPTY, 0, [TODO], "planned first", named),
|
||||
(EMPTY, 4, [EMPTY], "finished and ready to cut", unnamed),
|
||||
(LATER, Failure("count unreadable"), [TODO], "cannot be read", unnamed),
|
||||
(LATER, 4, [TODO], False, "release review is due", named),
|
||||
(LATER, 4, [TODO], True, "finished and ready to cut", named),
|
||||
(LATER, 0, [TODO], False, "planned first", named),
|
||||
(EMPTY, 4, [TODO], True, "finished and ready to cut", named),
|
||||
(EMPTY, 0, [TODO], False, "planned first", named),
|
||||
(EMPTY, 4, [EMPTY], True, "finished and ready to cut", unnamed),
|
||||
(LATER, Failure("count unreadable"), [TODO], False, "cannot be read", unnamed),
|
||||
)
|
||||
for todo, commits, todos, fact, release in cases:
|
||||
with self.subTest(todo=todo, commits=commits, todos=todos):
|
||||
why = planned(todo, LastCut("v0.1.0", "", commits, todos), "origin/main").why
|
||||
for todo, commits, todos, reviewed, fact, release in cases:
|
||||
with self.subTest(todo=todo, commits=commits, todos=todos, reviewed=reviewed):
|
||||
why = planned(todo, LastCut("v0.1.0", "", commits, todos, reviewed), "origin/main").why
|
||||
self.assertIn(fact, why)
|
||||
self.assertIn(release, why)
|
||||
|
||||
|
||||
@@ -25,7 +25,8 @@ the merge base of HEAD and the default branch.
|
||||
round-count prints each pass's round count among the branch's commits since the default branch
|
||||
whose titles open `Answer <pass> round <n>:`, ignoring case. It follows first parents, as
|
||||
rule-hook's round-cap does. The count is the highest <n>, or the number of such commits when that
|
||||
is more. At or past the cap of {cap} rounds, it says the pass takes no more rounds. It also lists
|
||||
is more. At or past the cap of {cap} rounds, {release_cap} for architecture and principles, which run
|
||||
only in the release review, it says the pass takes no more rounds. It also lists
|
||||
each name in such a title that is not a pass.
|
||||
|
||||
needs-scoring-run takes the IDs of the todo.md items the chunk ships, none when it ships none, and
|
||||
@@ -103,7 +104,7 @@ import sys
|
||||
import typing
|
||||
|
||||
from git_repo import branch_titles, default_branch, git, top
|
||||
from round_titles import CAP, round_counts
|
||||
from round_titles import cap, CAP, RELEASE_REVIEW_CAP, round_counts
|
||||
from failure import Failure
|
||||
from comprehension_history import FLOOR
|
||||
from larv_review.history_changes import history_changes
|
||||
@@ -119,7 +120,7 @@ USAGE = "usage: larv-review review-folder | ruling-base | round-count | needs-sc
|
||||
|
||||
def main(argv: list[str]) -> int:
|
||||
if argv in (["-h"], ["--help"]):
|
||||
print(__doc__.strip().format(cap=CAP, floor=FLOOR, pairs=MIN_PAIRS))
|
||||
print(__doc__.strip().format(cap=CAP, release_cap=RELEASE_REVIEW_CAP, floor=FLOOR, pairs=MIN_PAIRS))
|
||||
return 0
|
||||
command, *given = argv or [""]
|
||||
if command == "review-folder" and not given:
|
||||
@@ -199,14 +200,14 @@ def round_count(default: str) -> Failure | None:
|
||||
if isinstance(titles, Failure):
|
||||
return titles
|
||||
for name, count in round_counts(titles).items():
|
||||
print(f"{name}: {count}{cap_note(count) if name in PASSES else ', not a pass: check the commit title'}")
|
||||
print(f"{name}: {count}{cap_note(count, cap(name)) if name in PASSES else ', not a pass: check the commit title'}")
|
||||
return None
|
||||
|
||||
|
||||
def cap_note(count: int) -> str:
|
||||
if count < CAP:
|
||||
def cap_note(count: int, most: int) -> str:
|
||||
if count < most:
|
||||
return ""
|
||||
return f", {'at' if count == CAP else 'past'} the cap: no more rounds"
|
||||
return f", {'at' if count == most else 'past'} the cap: no more rounds"
|
||||
|
||||
|
||||
def needs_scoring_run(default: str, ids: list[int]) -> Failure | None:
|
||||
|
||||
+10
-2
@@ -6,6 +6,9 @@ from review_passes import PASSES
|
||||
|
||||
# The most rounds a pass takes per chunk, per `docs/decisions.md` → `review: a pass gets at most two rounds per chunk, …`. rule-hook's `round-cap` refuses a round commit that `past_cap` finds takes its pass past it, and `larv-review round-count` marks a pass that reached it.
|
||||
CAP = 2
|
||||
# The release review's passes take more, since they may refactor much: `skills/larv-review/SKILL.md` → "Release review".
|
||||
RELEASE_REVIEW_CAP = 5
|
||||
CAPS = {"architecture": RELEASE_REVIEW_CAP, "principles": RELEASE_REVIEW_CAP}
|
||||
ROUND = re.compile(r"^Answer (.+?) round ([0-9]+):", re.IGNORECASE)
|
||||
# What follows a round title's colon: the round's 🔴 and 🟡 counts, then how many of them a reviewer marked `[misread]`, a count that titles from before it lack, then `;` and its summary, if any.
|
||||
FINDINGS = re.compile(r" ([0-9]+) 🔴, ([0-9]+) 🟡(?: \(([0-9]+) misread\))?(?:;|$)")
|
||||
@@ -42,9 +45,14 @@ def lacks_counts(title: str) -> bool:
|
||||
|
||||
|
||||
def past_cap(title: str, earlier: list[str]) -> bool:
|
||||
"""Whether title is a round title that takes its pass past CAP, as round_counts counts title among the branch's earlier commit titles."""
|
||||
"""Whether title is a round title that takes its pass past its cap, as round_counts counts title among the branch's earlier commit titles."""
|
||||
named = ROUND.match(title)
|
||||
return named is not None and round_counts([*earlier, title])[named.group(1).lower()] > CAP
|
||||
return named is not None and round_counts([*earlier, title])[named.group(1).lower()] > cap(named.group(1).lower())
|
||||
|
||||
|
||||
def cap(name: str) -> int:
|
||||
"""The most rounds the pass named name takes per chunk."""
|
||||
return CAPS.get(name, CAP)
|
||||
|
||||
|
||||
def title_counts(title: str) -> Findings | None:
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
from rule_hook.rules import Breach
|
||||
from round_titles import CAP, past_cap, ROUND, round_counts
|
||||
from round_titles import cap, past_cap, ROUND, round_counts
|
||||
from git_command import Commit
|
||||
from failure import Failure
|
||||
import git_repo
|
||||
@@ -18,7 +18,7 @@ def refusal(name: str, title: str, earlier: list[str]) -> str:
|
||||
"""Why title, a round title of the pass name, is refused, listing the pass's round commits counted, and how to commit the fixes in hand."""
|
||||
counted = [earlier_title for earlier_title in earlier if (named := ROUND.match(earlier_title)) and named.group(1).lower() == name]
|
||||
listed = ", ".join(f"`{counted_title}`" for counted_title in counted) or "none found"
|
||||
return f"this would be {name}'s round {round_counts([*counted, title])[name]}, past its {CAP}; {name}'s round commits on this branch: {listed}. Fold the fixes into its last round commit with `git commit --amend` where that is the newest commit, or commit them under a title that doesn't open `Answer <pass> round`; they merge once the gate passes"
|
||||
return f"this would be {name}'s round {round_counts([*counted, title])[name]}, past its {cap(name)}; {name}'s round commits on this branch: {listed}. Fold the fixes into its last round commit with `git commit --amend` where that is the newest commit, or commit them under a title that doesn't open `Answer <pass> round`; they merge once the gate passes"
|
||||
|
||||
|
||||
def earlier_titles(directory: str, amends: bool) -> list[str]:
|
||||
|
||||
@@ -3,7 +3,7 @@ import posixpath
|
||||
import re
|
||||
import typing
|
||||
|
||||
from round_titles import CAP, lacks_counts
|
||||
from round_titles import CAP, lacks_counts, RELEASE_REVIEW_CAP
|
||||
from git_command import commits
|
||||
from rule_hook.heavy_command import heavy
|
||||
from shell_command import launched, Simple, tool_name
|
||||
@@ -60,13 +60,13 @@ RULES: dict[RuleName, Rule] = {
|
||||
),
|
||||
# A rung is not a judgment call, and the refusal names the arguments to pass, so no marker waives it.
|
||||
"reviewer-rung": Rule(
|
||||
"a reviewer, a comprehension seat or the security pass's subagent runs on the rung loop-claude names for it: for a seat or the security pass the project's rung, and for a reviewer the highest of the project's rung, the worker's and the one the chunk's item's E + I picks, so a worker below the project's rung cannot hand a review to its own cheaper model",
|
||||
"a reviewer, a comprehension seat or the security pass's subagent runs on the rung loop-claude names for it: for a seat or the security pass the project's rung, and for a reviewer the highest of the project's rung, the worker's and the one the chunk's item's E + I picks, or the project's rung where the branch changes only Markdown no agent follows, so a worker below the project's rung cannot hand a review to its own cheaper model",
|
||||
"an Agent call, in a claude loop-claude started, whose subagent type is an agent under agents/, or whose prompt opens with seat-prompts.md's opening sentence or the one larv-review's Security section sets",
|
||||
overridable=False,
|
||||
),
|
||||
# The cap holds with no ask, so no marker waives it.
|
||||
"round-cap": Rule(
|
||||
f"a larv-review pass takes at most {CAP} rounds per chunk, and none after them: the fixes answering its last round merge once the gate passes",
|
||||
f"a larv-review pass takes at most {CAP} rounds per chunk, and the release review's architecture and principles passes {RELEASE_REVIEW_CAP}, and none after them: the fixes answering its last round merge once the gate passes",
|
||||
"a git commit whose message opens `Answer <pass> round <n>:`, counted with the pass's round commits on the branch since the default branch as last fetched, less the one an --amend replaces",
|
||||
overridable=False,
|
||||
),
|
||||
|
||||
+28
-1
@@ -1,11 +1,14 @@
|
||||
import pathlib
|
||||
import subprocess
|
||||
import sys
|
||||
import tempfile
|
||||
import unittest
|
||||
|
||||
sys.path.insert(0, str(pathlib.Path(__file__).resolve().parent))
|
||||
|
||||
import chunk_pick
|
||||
from failure import Failure
|
||||
from test_env import isolated_env
|
||||
import todo_table
|
||||
|
||||
|
||||
@@ -80,7 +83,31 @@ class ChunkItem(unittest.TestCase):
|
||||
)
|
||||
for tag, changes, earliest, named, stands in cases:
|
||||
with self.subTest(tag=tag, changes=changes, earliest=earliest, named=named):
|
||||
self.assertEqual(chunk_pick.chunk_item(plan_under(earliest), chunk_pick.LastCut(tag, "", changes, naming(named))), stands)
|
||||
self.assertEqual(chunk_pick.chunk_item(plan_under(earliest), chunk_pick.LastCut(tag, "", changes, naming(named), reviewed=True)), stands)
|
||||
|
||||
def test_calls_a_release_review_due_where_the_next_release_holds_no_item_and_none_landed_since_the_cut(self):
|
||||
cut = lambda reviewed: chunk_pick.LastCut("v1.2.3", "", 4, naming({(1, 3, 0)}), reviewed)
|
||||
self.assertEqual(chunk_pick.chunk_item([], cut(False)), chunk_pick.ReviewDue((1, 3, 0)))
|
||||
self.assertEqual(chunk_pick.chunk_item([], cut(True)), chunk_pick.ReadyToCut((1, 3, 0)))
|
||||
self.assertEqual(chunk_pick.chunk_item([], cut(Failure("log unreadable"))), chunk_pick.Unknown())
|
||||
self.assertEqual(chunk_pick.chunk_item(plan_under((1, 3, 0)), cut(False)), chunk_pick.Next((1, 3, 0), one((1, 3, 0))), "a review matters only once the release's items run out")
|
||||
self.assertEqual(chunk_pick.chunk_item([], chunk_pick.LastCut("v1.2.3", "", 0, naming({(1, 3, 0)}))), chunk_pick.Unplanned((1, 3, 0)))
|
||||
|
||||
def test_finds_a_release_review_among_the_commits_since_the_cut(self):
|
||||
repo = tempfile.mkdtemp()
|
||||
self.addCleanup(subprocess.run, ["rm", "-rf", repo])
|
||||
run = lambda *args: subprocess.run(["git", "-c", "user.name=t", "-c", "user.email=t@t", *args], capture_output=True, check=True, cwd=repo, env=isolated_env(), text=True)
|
||||
run("init", "-q", "-b", "main")
|
||||
run("commit", "-q", "--allow-empty", "-m", "Release review of 0.1.0")
|
||||
run("tag", "v0.1.0")
|
||||
run("commit", "-q", "--allow-empty", "-m", "Ship item 4")
|
||||
self.assertIs(chunk_pick.release_reviewed("v0.1.0", "main", repo), False, "a review before the cut reviewed that release")
|
||||
run("commit", "-q", "--allow-empty", "-m", "Release review of 0.2.0")
|
||||
run("commit", "-q", "--allow-empty", "-m", "Answer architecture round 1: 0 🔴, 1 🟡 (0 misread); split loader")
|
||||
self.assertIs(chunk_pick.release_reviewed("v0.1.0", "main", repo), True)
|
||||
self.assertIs(chunk_pick.release_reviewed(None, "main", repo), True)
|
||||
self.assertIsInstance(chunk_pick.release_reviewed("v9.9.9", "main", repo), Failure)
|
||||
self.assertEqual(chunk_pick.default_plan(repo, "main").cut.reviewed, True)
|
||||
|
||||
def test_counts_the_changes_unreleased_since_the_last_cut_by_unreleased_entries_and_else_by_commits(self):
|
||||
changelog = "# Changelog\n\n## Unreleased\n\n- One.\n - A nested line.\n- Two.\n\n## 0.1.0\n\n- Old.\n"
|
||||
|
||||
@@ -31,6 +31,9 @@ class Cap(unittest.TestCase):
|
||||
self.assertTrue(past_cap("Answer stability round 3: 0 🔴, 1 🟡; fix", []))
|
||||
self.assertTrue(past_cap("answer full scan round 10: x", []))
|
||||
self.assertFalse(past_cap("Answer stability round 2: 0 🔴, 1 🟡; fix", []))
|
||||
self.assertFalse(past_cap("Answer architecture round 5: 0 🔴, 1 🟡 (0 misread); split", []), "the release review's passes take five")
|
||||
self.assertFalse(past_cap("Answer principles round 5: 0 🔴, 1 🟡 (0 misread); split", []))
|
||||
self.assertTrue(past_cap("Answer principles round 6: 0 🔴, 1 🟡 (0 misread); split", []))
|
||||
self.assertFalse(past_cap("Answer the 3 questions", []))
|
||||
|
||||
def test_counts_the_pass_s_earlier_round_commits(self):
|
||||
|
||||
+12
-4
@@ -92,7 +92,7 @@ The trials: four stability rounds and five principles rounds archived on 2026-10
|
||||
- Code-intelligence tooling: the `LSP` tool, through a pyright plugin built from the marketplace manifest with `pyright-langserver` on PATH, answers a file's symbols, a definition or the references in a few hundred characters. Under a rule telling them to use it, the stability reviewers and the workers never called it; the auditors did, read as much or more, and missed the one 🔴, 0 of 1 against the baseline's 1 of 1. Each machine would also need a server per language (goal 2). Not worth an item.
|
||||
- A cap on tool results. Claude Code caps a Bash result at about 30k characters already. A PostToolUse hook capping it at 12k, which `updatedToolOutput` allows, left the stability reviewers 3 of 6 findings, two lost in one round. Read results, 59.9M characters in subagents' threads with 58% of their characters in results over 12k, are out of such a hook's reach. Not worth an item.
|
||||
- A scout: Haiku 5.5 reading raw content, whole files or long output, and returning facts as path:line and the ranges worth reading, so the agent's own context holds the summary and the chosen lines. In session, as an agent under `agents/`, its first request writes 37k tokens, $0.005, and a read of a 38KB file costs $0.008 in 8 seconds. As a slim headless `claude -p` with its own system prompt, no setting sources and no dynamic sections, which keeps the subscription login, it starts at 6k tokens and $0.0003 in 3 to 5 seconds, its prefix cached across calls, and the same read costs $0.004 in 7 seconds; a direct API call and `claude --bare` need an API key, so they are out. Stability reviewers with the agent scout found 5 of 6 findings and read 29% fewer characters at 6% less cost and 14% more time; with the CLI scout 4 of 6, 38% fewer, 17% less and 39% more; the auditors with the agent scout 3 of 6, the 🔴 among the lost, at the same cost and twice the time. Workers offered the scout never called it.
|
||||
- What a reviewer reads: the auditors read the project whole by design. Of their 🔴 and 🟡 findings since the reset, 47% named a file the chunk edited and 51% another file, so reading only the change would drop half of them (`review: the principles audit runs on every chunk that changes code, config or tests, reads the project whole with one auditor checking the goals and every principles file that applies, and runs on no other chunk`).
|
||||
- What a reviewer reads: the auditors read the project whole by design. Of their 🔴 and 🟡 findings since the reset, 47% named a file the chunk edited and 51% another file, so reading only the change would drop half of them (`review: the principles audit runs only in the release review, and reads the project whole with one auditor checking the goals and every principles file that applies`).
|
||||
- The base context: every thread starts with `~/.claude/CLAUDE.md` (19k characters), `~/.claude/AGENTS.md` (11k, this repo's decisions, which Claude Code loads as user instructions into every project's sessions; `todo.md` item 52), the project's `AGENTS.md`, and, for the worker and general-purpose subagents, the skill listing (18k) and the agent listing (12k). Subagents' first messages wrote $97 of it. Trimming the listings would save about $20, 2%, and is not worth an item: `disableBundledSkills` would also drop `/security-review`, the security pass of record.
|
||||
|
||||
Quality. 19 chunks compacted between 2026-10-10 and 2026-10-22, at the compaction points Claude Code set then, 214k to 972k tokens. Per 100 worker messages they took a median 3.6 review rounds past each pass's first against 4.0 for the 68 uncompacted chunks of 100 messages or more, and 13.9 🔴 and 🟡 findings against 16.6. 4 of 19 had an unfinished verdict against 3 of 68, each 8 to 10 hours after the compaction and followed by a finished verdict within minutes; in those four verdicts the judge quoted the worker's own passages and the human's typed answers, never a summary. One cause was possible and is closed here: Claude Code writes the summary as a user entry, which `bin/claude_code/entries.py` read as the human's words, so the judge would see a `[human]` line of thousands of words and `/talk` would count it as typed; it now reads as Claude Code's. Whether compaction raises unfinished verdicts stays open until `todo.md` item 235 measures it. Two summaries read whole kept the chunk's intent, files, errors and next step in 12k to 20k characters, and the worker resumed without re-reading.
|
||||
@@ -173,7 +173,7 @@ Valid while no published standard sets either number, the reading-cost window st
|
||||
|
||||
2026-10-29, lilleman. Serves goals 1.4 and 1.5. One project's chunk on 2026-10-29 changed a README paragraph, `todo.md` and three lines of `gate.yml`, and the principles, security and stability passes all ran on it, each twice: 6 of the chunk's 10 rounds. A change to config is one that changes what runs, so a comment in it fires only the prose pass, as a comment in code already did. A branch that changes only Markdown no agent follows changes no code, config or tests, so no pass that reads those runs on it. A plan row a chunk files from a finding, re-scores or moves is read by the chunk that ships it, so reviewing it at filing reviewed it twice: that chunk spent a prose round of 4 minutes on its plan change. Markdown an agent follows, such as a skill, is config, since a change there changes what agents do. Valid while defects in prose-only chunks stay rare in later chunks' fixes.
|
||||
|
||||
## review: a pass gets at most two rounds per chunk, with no third and no ask for one; the fixes answering round 2 merge once the gate passes
|
||||
## review: a pass gets at most two rounds per chunk, and the release review's architecture and principles passes five, with no more and no ask for more; the fixes answering a pass's last round merge once the gate passes
|
||||
|
||||
2026-10-28, lilleman through todo item 246. Serves goals 1 and 1.4. One counter per pass per chunk, so no fix bounces between two passes without end. lilleman measured every repo's round titles since 2026-10-21. Round 1 ran 357 times and found 59 🔴. Round 2 ran about 200 times and found 12 🔴, mostly in round 1's fixes. Rounds 3 and later ran about 110 times and found no 🔴, at about $125 of review at list prices, and asks for a fourth or fifth round were 24 of the 59 interrupts. The cap had stood at three because a lower cap would ask the human more often; once nothing asks, that reason is gone. A rerun one rung up belongs to the round it reruns, so it doesn't count toward the cap: `review: a reviewer or comprehension seat that rules the work below standard`.
|
||||
|
||||
@@ -181,6 +181,8 @@ rule-hook's `round-cap` refuses a round commit that would take its pass past rou
|
||||
|
||||
Valid while the later fixes per finished chunk, which `score-outcomes` and the routing figures count, don't rise.
|
||||
|
||||
2026-10-29, lilleman: the release review's architecture and principles passes take five rounds, since they may refactor much of a project; the stability, security, overrides and prose passes on their fixes keep two.
|
||||
|
||||
## review: a pass skips only on a precedent: a decision, or a plan item crediting the pass, that the repo held before the chunk began
|
||||
|
||||
2026-09-30, lilleman. Serves goal 1: a decision the chunk writes is the chunk's own and unreviewed, and an unattended run has no human to catch it. Valid while a pass is the only reader of a chunk before merge.
|
||||
@@ -233,7 +235,7 @@ Valid while Claude Code passes `agent_type` to hooks inside a subagent. Without
|
||||
|
||||
2026-10-28, lilleman: prose findings stay, since Claude's prose needs them, though prose's 105 first rounds since 2026-10-21 raised 498 🟡 and only 3 🔴.
|
||||
|
||||
## review: the comprehension check records how hard a project is to read and blocks no merge: a paired ruling against the last measured commit where the architecture pass ran, and the four-seat scoring run, once when an item names the floor and twice on one head when a release's items run out
|
||||
## review: the comprehension check records how hard a project is to read and blocks no merge: a paired ruling against the last measured commit in the release review, and the four-seat scoring run, once when an item names the floor and twice on one head when a release's items run out
|
||||
|
||||
2026-10-08, lilleman. Serves goals 1.1 and 1.4. Two independent four-seat runs moved up to 0.4 on near-identical code, so a fall within that noise forced rounds that changed nothing (PR #224). A seat reading both versions judges the difference on the same material, so the noise the versions share cancels. No conventional significance level lets a sign test settle with four votes, so the human chose a lead of two votes over every other ruling, same included. Two seats that agree settle it, so a PR that leaves the reading as it was costs two seats. A third seat alone can never settle it, so the third and fourth launch together. The scoring run also runs on a chunk shipping an item that names the floor, so the chunk that lifts a project to the floor can prove it. A chunk that removes a release's last item without shipping it runs the scoring run too, so no release ends unmeasured, unless `todo.md` marks that release renamed in a `## Renamed` section (`bin/todo_table.py` → `renames`). Valid while seats reading both versions agree more often than two absolute runs do.
|
||||
|
||||
@@ -247,7 +249,11 @@ The base is the last measured commit: the default branch's newest merged change
|
||||
|
||||
2026-09-20, lilleman. Serves goal 1.1. A reviewer's finding on that chunk could only be declined by citing the goals the chunk exists to write. Valid while every decline must name a goal or a technical principle.
|
||||
|
||||
## review: the principles audit runs on every chunk that changes code, config or tests, reads the project whole with one auditor checking the goals and every principles file that applies, and runs on no other chunk
|
||||
## review: the architecture and principles passes run only in the release review, a release's last chunk, which must land before the release is ready to cut; between releases the product-owner pass reviews changes to what consumers rely on
|
||||
|
||||
2026-10-29, lilleman. Serves goals 1.4 and 1.5, and code health. The principles audit read the whole project on every chunk that changed code, because small changes had let a project drift; it was the costliest reviewer after the worker, and it filed findings unrelated to the chunk. A per-chunk architecture trigger needs judgment about what a change carries, which a worker knows only after the work, and a planner or worker asking for the review would pile up agents. So both passes run once, over the whole project, in the release review: the chunk that runs once a release holds no item and changes are unreleased. They may refactor boldly, five rounds each, and their fixes take the stability, security, overrides and prose passes, two rounds each. The human sets how much drift a review must catch through how big a release is. Between releases, the product-owner pass reviews changes to what consumers rely on, such as routes, file formats and CLI flags, which the architecture trigger used to cover. `chunk-preflight` reports a release review due until a commit titled `Release review of <release>` follows the newest `v*` tag, and only then the release ready to cut. A project that deploys every merge, as this repo does, carries drift into production until its release review; lilleman means to move such projects onto releases. Valid while drift a release's chunks leave stays small enough for one review to fix.
|
||||
|
||||
## review: the principles audit runs only in the release review, and reads the project whole with one auditor checking the goals and every principles file that applies
|
||||
|
||||
2026-10-16, lilleman, answering the question on the audit's trigger that the plan held. Serves goal 1.1: a principle that no chunk checks drifts, as the stability reviewer's own copy of the principles drifted from them, until it applied `principles/technical-principles.md` as written. It costs goal 1.4: a chunk that changes code, config or tests launches an auditor, and a code fix re-enters it. The human accepted that cost. The cost shows in tokens per finished chunk and in review rounds per chunk. Valid while the audit's findings are drift a chunk would otherwise merge, not the same whole-project findings repeated chunk after chunk: a repeat is a question on the audit's scope for the human.
|
||||
|
||||
@@ -257,6 +263,8 @@ The base is the last measured commit: the default branch's newest merged change
|
||||
|
||||
A trial checked that it keeps goal 1.1. It replayed the 6 latest first rounds that launched two or more auditors, at most two per project, from this repo, `log`, `visthus` and `adf-codec`: 15 auditors, whose reports held 40 🔴 and 🟡 findings. Each round ran on the project's rung as `review-replay` replays it, once with its separate auditors and once with one auditor handed everything they checked, its new definition passed through `--agents`. A replayed reviewer finds a different part of its findings each time: the separate auditors found only 10 of their own 40 again. The one auditor found 12, among them 8 of those 10. So it finds as much as the separate auditors do. It missed two 🟡s on a missing or weak test, and found 4 findings they missed. No principles file keeps an auditor of its own. Asked whether those two misses should bring back separate auditors for the technical principles and for the goals with code health, lilleman chose to try the one auditor. Valid until the auditor's definition changes or a new model joins the ladder: replay the pass then, as this trial did.
|
||||
|
||||
2026-10-29, lilleman: it runs only in the release review. `review: the architecture and principles passes run only in the release review…` says why.
|
||||
|
||||
## review: the stability pass mutation-tests the lines a chunk changes, in place of measuring test coverage
|
||||
|
||||
2026-10-13, lilleman through todo item 108, implemented by claude. Serves goals 1.1 and 1.4. Coverage counts the lines a test runs, so a test without a meaningful assertion still raises it. A surviving mutant shows a test that would let behaviour break. Every mutant of an untested changed line survives, so mutation testing of the changed lines also shows what a coverage drop on them would. Coverage would also catch a deleted test; the stability reviewer sees one in the diff without it. Measuring coverage beside it would add cost without raising quality, so todo item 69 was dropped and `principles/technical-principles.md` replaced "Test coverage should not decline" with the mutant rule.
|
||||
|
||||
+20
-10
@@ -34,13 +34,13 @@ A pass is one kind of review, a row of the table, named by its first column. Its
|
||||
|
||||
| Pass | Reviewer | Trigger |
|
||||
|------|----------|----------------------------------------|
|
||||
| Architecture | systems-architect | 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 |
|
||||
| Principles | principles-auditor | changes code, config or tests |
|
||||
| Architecture | systems-architect | the release review, and no other chunk |
|
||||
| Principles | principles-auditor | the release review, and no other chunk |
|
||||
| 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 |
|
||||
| Security | `/security-review` | changes code or config, unless the full scan runs on the same change |
|
||||
| Overrides | override-reviewer | `~/.claude/bin/rule-hook overrides`, run in the chunk's worktree, prints a line no round of this pass has ruled on |
|
||||
| Stability | stability-reviewer | changes code, config or tests |
|
||||
| Product-owner | product-owner-reviewer | changes an external surface: API, CLI, UI, error or deprecation text a consumer reads, README and docs an outside reader lands on |
|
||||
| Product-owner | product-owner-reviewer | changes an external surface or contract: API routes and request/response shapes, events, webhooks, published file formats, CLI flags and exit codes, UI, error or deprecation text a consumer reads, README and docs an outside reader lands on |
|
||||
| Prose | prose-reviewer | changes prose a reader reads, such as docs, comments, help or error text, or the plan's text for an item the chunk ships, splits or answers; one round |
|
||||
|
||||
A comment is prose, not code, in any file. A change to config is one that changes what runs, so a comment in a workflow or compose file fires only the prose pass. Markdown an agent follows is config: `CLAUDE.md`, `AGENTS.md`, and files under `agents/`, `principles/`, `rules/` or `skills/`.
|
||||
@@ -61,7 +61,7 @@ Give a reviewer without Bash the branch diff and `git ls-files`'s output in its
|
||||
|
||||
**Reports.** Run `~/.claude/bin/larv-review review-folder` in the chunk's worktree: it makes the chunk's review folder and prints its path. In each prompt to an agent under `~/.claude/agents/`, name the file in that folder for its full report: `<pass>-round-<n>.md`. For a relaunch one rung up, add `-rerun` before `.md`. 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 architecture pass and the full scan:
|
||||
**Precedent, then ask** — for the full scan:
|
||||
|
||||
- **Skip.** A precedent is a `docs/decisions.md` entry, or a plan item crediting the pass, that the repo held before the chunk began. Where one holds the decision this change executes, skip the pass and cite that entry or item.
|
||||
- **Departure.** A change that departs from the precedent is unreviewed, however thorough the precedent is.
|
||||
@@ -79,15 +79,15 @@ Give a reviewer without Bash the branch diff and `git ls-files`'s output in its
|
||||
- **Auto-reviewer.** The external auto-reviewer (§4) is a pass of its own, each review it posts, up to the cap, a round. Its count is the number of its reviews on the PR, less its reviews of a `Record the comprehension check:` commit, and `round-count` doesn't list it. A commit that answers one of its rounds takes an ordinary title, not an `Answer <pass> round` one, and a round that changed nothing gets no commit.
|
||||
- **Count.** Close each round of a pass other than the auto-reviewer with one commit that holds the round's fixes. Title it `Answer <pass> round <n>: <k> 🔴, <m> 🟡 (<j> misread); …`: `<pass>` is the pass's name in lower case, such as `full scan`, `<k>` and `<m>` are the 🔴 and 🟡 findings all the round's reviewers reported, and `<j>` is how many of those they marked `[misread]` (review-findings.md → "Misread"); a reviewer that marks none, such as `/security-review`, adds 0. Example: `Answer stability round 1: 1 🔴, 2 🟡 (1 misread); flag a deleted test`. 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. `~/.claude/bin/larv-review round-count` prints each pass's count and marks a pass at the cap.
|
||||
- **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", or settled in the PR summary per "Comprehension check" → "Places", or, for the prose pass and a pass at its cap, fixed. Resolve that round's 🟢s and ❓s per "Findings" too.
|
||||
- **Cap.** A pass takes at most two rounds per chunk; don't ask the user for a third. Answer its second round's findings per "Findings": those fixes merge once the gate passes, unreviewed by that pass. rule-hook's `round-cap` refuses a round commit that would take a pass past two, and no override waives it. A review the auto-reviewer posts after its second isn't a round: fix none of it and rerun no pass for it, but file a security finding it raises per `~/.claude/CLAUDE.md` → "Working loop", and any other 🔴 in `todo.md`.
|
||||
- **Cap.** A pass takes at most two rounds per chunk, and the release review's architecture and principles passes five; don't ask the user for more. Answer its last round's findings per "Findings": those fixes merge once the gate passes, unreviewed by that pass. rule-hook's `round-cap` refuses a round commit that would take a pass past its cap, and no override waives it. A review the auto-reviewer posts after its second isn't a round: fix none of it and rerun no pass for it, but file a security finding it raises per `~/.claude/CLAUDE.md` → "Working loop", and any other 🔴 in `todo.md`.
|
||||
|
||||
**Re-entry.** A fix is a change no pass has seen. A fix for a 🟡, a 🟢, a ❓ or a prose finding reruns no pass, whatever it changes. A round's fixes for 🔴 findings re-enter together: run every pass that a row below names for any of them, a done pass included, in the waves of "Waves", then §4. A pass at its cap doesn't run again ("Round cap" → "Cap").
|
||||
|
||||
| The fix | Reruns |
|
||||
|---------|--------|
|
||||
| answers a 🔴 of a pass other than prose | that pass |
|
||||
| carries an architectural decision | Architecture |
|
||||
| changes code, config or tests | Principles |
|
||||
| carries an architectural decision, in the release review | Architecture |
|
||||
| changes code, config or tests, in the release review | Principles |
|
||||
| opens an untrusted-input boundary or touches authn/authz, secrets or crypto | Security, unless the full scan reruns on it |
|
||||
| made rule-hook log an override | Overrides |
|
||||
| changes behaviour: what the code or its tests do | Stability |
|
||||
@@ -112,9 +112,19 @@ A fix meets every row it fits. Prose has no row, so a comment or doc edit inside
|
||||
- **🔀.** A 🔀 runs the named reviewer's pass once the current pass is done.
|
||||
- **Other scales.** Other reviewers map onto this scale: `/security-review`'s HIGH is 🔴, MEDIUM 🟡, LOW 🟢; what a forge's auto-reviewer marks blocking is 🔴. A finding of theirs repeating one declined or filed does not stand.
|
||||
|
||||
### Release review
|
||||
|
||||
The release review is a release's last chunk, run once the release holds no item and changes are unreleased, before it is ready to cut. It looks for the drift the release's small changes left, and fixes it.
|
||||
|
||||
- **When.** `chunk-preflight` reports a release review due. It counts one as landed once a commit titled `Release review of <release>` follows the newest `v*` tag on the default branch.
|
||||
- **Branch.** `release-review-<release>`, off the default branch. Open it with `git commit --allow-empty -m "Release review of <release>"`.
|
||||
- **Passes.** Architecture, then Principles, each over the whole project, per "Waves". Tell both to refactor boldly where the code needs it. Each takes up to five rounds.
|
||||
- **Their fixes** re-enter Stability, Security, Overrides and Prose per "Re-entry", each at most two rounds.
|
||||
- **Comprehension check.** It runs its paired ruling here, per "Comprehension check".
|
||||
|
||||
### Architecture
|
||||
|
||||
Launch systems-architect: review the system as a whole entered through this change; the decision log carries previously accepted decisions to honor, the README the goals and Stage 0 artifacts. Give it the places per "Comprehension check" → "Places". Each of its other findings names a concrete later change the PR makes harder, such as "a second forge needs edits in four modules"; drop one that names none.
|
||||
Launch systems-architect: review the whole project as the release leaves it; the decision log carries previously accepted decisions to honor, the README the goals and Stage 0 artifacts. Give it the places per "Comprehension check" → "Places". Each of its other findings names a concrete later change the PR makes harder, such as "a second forge needs edits in four modules"; drop one that names none.
|
||||
|
||||
- **Stage 0 questions returned**: relay them to the user, record the answers in the README, re-run once.
|
||||
- **BLOCK** standing after any relaunch ("Rung up"): confirm with the user first when the restructure materially reshapes their PR; until confirmed, no later pass runs.
|
||||
@@ -125,7 +135,7 @@ Launch one principles-auditor on the trigger in §3, so the project is read once
|
||||
|
||||
### Comprehension check
|
||||
|
||||
The comprehension check records how hard the project is for its contributor to read (`~/.claude/rules/goals-and-audience.md`), and blocks no merge. Simulated readers, the seats, launched per `~/.claude/skills/comprehension-panel/SKILL.md`, each read the whole project, not the diff. It reports no findings and is no pass: it runs once, in §5, after every pass is done, the auto-reviewer included, so it reads the branch as review left it. It runs a paired ruling when the architecture pass's trigger fired, whether or not a precedent, the user's no or an opt-out skipped its architect, and a scoring run where one is due. It skips only as "Opt-out" or "Suspended" below says.
|
||||
The comprehension check records how hard the project is for its contributor to read (`~/.claude/rules/goals-and-audience.md`), and blocks no merge. Simulated readers, the seats, launched per `~/.claude/skills/comprehension-panel/SKILL.md`, each read the whole project, not the diff. It reports no findings and is no pass: it runs once, in §5, after every pass is done, the auto-reviewer included, so it reads the branch as review left it. It runs a paired ruling in the release review, even where an opt-out skips its architect, and a scoring run where one is due. It skips only as "Opt-out" or "Suspended" below says.
|
||||
|
||||
**Paired ruling.** Each seat votes whether the project reads better, the same or worse at this branch's head than at the base.
|
||||
|
||||
@@ -165,7 +175,7 @@ Launch the reviewer with the change — stability-reviewer also with the places
|
||||
|
||||
### Prose
|
||||
|
||||
Launch prose-reviewer with what the diff touched and every section this review cited — a reviewer's finding, your decline or the implementer's decision quoted it — each with the code it governs, and say whether the architecture pass's trigger fired. Fix what the chunk touched. A finding on a cited section the chunk did not touch, or on any other prose file, is outside the chunk. A split or index bigger than the chunk is filed as a `todo.md` item naming the section and how long a reader searches it.
|
||||
Launch prose-reviewer with what the diff touched and every section this review cited — a reviewer's finding, your decline or the implementer's decision quoted it — each with the code it governs, and say whether the chunk is a release review. Fix what the chunk touched. A finding on a cited section the chunk did not touch, or on any other prose file, is outside the chunk. A split or index bigger than the chunk is filed as a `todo.md` item naming the section and how long a reader searches it.
|
||||
|
||||
## 4. Gate
|
||||
|
||||
|
||||
Reference in New Issue
Block a user