Hand a reviewer without a shell the plan as a listing larv-review writes into the review folder
This commit is contained in:
@@ -7,9 +7,9 @@ omitClaudeMd: true
|
||||
|
||||
You check every yardstick you are handed against the whole project, which you read once for all of them. A yardstick is either the project's goals, every goal under `## Goals` in the file your prompt's `Goals and audience:` line names, with code health (`~/.claude/CLAUDE.md` → "Shared goal") unless that file voids it, or one principles file, every principle in it.
|
||||
|
||||
Verdict, severities and rounds: ~/.claude/skills/larv-review/review-findings.md. Read the yardsticks, `README.md`, `docs/decisions.md` and `todo.md` first, then all of the project's code, config, tests and CI.
|
||||
Verdict, severities and rounds: ~/.claude/skills/larv-review/review-findings.md. Read the yardsticks, `README.md`, `docs/decisions.md` and the plan, the file your prompt's `Plan:` line names, first, then all of the project's code, config, tests and CI.
|
||||
|
||||
- Per principle or goal: every place the project departs from it, with file:line, the defect in one sentence and its concrete consequence. Then one line: followed, mostly, not followed, or does not apply and why.
|
||||
- A departure a `todo.md` item plans away is named with that item, not raised.
|
||||
- A decision in `docs/decisions.md` working against a goal or a technical principle is a 🔴 on the decision, unless it names the `todo.md` item that ends it. Weigh it hard: that it was decided is no reason.
|
||||
- A departure a plan item plans away is named with that item, not raised.
|
||||
- A decision in `docs/decisions.md` working against a goal or a technical principle is a 🔴 on the decision, unless it names the plan item that ends it. Weigh it hard: that it was decided is no reason.
|
||||
- Report under one heading per yardstick.
|
||||
|
||||
@@ -47,7 +47,7 @@ Before anything else, **read the technical principles** in the folder your promp
|
||||
|
||||
## Your Output Format
|
||||
|
||||
Report only a defect a persona hits; a requirement that the change breaks, of the plan, of the goals in the file your prompt's `Goals and audience:` line names, or of code health (`~/.claude/CLAUDE.md` → "Shared goal", unless that file voids it); or a breach of a technical principle. Friction that is none of these is not a finding.
|
||||
Report only a defect a persona hits; a requirement that the change breaks, of the plan in the file your prompt's `Plan:` line names, of the goals in the file your prompt's `Goals and audience:` line names, or of code health (`~/.claude/CLAUDE.md` → "Shared goal", unless that file voids it); or a breach of a technical principle. Friction that is none of these is not a finding.
|
||||
|
||||
Verdict, severities and rounds: ~/.claude/skills/larv-review/review-findings.md. After the verdict:
|
||||
|
||||
|
||||
@@ -130,7 +130,7 @@ Every PR gets at least this sweep.
|
||||
|
||||
## Output Format
|
||||
|
||||
Report only a defect; a requirement that the change breaks, of the plan, of the goals in the file your prompt's `Goals and audience:` line names, or of code health (`~/.claude/CLAUDE.md` → "Shared goal", unless that file voids it); a breach of a technical principle; and the places the prompt hands you. A finding that is none of these is noise, however true: leave it out.
|
||||
Report only a defect; a requirement that the change breaks, of the plan in the file your prompt's `Plan:` line names, of the goals in the file your prompt's `Goals and audience:` line names, or of code health (`~/.claude/CLAUDE.md` → "Shared goal", unless that file voids it); a breach of a technical principle; and the places the prompt hands you. A finding that is none of these is noise, however true: leave it out.
|
||||
|
||||
Verdict, severities and rounds: ~/.claude/skills/larv-review/review-findings.md. After the verdict, a short **Coverage & Verification** block: what you ran (tests, static analysis, mutation — and their results), what you could not verify and why, and any files that got a lighter pass — never let silence imply coverage. Then the findings, most severe first, each with:
|
||||
- **Location**: File and line/function
|
||||
|
||||
@@ -184,7 +184,7 @@ This is where unjustified duplication and accidental complexity get caught. Run
|
||||
6. **Price the reasoned complexity too.** Essential-looking complexity has a requirement behind it. For each hotspot that survives the steps above, name that requirement, then sketch the design without it. When a much simpler near-equivalent exists, report the trade as a finding: the simpler shape, the exact functionality delta, and the complexity saved. A requirement nobody has priced is not a decision — offer the trade once, plainly, and let the owner accept or reject it.
|
||||
7. **Hunt the imagined requirement.** The step above prices complexity a real requirement forces; this one removes complexity no requirement forces. For every abstraction, indirection, configuration point, and layer of generality, name the present, Stage 0-recorded requirement it serves. An interface with one implementation, a plugin system with one plugin, a cache or shard — or a load-testing rig — for load nobody recorded, a canary rig for a blast radius nobody recorded, "in case we swap the database" — speculative generality is the over-engineered twin of copy-paste drift: complexity nobody's requirement chose. The future that justifies flexibility must be a recorded goal or horizon, not the author's imagination — and the shorter the horizon, the harder this step cuts. Rate removals with the same severity as unreasoned duplication.
|
||||
|
||||
Respect documented deliberate deviations — a stated trade-off is a valid reason (`docs/decisions.md`), unless it works against a goal or a technical principle and names no `todo.md` item ending it. Respecting it means not re-arguing the same trade with the same facts; it does not forbid offering a materially simpler alternative the decision never considered — offer it once with the exact delta, then drop it if declined. The target is the *un*reasoned: duplication, complexity, and confusion that nobody decided and nobody can defend. "Acceptable for now", "will compound later", and "converge in a future pass" are how a small drift becomes the permanent shape of the system.
|
||||
Respect documented deliberate deviations — a stated trade-off is a valid reason (`docs/decisions.md`), unless it works against a goal or a technical principle and names no plan item ending it. Respecting it means not re-arguing the same trade with the same facts; it does not forbid offering a materially simpler alternative the decision never considered — offer it once with the exact delta, then drop it if declined. The target is the *un*reasoned: duplication, complexity, and confusion that nobody decided and nobody can defend. "Acceptable for now", "will compound later", and "converge in a future pass" are how a small drift becomes the permanent shape of the system.
|
||||
|
||||
## Communication Style
|
||||
|
||||
|
||||
@@ -130,12 +130,14 @@ reviewer-header takes the name of a pass that an agent under agents/ reviews, sp
|
||||
prints it, such as stability. It prints the header of the prompt that launches the pass's reviewer
|
||||
in its next round: the pass and round, the branch's open pull request at its pushed head, the
|
||||
worktree and branch, the merge base of HEAD and the default branch, and the paths of the reviewer's
|
||||
report, the branch diff, the folder of technical principles the project's config sets and, for
|
||||
architecture and stability, the places. For a reviewer whose
|
||||
report, the branch diff, the folder of technical principles the project's config sets, the goals
|
||||
and the plan and, for architecture and stability, the places. For a reviewer whose
|
||||
definition under ~/.claude/agents/ has `omitClaudeMd: true`, it then names the file that holds the
|
||||
project principles and decision titles, where the project keeps one. It writes the diff, from
|
||||
that base to HEAD, into the chunk's review folder as branch-<short HEAD>.diff, and writes what
|
||||
places prints into places.md; a file whose text is unchanged is left as it is. With --rerun, the
|
||||
that base to HEAD, into the chunk's review folder as branch-<short HEAD>.diff, writes what
|
||||
places prints into places.md, and lists the plan's items, read through the plan's store, into
|
||||
plan.md, so a reviewer without a shell reads the plan from a file, whatever store holds it; a file
|
||||
whose text is unchanged is left as it is. With --rerun, the
|
||||
header names the report of a relaunch one rung up, in the same round, and the report that asked for
|
||||
it. It exits 1 when the pass takes no more rounds, when `project-config` fails in the checkout, when the
|
||||
principles folder it names is not a folder with a file in it, or, with --rerun, when the report that
|
||||
|
||||
@@ -0,0 +1,22 @@
|
||||
"""The plan as a listing a reviewer reads with the Read tool, whatever store holds the plan."""
|
||||
from failure import Failure
|
||||
from plan_store.stores import PlanStore
|
||||
from release_plan.release import version
|
||||
from release_plan.todo_table import Item
|
||||
|
||||
|
||||
def plan_listing(plan: PlanStore) -> str:
|
||||
"""The plan's items as the store supplies them, each with its release, tagline, blockers and detail. Where the plan can't be read, says so, so a reviewer doesn't take it for empty."""
|
||||
read = plan.read()
|
||||
opening = f"# Plan, as {plan.label} holds it\n\n"
|
||||
if isinstance(read, Failure):
|
||||
return f"{opening}The plan cannot be read, so no item is listed: {read.reason}\n"
|
||||
if not read.items:
|
||||
return f"{opening}The plan holds no item.\n"
|
||||
return opening + "\n".join(item_listing(item) for item in read.items)
|
||||
|
||||
|
||||
def item_listing(item: Item) -> str:
|
||||
blockers = ", ".join(map(str, item.blocked_by))
|
||||
parts = [f"## Item {item.id}, release {version(item.release)}", item.tagline, *([f"Blocked by: {blockers}."] if blockers else []), *([item.detail.strip()] if item.detail.strip() else [])]
|
||||
return "\n\n".join(parts) + "\n"
|
||||
@@ -1,4 +1,4 @@
|
||||
"""reviewer-header: write the branch diff and the places into the chunk's review folder, and print the header of a reviewer's prompt."""
|
||||
"""reviewer-header: write the branch diff, the places and the plan into the chunk's review folder, and print the header of a reviewer's prompt."""
|
||||
import dataclasses
|
||||
import pathlib
|
||||
|
||||
@@ -11,6 +11,8 @@ from larv_review.history_commands import history_file, places_report
|
||||
from project_config.main import located, title_templates
|
||||
from review_rules.review_folder import made_review_folder
|
||||
from deploy_release.forge import open_pull, runner
|
||||
from larv_review.plan_listing import plan_listing
|
||||
from plan_store.stores import store as plan_store
|
||||
from review_rules.reviewer_context import principles_line, starts_bare
|
||||
from review_rules.review_passes import REVIEWERS
|
||||
|
||||
@@ -33,6 +35,8 @@ class Launch:
|
||||
diff: pathlib.Path
|
||||
principles: pathlib.Path
|
||||
goals: pathlib.Path
|
||||
# The plan as `plan_listing` writes it, for a reviewer that reads files, whatever store holds the plan.
|
||||
plan: pathlib.Path
|
||||
bare: bool
|
||||
# The project's `AGENTS.md`, where its config puts it, and a local file of its decision log.
|
||||
rules: pathlib.Path
|
||||
@@ -56,6 +60,7 @@ class Launch:
|
||||
f"Diff: {self.diff}",
|
||||
f"Technical principles: {self.principles}",
|
||||
f"Goals and audience: {self.goals}",
|
||||
f"Plan: {self.plan}",
|
||||
f"Prose language: {self.language}.",
|
||||
*([f"Places: {self.folder / 'places.md'}"] if self.pass_ in TAKE_PLACES else []),
|
||||
*([principles] if self.bare and (principles := principles_line(self.rules, self.decisions)) else []),
|
||||
@@ -103,17 +108,17 @@ def reviewer_header(default: str, pass_: str, rerun: bool, home: pathlib.Path) -
|
||||
goals = local_file(goals_store(config), folder / "goals.md")
|
||||
if isinstance(goals, Failure):
|
||||
return goals
|
||||
launch = Launch(pass_, round_, rerun, pull_named(worktree, branch), worktree, branch, base, default, folder, folder / f"branch-{head}.diff", principles, goals, starts_bare(next((agent for name, agent in REVIEWERS.items() if name == pass_), ""), home), config.paths["working-rules"], decisions, config.language)
|
||||
launch = Launch(pass_, round_, rerun, pull_named(worktree, branch), worktree, branch, base, default, folder, folder / f"branch-{head}.diff", principles, goals, folder / "plan.md", starts_bare(next((agent for name, agent in REVIEWERS.items() if name == pass_), ""), home), config.paths["working-rules"], decisions, config.language)
|
||||
if rerun and not launch.asked().exists():
|
||||
return Failure(f"no report asked for a rerun of {pass_}'s round {round_}: {launch.asked()} is missing; relaunch before you commit the round's answers")
|
||||
written = write_inputs(launch, base, home)
|
||||
written = write_inputs(launch, base, home, plan_listing(plan_store(config)))
|
||||
if isinstance(written, Failure):
|
||||
return written
|
||||
return launch.header()
|
||||
|
||||
|
||||
def write_inputs(launch: Launch, base: str, home: pathlib.Path) -> Failure | None:
|
||||
"""Writes the branch diff from base to HEAD and what `larv-review places` prints into the review folder."""
|
||||
def write_inputs(launch: Launch, base: str, home: pathlib.Path, listing: str) -> Failure | None:
|
||||
"""Writes the branch diff from base to HEAD, what `larv-review places` prints, and the plan's listing into the review folder."""
|
||||
diff = git("diff", base, "HEAD", errors="replace")
|
||||
if isinstance(diff, Failure):
|
||||
return diff
|
||||
@@ -121,7 +126,7 @@ def write_inputs(launch: Launch, base: str, home: pathlib.Path) -> Failure | Non
|
||||
if isinstance(history, Failure):
|
||||
return history
|
||||
try:
|
||||
for path, text in ((launch.diff, diff), (launch.folder / "places.md", places_report(history[1]) + "\n")):
|
||||
for path, text in ((launch.diff, diff), (launch.folder / "places.md", places_report(history[1]) + "\n"), (launch.plan, listing)):
|
||||
# review-replay copies a file into a round's replay by its mtime, so rewriting one unchanged would drop it from every earlier round.
|
||||
if not path.exists() or path.read_text(encoding="utf-8") != text:
|
||||
path.write_text(text, encoding="utf-8")
|
||||
|
||||
@@ -1121,11 +1121,18 @@ class LarvReviewTool(unittest.TestCase):
|
||||
f"Diff: {folder}/branch-{short}.diff\n"
|
||||
f"Technical principles: {self.checkout.parent}/principles\n"
|
||||
f"Goals and audience: {self.checkout}/README.md\n"
|
||||
f"Plan: {folder}/plan.md\n"
|
||||
"Prose language: English.\n"
|
||||
f"Places: {folder}/places.md\n"
|
||||
)), ran.stderr)
|
||||
self.assertEqual((folder / f"branch-{short}.diff").read_text(), self.git("diff", base, "HEAD"))
|
||||
self.assertEqual((folder / "places.md").read_text(), self.run_tool("places").stdout)
|
||||
self.assertEqual((folder / "plan.md").read_text(), (
|
||||
f"# Plan, as {self.checkout}/todo.md holds it\n\n"
|
||||
"## Item 1, release 0.1.0\n\n**Do it.**\n\n"
|
||||
"## Item 2, release 0.2.0\n\n**Then this.**\n\n"
|
||||
"## Item 3, release 0.2.0\n\n**And this.**\n"
|
||||
))
|
||||
|
||||
def test_counts_the_round_from_the_branchs_answers_and_names_the_report_that_asked_for_a_rerun(self):
|
||||
self.commit("Answer prose round 1: a")
|
||||
@@ -1151,15 +1158,15 @@ class LarvReviewTool(unittest.TestCase):
|
||||
for given in (["security"], ["Stability"], ["prose", "--again"], []):
|
||||
self.assertEqual(self.run_tool("reviewer-header", *given).returncode, 1, given)
|
||||
|
||||
def test_reviewer_header_leaves_an_unchanged_diff_and_places_untouched_so_an_earlier_rounds_replay_keeps_them(self):
|
||||
def test_reviewer_header_leaves_an_unchanged_diff_places_and_plan_untouched_so_an_earlier_rounds_replay_keeps_them(self):
|
||||
self.commit("Work", {"a.txt": "one\n"})
|
||||
folder = self.checkout.parent / ".local" / "state" / "larv-review" / "proj"
|
||||
self.assertEqual(self.run_tool("reviewer-header", "stability").returncode, 0)
|
||||
written = [folder / f"branch-{self.git('rev-parse', '--short', 'HEAD').strip()}.diff", folder / "places.md"]
|
||||
written = [folder / f"branch-{self.git('rev-parse', '--short', 'HEAD').strip()}.diff", folder / "places.md", folder / "plan.md"]
|
||||
for path in written:
|
||||
os.utime(path, (0, 0))
|
||||
self.assertEqual(self.run_tool("reviewer-header", "prose").returncode, 0)
|
||||
self.assertEqual([path.stat().st_mtime for path in written], [0, 0])
|
||||
self.assertEqual([path.stat().st_mtime for path in written], [0, 0, 0])
|
||||
|
||||
def test_reviewer_header_names_why_it_names_no_pull_request(self):
|
||||
self.git("push", "-q", "-u", "origin", "chunk")
|
||||
|
||||
@@ -0,0 +1,44 @@
|
||||
import pathlib
|
||||
import sys
|
||||
import unittest
|
||||
|
||||
sys.path.insert(0, str(pathlib.Path(__file__).resolve().parents[1]))
|
||||
|
||||
from larv_review.plan_listing import plan_listing
|
||||
from plan_store.contract import FIRST, SECOND
|
||||
from plan_store.fakes import MemoryPlan
|
||||
from plan_store.stores import BLOCKED_BY
|
||||
|
||||
|
||||
class PlanListing(unittest.TestCase):
|
||||
def test_lists_each_item_with_its_release_tagline_blockers_and_detail_in_the_stores_order(self):
|
||||
plan = MemoryPlan(label="the epic ABC-12")
|
||||
plan.add(FIRST, "Count them where they are made.\n\nSay why.")
|
||||
plan.add(SECOND | {BLOCKED_BY: "1"}, "")
|
||||
self.assertEqual(plan_listing(plan), (
|
||||
"# Plan, as the epic ABC-12 holds it\n"
|
||||
"\n"
|
||||
"## Item 1, release 0.1.0\n"
|
||||
"\n"
|
||||
"**Count the runs.**\n"
|
||||
"\n"
|
||||
"Count them where they are made.\n"
|
||||
"\n"
|
||||
"Say why.\n"
|
||||
"\n"
|
||||
"## Item 2, release 0.2.0\n"
|
||||
"\n"
|
||||
"**Ship the later thing.**\n"
|
||||
"\n"
|
||||
"Blocked by: 1.\n"
|
||||
))
|
||||
|
||||
def test_says_so_where_the_plan_holds_no_item(self):
|
||||
self.assertEqual(plan_listing(MemoryPlan(label="the epic ABC-12")), "# Plan, as the epic ABC-12 holds it\n\nThe plan holds no item.\n")
|
||||
|
||||
def test_says_why_where_the_plan_cannot_be_read_so_a_reviewer_does_not_take_it_for_empty(self):
|
||||
self.assertEqual(plan_listing(MemoryPlan(label="the epic ABC-12", fails="Jira answered 401")), "# Plan, as the epic ABC-12 holds it\n\nThe plan cannot be read, so no item is listed: Jira answered 401\n")
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
unittest.main()
|
||||
@@ -2135,3 +2135,20 @@ Read most (opens and searches):
|
||||
- `bin/project_config/main.py` 5
|
||||
- `bin/project_config/settings.py` 4
|
||||
- `bin/release_plan/goals_file.py` 4
|
||||
|
||||
## Reading cost, chunk be2b74d8a78d, finished 2026-11-14T23:39:10Z
|
||||
|
||||
120395 new input tokens before the first commit.
|
||||
|
||||
Read most (opens and searches):
|
||||
|
||||
- `bin/project_config/test_project_config.py` 10
|
||||
- `README.md` 9
|
||||
- `bin/project_config/main.py` 7
|
||||
- `bin/project_config/settings.py` 5
|
||||
- `bin/mattermost_dm/test_mattermost_dm.py` 4
|
||||
- `CHANGELOG.md` 3
|
||||
- `bin/loop_effects/effects.py` 3
|
||||
- `bin/mattermost_dm/dm.py` 3
|
||||
- `.gitignore` 2
|
||||
- `bin/loop_claude/direct_message.py` 2
|
||||
|
||||
@@ -65,7 +65,7 @@ Give a reviewer without Bash `git ls-files`'s output in its prompt, since some h
|
||||
|
||||
`~/.claude/bin/larv-review` holds this section's mechanical rules: the chunk's review folder, the round count, the paired ruling's base and vote count, the scoring run's trigger; the history's format, its latest places and its count of how often seats agree; and the header of each reviewer's prompt. Run it in the chunk's worktree; `~/.claude/bin/larv-review --help` states each rule. On exit 1, repair what its message names and run it again; when you cannot, ask the user.
|
||||
|
||||
**Reports.** Run `~/.claude/bin/larv-review reviewer-header <pass>` in the chunk's worktree, and open each prompt to an agent under `~/.claude/agents/` with what it prints; then say in a few lines what the change does and which files it touches. The command makes the chunk's review folder and writes the branch diff into it. The header names that diff, the reviewer's full report, `<pass>-round-<n>.md`, in the folder, the folder of technical principles the project's config sets, and for architecture and stability the places too. For a reviewer whose definition starts it without `CLAUDE.md`, the header's last line names the file that holds the project principles and decision titles, which the reviewer reads first. For a relaunch one rung up, add `--rerun`: the report becomes `<pass>-round-<n>-rerun.md`, and the header names the report that asked. Before you answer a 🔴 or 🟡, read its entry: Grep the report for the finding's place, with the lines after it, rather than Read the whole report. rule-hook refuses a reviewer's Edit and MultiEdit, and any Write outside `~/.local/state/larv-review/`. Keep the folder after the merge: `review-replay` replays a round from the reports its prompt names.
|
||||
**Reports.** Run `~/.claude/bin/larv-review reviewer-header <pass>` in the chunk's worktree, and open each prompt to an agent under `~/.claude/agents/` with what it prints; then say in a few lines what the change does and which files it touches. The command makes the chunk's review folder and writes the branch diff into it, and the plan as a listing, read through the plan's store, so a reviewer without a shell reads it whatever holds the plan. The header names that diff, the reviewer's full report, `<pass>-round-<n>.md`, in the folder, the folder of technical principles the project's config sets, that listing, and for architecture and stability the places too. For a reviewer whose definition starts it without `CLAUDE.md`, the header's last line names the file that holds the project principles and decision titles, which the reviewer reads first. For a relaunch one rung up, add `--rerun`: the report becomes `<pass>-round-<n>-rerun.md`, and the header names the report that asked. Before you answer a 🔴 or 🟡, read its entry: Grep the report for the finding's place, with the lines after it, rather than Read the whole report. rule-hook refuses a reviewer's Edit and MultiEdit, and any Write outside `~/.local/state/larv-review/`. Keep the folder after the merge: `review-replay` replays a round from the reports its prompt names.
|
||||
|
||||
**Precedent, then ask** — for the full scan:
|
||||
|
||||
|
||||
@@ -2,7 +2,7 @@
|
||||
|
||||
Words: `~/.claude/CLAUDE.md` → "Vocabulary".
|
||||
|
||||
A reviewer reads and reports; it doesn't edit anything. It writes no file but its report, except the scratch files that a reviewer holding Bash makes with Bash. Read `docs/decisions.md` and `todo.md` first: a finding declined or disproved in `docs/decisions.md` or in a comment at the code it concerns, or filed in `todo.md`, is not raised again, unless the decline works against a goal or a technical principle and names no `todo.md` item ending it.
|
||||
A reviewer reads and reports; it doesn't edit anything. It writes no file but its report, except the scratch files that a reviewer holding Bash makes with Bash. Read `docs/decisions.md` and the plan, the file your prompt's `Plan:` line names, first: a finding declined or disproved in `docs/decisions.md` or in a comment at the code it concerns, or filed in the plan, is not raised again, unless the decline works against a goal or a technical principle and names no plan item ending it.
|
||||
|
||||
## Severity
|
||||
|
||||
|
||||
Reference in New Issue
Block a user