Merge remote-tracking branch 'origin/main' into item-410
CI / tests (pull_request) Has been cancelled
CI / tests (pull_request) Has been cancelled
# Conflicts: # docs/reading-cost.md # todo.md
This commit is contained in:
@@ -2,6 +2,8 @@
|
||||
|
||||
## Unreleased
|
||||
|
||||
- Refuse in rule-hook a Bash or Monitor command that waits forever: a sleeping loop with no time or count cap, and a `pgrep -f` or `pkill -f` whose pattern its own command line matches.
|
||||
- A project's config may list its team's convention files in `coding-conventions`, which larv-review's reviewer agents read beside the principles and the standards, the team's rule winning where they conflict. larv-review opens the pull request after its own review where a push to the branch starts CI, and files an item to add a mutation tool where `mutate-changes` covers none of a language. The technical principles gain rules for tests on a shared environment, "Never mock a service your own team runs" and "Don't loosen a type when refactoring"; stability-reviewer checks a change that stores a value differently; and every finding of an outside reviewer now changes the setup, a deterministic tool first.
|
||||
- do-epic's epic backends rank a child issue just before another, in Jira and in memory, and do-epic can re-rank Jira's backlog to an epic's ranking: it moves only the issues the loop filed, so each issue a person filed keeps its place, and it stops at the first rank Jira refuses and names it. Nothing calls it yet.
|
||||
- Comprehension seats run as the `comprehension-seat` agent under `agents/`, which starts without `CLAUDE.md` and the skill and agent listings, and `larv-review prepare-scoring` no longer takes `--preloaded`; after updating, launch each seat with `subagent_type: comprehension-seat`.
|
||||
- do-epic splits an epic item that changes several repos into one Jira sub-task per repo, each labelled `repo:<name>`, with a headless claude call predicting the repos from the code; the item is marked `split-by-repo` and counts as done once every sub-task is, and an issue a person filed gets a comment for the team in the epic's language. The epic backends gain `comment`, in the Jira backend and the in-memory one.
|
||||
|
||||
@@ -18,12 +18,12 @@ How work proceeds in any repo, unless the repo's `AGENTS.md` says otherwise. The
|
||||
- **Ask, don't guess.** Three choices are always the human's: a goal; a release, meaning the items planned into it and when it is cut; and a change to loop-claude's routing ladder, its rungs included. Any other rule that asks the human's approval reserves that choice too. Ask about a reserved choice. For any other choice, first check whether the goals already answer it. If they nearly do, propose a change to the goals and show how it answers this case: an answer settles one question, a goal settles every question like it. Otherwise take the option you would recommend, and record it with its reason: in the item's detail, or, where it governs later work, as the next sentence says. A recommendation you can give a reason for is not a guess. Ask only where you have no recommendation. Write every answer once, where it belongs, never only in chat: a goal in the goals file, a working rule in `AGENTS.md`, a standing choice in a comment at the one place it governs, or in `docs/decisions.md` once made in more than one place. When an answer holds a goal and a choice, write the goal in the goals file, and record as a choice only what the goal leaves open.
|
||||
- **Bench a syntax with the people who write it.** Before a new or changed spelling of something users read or write ships — markdown, HTML, a config key, a CLI flag — a panel of fresh-context readers, seated as those users from the goals file's `## Audience`, picks it.
|
||||
- **Implement the simplest change that solves the item, and ship it with `/larv-review`.** Whenever a test can check the change, write that test first and see it fail. Take its expected values from the item, never from the code. larv-review's reviewers hold the change to the technical principles, and a finding against one names it. Read a file in the principles folder the project's config sets (`~/.claude/bin/project-config principles` prints it) only when the item changes it, a finding or a record you write names it, or you decline a finding.
|
||||
- **Change the setup for each reasonable fix an outside reviewer asked for on a PR.** An outside reviewer is a forge's auto-reviewer or a human, not one of larv-review's reviewer agents. When you fix a comment of theirs, ask why our review didn't catch the fault first, and change the setup so it would; a fix that only answers the comment leaves the same gap open for the next chunk. Put the change in the first place that fits:
|
||||
1. claude-config's core: the reviewers' agents, `larv-review`, the hooks and tools, so every project gains.
|
||||
2. claude-config's technical principles or review standards, where a rule was missing or too vague.
|
||||
3. The project's own settings, principles folder or `AGENTS.md`, only where the gap is that project's alone. A client repo's `AGENTS.md` changes by a proposal of its own, per "A client project's `CLAUDE.md` and `AGENTS.md`" above.
|
||||
- **Change the setup for each finding an outside reviewer raises on a PR, deterministic tools first.** An outside reviewer is a forge's auto-reviewer or a human, not one of larv-review's reviewer agents. For each finding of theirs, whether you fix it or decline it, ask why our review didn't raise it first, and change the setup so it would; a fix that only answers the comment leaves the same gap open for the next chunk. Put the change in the first place that fits:
|
||||
1. A deterministic tool that would have caught it, such as a rule-hook rule, a gate check, a linter setting or `mutate-changes`: a tool catches the fault every time, and a reviewer only when it notices.
|
||||
2. A technical principle or a review standard, where a rule was missing or too vague: in claude-config's files, or in the project's own principles folder.
|
||||
3. Anything else: the reviewers' agents, `larv-review`'s text, or the project's own settings or `AGENTS.md`. A client repo's `AGENTS.md` changes by a proposal of its own, per "A client project's `CLAUDE.md` and `AGENTS.md`" above.
|
||||
|
||||
In claude-config, the change is a fix of the chunk. In another project, places 1 and 2 are an item in claude-config's plan: start a worktree of claude-config off `origin/main`, run `todo-item add` in it, commit the plan file, and ship it as a pull request of its own with `chunk-pr`, since claude-config's default branch may not take a direct push. Describe the gap without the client's name, code or comment text. File a change too big for the chunk as its own item. Where no place holds the gap, say so in the chunk's summary rather than inventing a change.
|
||||
Change claude-config's files where every project gains, and the project's own only where the gap is that project's alone. In claude-config, the change is a fix of the chunk. In another project, a change to the project's own files is a fix of the chunk too, and a change to claude-config's is an item in claude-config's plan: start a worktree of claude-config off `origin/main`, run `todo-item add` in it, commit the plan file, and ship it as a pull request of its own with `chunk-pr`, since claude-config's default branch may not take a direct push. Describe the gap without the client's name, code or comment text. File a change too big for the chunk as its own item. Where no setup gap caused the finding, as when the finding is wrong, say so in the chunk's summary rather than inventing a change.
|
||||
- **Remove a finished item from the plan, and revise any decision that cites it.** If the repo publishes something others consume — a package, an image, an API — reword the item for them and move it to `CHANGELOG.md` under `## Unreleased`. A changelog is for the public, never for the next agent. Otherwise delete it; git history is the record. `~/.claude/bin/todo-item finish <ID>` removes the item with its detail, and adds the bullet you pass with `--changelog <bullet>`; it refuses while a decision cites the item. A plan kept in Jira takes no bullet, since the issues' history is its changelog: `finish` there refuses `--changelog`. A chunk finishes its items as it merges, through `chunk-pr merge --finish <ID>`, which takes the same flags (`larv-review` §5).
|
||||
- **Releases are the human's.** The version bump and the publishing credentials are theirs, whatever another rule says. Prepare everything else, so cutting a release is one decision.
|
||||
- **Open each plan item or ticket with a bold one-sentence tagline**, so the taglines alone say what a release holds. The tagline states the target state, checkable when done: an imperative verb plus what holds afterwards. A present-tense fact reads as the current state and doesn't say anything about what to do. Add "today X" only where the direction is otherwise ambiguous. GOOD: `**Accept undefined in MetadataValue and drop such keys on output.**` BANNED: `MetadataValue accepts undefined; such keys are dropped on output`.
|
||||
|
||||
@@ -109,6 +109,8 @@ A project may also set `env-file`, the file of `KEY=value` credentials its tools
|
||||
|
||||
A project may also set `touch-predictions`, a path spelt as `changelog`'s is, such as `touch-predictions = "checkout:docs/touch-predictions.md"`. `touch-predictions record` appends each chunk's predicted files and parts there, beside those it touched. A project that leaves it out keeps no such record.
|
||||
|
||||
A project whose team wrote its own coding conventions lists the files in `coding-conventions`, each spelt as `principles` is, such as `coding-conventions = ["checkout:CONVENTIONS.md"]`. Each reviewer agent larv-review launches reads them beside the principles and the standards, and the team's rule wins where they conflict.
|
||||
|
||||
A project may also set `notifier` to `"mattermost"` or `"slack"`, the service that sends loop-claude's DMs. The `env-file` then holds that service's keys. A project that sets none gets no DMs, whatever its env file holds. `project-config notifier` prints the setting.
|
||||
|
||||
A project's config may set four more things, each optional, as `project-config --help` describes. `language` names the language its owners write in, where that isn't English: the worker writes the project's prose in it, and the prose reviewer judges the prose in it. `commit-title`, `pull-request-title` and `branch` are templates for a project that titles and names these in another way than `CLAUDE.md` → "Git, commits, and PRs" says. `chunk-preflight` names the branch and the worktree by the `branch` template. On a branch that fits it, rule-hook refuses a commit, and `chunk-pr` a pull request, whose title doesn't fit its template; on any other branch, such as a release review's, a title is the summary alone. A tool that reads a commit title, such as a round's `Answer <pass> round <n>:`, reads the template's `{summary}`: it tries `commit-title`, then `pull-request-title`, since a squash merge titles the commit as the pull request, then takes the title whole. While a project's config holds a fault, rule-hook refuses every commit there, and the tools that read its titles fail naming the fault.
|
||||
@@ -193,7 +195,7 @@ Install puts only `loop-claude` on `PATH`; call the others by their path, such a
|
||||
- `rank_todo.py [--check] [todo.md]` scores and ranks a project's `todo.md`, by default the one its config names; `rank_todo.py --help` states the format.
|
||||
- `reading-cost [--reset] [record]` appends a figure for each chunk `loop-claude` finished to a project's `docs/reading-cost.md`, and says whether the figures rise; `reading-cost --help` states the measure.
|
||||
- `review-replay <pass> <model>` replays a review pass's archived rounds from the projects run on the model, on the code each reviewed, and prints the lowest rung below the project's that, like each rung above it, qualifies: it finds no less of the 🔴 and 🟡 findings than two replays on the project's rung find, within a margin, and misses no 🔴 that both found. `review-replay --help` states the replay. With `--omit-claude-md`, `--bash-ceiling` or `--read-limit` it tests instead whether the pass's reviewer may start without `CLAUDE.md`, or under the Bash output ceiling loop-claude hands the worker, or a Read limit it doesn't hand yet: it replays each round three times as archived and once with the change, and prints whether the reviewer passes: whether the last replay missed no more findings than the most an unchanged replay missed, with each count and each finding it missed. Each replayed reviewer skips every permission prompt, stability-reviewer has Bash, and an archived prompt may name paths on the host.
|
||||
- `rule-hook [overrides]` blocks a tool call that breaks a rule a program can check, unless the call overrides the rule; `settings.json` → `hooks` runs it before each Agent, Bash, Edit, Grep, MultiEdit, Read, Skill and Write call, and `rule-hook --help` states the rules and the override.
|
||||
- `rule-hook [overrides]` blocks a tool call that breaks a rule a program can check, unless the call overrides the rule; `settings.json` → `hooks` runs it before each Agent, Bash, Edit, Grep, Monitor, MultiEdit, Read, Skill and Write call, and `rule-hook --help` states the rules and the override.
|
||||
- `run-heavy <command>` runs a heavy command once it holds one of the machine's heavy slots, one per 4 CPUs, which every session shares; `run-heavy --help` states the slots, and the memory cap it gives a container that sets no limit.
|
||||
- `run-tests [<pytest args>...]` runs this repo's test suite, as Test says.
|
||||
- `score-outcomes [L E I S]` shows what each finished item's chunk measured beside the scores the item was guessed at, to score a new item by. Per chunk it also shows code health's two counter-signals, misread findings and later fixes, and how many of the human's answers reversed a worker's choice; `score-outcomes --help` states the report.
|
||||
|
||||
@@ -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 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.
|
||||
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, or of a coding convention, which counts as one. Friction that is none of these is not a finding.
|
||||
|
||||
Verdict, severities and rounds: ~/.claude/skills/larv-review/review-findings.md. After the verdict:
|
||||
|
||||
|
||||
@@ -89,6 +89,7 @@ Catch behavior that is unclear or under-specified — "building in ambiguousness
|
||||
- Are consumers idempotent under at-least-once delivery (webhooks, queue retries, double-submit)? Where a duplicate would double-charge or double-send, is there an idempotency key or dedup?
|
||||
- Do DB constraints (NOT NULL, unique, FK) mirror what the code assumes, so bad data cannot arrive via another path?
|
||||
- New column on an existing table: what do existing rows contain — is null/default handled or backfilled?
|
||||
- Where the change stores a value differently, by escaping, converting or growing it: does the longest value it can now write still fit the column, counted as stored? Does every search, filter and comparison on the column still find what users type? Escaped text takes more room than the input's limit allows for, and a `LIKE` on an escaped column no longer matches an apostrophe.
|
||||
|
||||
### 8. Resources & Performance Under Production Data
|
||||
Works-on-fixtures, dies-on-volume is a stability bug.
|
||||
@@ -126,12 +127,13 @@ Every PR gets at least this sweep.
|
||||
- Were tests and implementation changed together in a way that could mask a regression — e.g. an assertion weakened to make a test pass? Flag it; these should be separate changes.
|
||||
- Does each test earn its keep, as the technical principles' test bullet says? Look at where its expected values come from, what it asserts, what it mocks, what wording it pins, whether another test already pins the behaviour, and whether it sleeps or reads the wall clock.
|
||||
- Does a test decide at run time whether to check anything, by a conditional skip, early return or catch around its assertions, as the technical principles' test bullet forbids? Flag it.
|
||||
- Does a test that runs on a shared environment hold the rules for such a test in the technical principles' "Compose, do not entangle" → "Tests and tooling"? Does the test that covers a seam to a service the team runs mock that service, which the test bullet's "Never mock a service your own team runs" forbids?
|
||||
- Are there untestable side effects that should be refactored?
|
||||
|
||||
|
||||
## Output Format
|
||||
|
||||
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.
|
||||
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, or of a coding convention, which counts as one; 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
|
||||
|
||||
@@ -302,8 +302,9 @@ class ChunkPreflightTool(unittest.TestCase):
|
||||
|
||||
def test_reads_origin_as_last_fetched_where_the_fetch_stalls_and_still_states_the_other_facts(self):
|
||||
repo = Repo(self)
|
||||
repo.stub_git(f'"fetch --quiet origin") exec {shutil.which("sleep")} 10;;')
|
||||
done = repo.preflight("--worktree", CHUNK_PREFLIGHT_TIMEOUT="1")
|
||||
repo.stub_git(f'"fetch --quiet origin") exec {shutil.which("sleep")} 30;;')
|
||||
# The timeout also stops `reading-cost`, so it is set well above the seconds `reading-cost` takes on a loaded runner.
|
||||
done = repo.preflight("--worktree", CHUNK_PREFLIGHT_TIMEOUT="5")
|
||||
self.assertEqual(done.returncode, 0, done.stderr)
|
||||
self.assertIn("as last fetched", done.stdout)
|
||||
self.assertIn("item 3, L 2, E + I 5", done.stdout)
|
||||
|
||||
@@ -130,7 +130,7 @@ prints it, such as stability. It prints the header of the prompt that launches t
|
||||
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 folders of technical principles and review standards the project's
|
||||
config sets, the goals and the plan and, for architecture and stability, the places. For a reviewer whose
|
||||
config sets, the files of coding conventions where it lists any, the goals and the plan and, for architecture and stability, the places. For a reviewer whose
|
||||
definition under ~/.claude/agents/ has `omitClaudeMd: true`, it then names the file that holds the
|
||||
project principles and decision titles, where the project keeps one. It writes the diff, from
|
||||
that base to HEAD, into the chunk's review folder as branch-<short HEAD>.diff, writes what
|
||||
@@ -138,7 +138,8 @@ places prints into places.md, and lists the plan's items into
|
||||
plan.md, whatever store holds the plan; a file whose text is unchanged is left as it is. With --rerun, the
|
||||
header names the report of a relaunch one rung up, in the same round, and the report that asked for
|
||||
it. It exits 1 when the pass takes no more rounds, when `project-config` fails in the checkout, when
|
||||
the principles or standards folder is not a folder with a file in it, or, with --rerun, when the
|
||||
the principles or standards folder is not a folder with a file in it, when a file the config lists
|
||||
in `coding-conventions` is missing, or, with --rerun, when the
|
||||
report that asked is missing.
|
||||
|
||||
round-title takes a pass as reviewer-header does. It prints how the commit that answers the pass's
|
||||
|
||||
@@ -44,6 +44,8 @@ class Launch:
|
||||
decisions: pathlib.Path
|
||||
# The language the project's config names for its prose.
|
||||
language: str
|
||||
# The files of the team's coding conventions, where the project's config names any.
|
||||
conventions: tuple[pathlib.Path, ...] = ()
|
||||
|
||||
def asked(self) -> pathlib.Path:
|
||||
"""The round's report, which asks for the rerun where there is one."""
|
||||
@@ -61,6 +63,7 @@ class Launch:
|
||||
f"Diff: {self.diff}",
|
||||
f"Technical principles: {self.principles}",
|
||||
f"Review standards: {self.standards}",
|
||||
*([f"Coding conventions: {', '.join(str(file) for file in self.conventions)}"] if self.conventions else []),
|
||||
f"Goals and audience: {self.goals}",
|
||||
f"Plan: {self.plan}",
|
||||
f"Prose language: {self.language}.",
|
||||
@@ -104,6 +107,10 @@ def reviewer_header(default: str, pass_: str, rerun: bool, home: pathlib.Path) -
|
||||
empty = next((setting for setting in ("principles", "standards") if not config.paths[setting].is_dir() or not any(config.paths[setting].iterdir())), None)
|
||||
if empty is not None:
|
||||
return Failure(f"{config.paths[empty]} is not a folder with a file in it; {config.folder / 'config.toml'} sets it as `{empty}`")
|
||||
# A reviewer told to read a file that isn't there would review without the team's rules, as with an empty principles folder.
|
||||
absent = next((file for file in config.coding_conventions if not file.is_file()), None)
|
||||
if absent is not None:
|
||||
return Failure(f"{absent} is not a file; {config.folder / 'config.toml'} sets it in `coding-conventions`")
|
||||
decisions = local_file(store(config, "decisions"), folder / "decisions.md")
|
||||
if isinstance(decisions, Failure):
|
||||
return decisions
|
||||
@@ -111,7 +118,7 @@ def reviewer_header(default: str, pass_: str, rerun: bool, home: pathlib.Path) -
|
||||
goals = local_file(goals_store(config), folder / "goals.md")
|
||||
if isinstance(goals, Failure):
|
||||
return goals
|
||||
launch = Launch(pass_, round_, rerun, pull_named(worktree, branch), worktree, branch, base, default, folder, folder / f"branch-{head}.diff", principles, standards, goals, folder / "plan.md", starts_bare(next((agent for name, agent in REVIEWERS.items() if name == pass_), ""), home), config.paths["working-rules"], decisions, config.language)
|
||||
launch = Launch(pass_, round_, rerun, pull_named(worktree, branch), worktree, branch, base, default, folder, folder / f"branch-{head}.diff", principles, standards, goals, folder / "plan.md", starts_bare(next((agent for name, agent in REVIEWERS.items() if name == pass_), ""), home), config.paths["working-rules"], decisions, config.language, config.coding_conventions)
|
||||
if rerun and not launch.asked().exists():
|
||||
return Failure(f"no report asked for a rerun of {pass_}'s round {round_}: {launch.asked()} is missing; relaunch before you commit the round's answers")
|
||||
written = write_inputs(launch, base, home, plan_listing(plan_store(config)))
|
||||
|
||||
@@ -1304,6 +1304,19 @@ class LarvReviewTool(unittest.TestCase):
|
||||
self.assertEqual((ran.returncode, ran.stdout), (1, ""))
|
||||
self.assertIn(f"{folder} is not a folder with a file in it; {self.config} sets it as `{setting}`", ran.stderr)
|
||||
|
||||
def test_reviewer_header_names_the_coding_conventions_only_where_the_projects_config_sets_them(self):
|
||||
self.assertIsNone(self.header_line("Coding conventions:", "prose"))
|
||||
(self.checkout / "CONVENTIONS.md").write_text("# Conventions\n")
|
||||
(self.config.parent / "style.md").write_text("# Style\n")
|
||||
self.config.write_text(PROJECT_CONFIG + 'coding-conventions = ["checkout:CONVENTIONS.md", "folder:style.md"]\n')
|
||||
self.assertEqual(self.header_line("Coding conventions:", "prose"), f"Coding conventions: {self.checkout}/CONVENTIONS.md, {self.config.parent}/style.md")
|
||||
|
||||
def test_reviewer_header_fails_where_a_coding_conventions_file_is_missing(self):
|
||||
self.config.write_text(PROJECT_CONFIG + 'coding-conventions = ["checkout:CONVENTIONS.md"]\n')
|
||||
ran = self.run_tool("reviewer-header", "prose")
|
||||
self.assertEqual((ran.returncode, ran.stdout), (1, ""))
|
||||
self.assertIn(f"{self.checkout}/CONVENTIONS.md is not a file; {self.config} sets it in `coding-conventions`", ran.stderr)
|
||||
|
||||
def test_reviewer_header_gives_the_architect_the_places(self):
|
||||
folder = self.checkout.parent / ".local" / "state" / "larv-review" / "proj"
|
||||
self.assertEqual(self.header_line("Places:", "architecture"), f"Places: {folder}/places.md")
|
||||
|
||||
@@ -77,6 +77,13 @@ a tool that needs one fails naming the setting. It is printed with the others on
|
||||
where `touch-predictions record` appends what each chunk was predicted to touch beside what it touched.
|
||||
Left out, the project keeps no such record. It is printed with the others only where it is set.
|
||||
|
||||
`coding-conventions` is an optional setting, a list of paths spelt as the others are: the files in
|
||||
which the project's team wrote its own coding conventions, such as
|
||||
`coding-conventions = ["checkout:CONVENTIONS.md"]`. Each reviewer agent larv-review launches reads
|
||||
them beside the principles and the standards, and the team's rule wins where they conflict. `project-config coding-conventions`
|
||||
prints one path a line. Left out, the reviewers read no such file. It is printed with the others only
|
||||
where it is set.
|
||||
|
||||
`notifier` is an optional setting, "mattermost" or "slack": the service that sends loop-claude's DMs and
|
||||
`notify`'s messages to the human. Setting it requires `env-file`, which holds that service's keys;
|
||||
`notify --help` names them. Left out, the project gets no DMs. It is printed with the others only where it
|
||||
@@ -134,18 +141,18 @@ The chunk for the issue ABC-123 is then on the branch ABC-123, in the worktree <
|
||||
and its commits and pull request are titled "ABC-123 - …".
|
||||
|
||||
Exit 1, naming each fault on stderr, where no config names the checkout, or its config leaves out a
|
||||
setting, names an unknown one, misspells a path, a language or a template, sets `wait-for-approval` or
|
||||
setting, names an unknown one, misspells a path, a language or a template, sets `coding-conventions` to anything but a list of paths, sets `wait-for-approval` or
|
||||
`tooling-on-host` to anything but true or false, sets `notifier` to anything but mattermost or slack or
|
||||
without `env-file`, sets `jira-finish-transition` or `jira-finish-status` to anything but a name, without the other or
|
||||
without a `plan` in Jira, names a Jira `plan` and leaves out `jira-score-formula` or `jira-score-bar`, sets
|
||||
one of those two without a `plan` in Jira, sets the formula to one that doesn't parse or the bar to anything
|
||||
but a number, sets `readability-floor` to anything but a number
|
||||
from 1 to 10, or sets `parallel-chunks` to anything but a whole number of 1 or more, and where `env-file`, `jira-finish-transition`, `jira-finish-status`, `notifier` or `touch-predictions` is asked for and not set. No path setting has a default.
|
||||
from 1 to 10, or sets `parallel-chunks` to anything but a whole number of 1 or more, and where `coding-conventions`, `env-file`, `jira-finish-transition`, `jira-finish-status`, `notifier` or `touch-predictions` is asked for and not set. No path setting has a default.
|
||||
"""
|
||||
import pathlib
|
||||
import sys
|
||||
|
||||
from project_config.settings import CONFIG, ENV_FILE, JIRA_FINISH_STATUS, JIRA_FINISH_TRANSITION, JIRA_SCORE_BAR, JIRA_SCORE_FORMULA, load, OPTIONAL, ProjectConfig, SCALARS, SETTINGS, Unnamed
|
||||
from project_config.settings import CODING_CONVENTIONS, CONFIG, ENV_FILE, JIRA_FINISH_STATUS, JIRA_FINISH_TRANSITION, JIRA_SCORE_BAR, JIRA_SCORE_FORMULA, load, OPTIONAL, ProjectConfig, SCALARS, SETTINGS, Unnamed
|
||||
from failure import Failure
|
||||
from git_cli.git_repo import git, Git
|
||||
from project_config import templates
|
||||
@@ -165,7 +172,10 @@ def main(argv: list[str]) -> int:
|
||||
# A one-value setting prints its value, its default where the config leaves it out; one without a default, as `notifier`, prints only where set.
|
||||
scalars = {scalar.name: scalar.shown(value) for scalar in SCALARS if (value := getattr(config, scalar.field)) is not None}
|
||||
paths = {**config.places, **({ENV_FILE: str(config.env_file)} if config.env_file else {}), **({JIRA_SCORE_FORMULA: config.jira_scoring.formula, JIRA_SCORE_BAR: f"{config.jira_scoring.bar:g}"} if config.jira_scoring else {}), **({JIRA_FINISH_TRANSITION: config.jira_finish.transition, JIRA_FINISH_STATUS: config.jira_finish.status} if config.jira_finish else {})}
|
||||
shown = paths | scalars
|
||||
# The listing names the conventions on one line; asked for alone, they print one path a line, for a script to read.
|
||||
conventions = [str(path) for path in config.coding_conventions]
|
||||
paths |= {CODING_CONVENTIONS: ", ".join(conventions)} if conventions else {}
|
||||
shown = paths | scalars | ({CODING_CONVENTIONS: "\n".join(conventions)} if conventions else {})
|
||||
if argv and argv[0] not in shown:
|
||||
print(f"{config.folder / CONFIG} sets no `{argv[0]}`", file=sys.stderr)
|
||||
return 1
|
||||
|
||||
@@ -48,6 +48,8 @@ PULL_REQUEST_TITLE = "pull-request-title"
|
||||
BRANCH = "branch"
|
||||
# An optional path setting: main's help says what it places.
|
||||
TOUCH_PREDICTIONS = "touch-predictions"
|
||||
# An optional setting: a list of paths, each spelt as SPELLING says, to the files that hold the team's own coding conventions, which each reviewer agent larv-review launches reads. Three readers, seated as the human who writes a client's config, picked the spelling 2-1 from four candidates, over a bare `conventions`, which they confused with `principles` and `working-rules`.
|
||||
CODING_CONVENTIONS = "coding-conventions"
|
||||
# Two optional settings, each a name, set together and only where `plan` names a Jira epic: the name of the workflow transition that finishes an item, and of the status it must lead to. Three readers, seated as the human who writes a client's config, picked the spelling from four candidates: two flat keys, as the other settings are, with a prefix that says what they apply to.
|
||||
JIRA_FINISH_TRANSITION = "jira-finish-transition"
|
||||
JIRA_FINISH_STATUS = "jira-finish-status"
|
||||
@@ -129,6 +131,8 @@ class ProjectConfig:
|
||||
commit_title: str = templates.TITLE
|
||||
pull_request_title: str = templates.TITLE
|
||||
branch: str = templates.BRANCH
|
||||
# The config's `coding-conventions`, in its order; empty where it sets none.
|
||||
coding_conventions: tuple[pathlib.Path, ...] = ()
|
||||
# The epic whose child issues are the plan, where the config's `plan` names one.
|
||||
epic: Epic | None = None
|
||||
# The epic whose description holds the goals and audience, where the config's `goals-and-audience` names one.
|
||||
@@ -196,6 +200,7 @@ def load(top: pathlib.Path, main: pathlib.Path, home: pathlib.Path) -> ProjectCo
|
||||
paths = {name: placed(values[name], top, file.parent, home) for name in (*SETTINGS, TOUCH_PREDICTIONS) if name in values}
|
||||
epics = {name: epic_of(values.get(name)) for name in EPIC_SPELLINGS}
|
||||
pages = {name: page for name in RECORDS if (page := page_of(values.get(name)))}
|
||||
conventions = conventions_of(values.get(CODING_CONVENTIONS, []), top, file.parent, home)
|
||||
env_file = anywhere(values.get(ENV_FILE), home)
|
||||
misplaced = ENV_FILE in values and (env_file is None or lies_in(env_file, top, main, file.parent))
|
||||
scalars = {scalar: scalar.read(values[scalar.name]) for scalar in SCALARS if scalar.name in values}
|
||||
@@ -210,6 +215,7 @@ def load(top: pathlib.Path, main: pathlib.Path, home: pathlib.Path) -> ProjectCo
|
||||
*(f"`{name}` is {values[name]!r}, not {SPELLING}, or {EPIC_SPELLINGS[name]}" for name in EPIC_SPELLINGS if name in values and paths[name] is None and epics[name] is None),
|
||||
*(f"`{name}` is {values[name]!r}, not {SPELLING}, or {PAGE_SPELLING}" for name in RECORDS if name in values and paths[name] is None and name not in pages),
|
||||
*([f"`{ENV_FILE}` is {values[ENV_FILE]!r}, not {OUTSIDE}"] if misplaced else []),
|
||||
*([f"`{CODING_CONVENTIONS}` is {values[CODING_CONVENTIONS]!r}, not a list of paths, each {SPELLING}"] if conventions is None else []),
|
||||
# Each setting that reaches a service needs the file that holds its credentials.
|
||||
*(f"`{name}` names a Jira epic, so `{ENV_FILE}` must name the file that holds its credentials" for name, epic in epics.items() if epic and ENV_FILE not in values),
|
||||
*(f"`{name}` names a Confluence page, so `{ENV_FILE}` must name the file that holds its credentials" for name in pages if ENV_FILE not in values),
|
||||
@@ -228,7 +234,7 @@ def load(top: pathlib.Path, main: pathlib.Path, home: pathlib.Path) -> ProjectCo
|
||||
return Failure(f"{file}: {'; '.join(faults)}. The settings are {', '.join(SETTINGS)}, and optionally {', '.join(OPTIONAL[:-1])} and {OPTIONAL[-1]}.")
|
||||
# faults names a formula or bar a plan in Jira lacks or misspells.
|
||||
assert scoring is not None or not epics["plan"]
|
||||
defaulted = ProjectConfig(file.parent.name, file.parent, top, {name: path for name, path in paths.items() if path}, env_file, epic=epics["plan"], goals_epic=epics["goals-and-audience"], jira_finish=Finish(*finish) if finish else None, jira_scoring=scoring, pages=pages)
|
||||
defaulted = ProjectConfig(file.parent.name, file.parent, top, {name: path for name, path in paths.items() if path}, env_file, epic=epics["plan"], goals_epic=epics["goals-and-audience"], jira_finish=Finish(*finish) if finish else None, jira_scoring=scoring, pages=pages, coding_conventions=conventions or ())
|
||||
return dataclasses.replace(defaulted, **{scalar.field: read for scalar, read in scalars.items()})
|
||||
|
||||
|
||||
@@ -332,7 +338,7 @@ SCALARS = (
|
||||
Scalar(PULL_REQUEST_TITLE, "pull_request_title", text_read(templates.title_fault)),
|
||||
Scalar(BRANCH, "branch", text_read(templates.branch_fault)),
|
||||
)
|
||||
OPTIONAL = tuple(sorted((ENV_FILE, TOUCH_PREDICTIONS, *JIRA_PLAN_ONLY, *(scalar.name for scalar in SCALARS))))
|
||||
OPTIONAL = tuple(sorted((CODING_CONVENTIONS, ENV_FILE, TOUCH_PREDICTIONS, *JIRA_PLAN_ONLY, *(scalar.name for scalar in SCALARS))))
|
||||
|
||||
|
||||
def lies_in(path: pathlib.Path, *places: pathlib.Path) -> bool:
|
||||
@@ -406,6 +412,14 @@ def placed(value: object, top: pathlib.Path, folder: pathlib.Path, home: pathlib
|
||||
return anywhere(value, home)
|
||||
|
||||
|
||||
def conventions_of(value: object, top: pathlib.Path, folder: pathlib.Path, home: pathlib.Path) -> tuple[pathlib.Path, ...] | None:
|
||||
"""The paths a `coding-conventions` value lists, or None where it is not a list of paths that `placed` can place."""
|
||||
if not isinstance(value, list):
|
||||
return None
|
||||
paths = tuple(path for listed in value if (path := placed(listed, top, folder, home)))
|
||||
return paths if len(paths) == len(value) else None
|
||||
|
||||
|
||||
def anywhere(value: object, home: pathlib.Path) -> pathlib.Path | None:
|
||||
if isinstance(value, str) and value.startswith("~/"):
|
||||
return home / value.removeprefix("~/")
|
||||
|
||||
@@ -410,6 +410,23 @@ class LoadTest(ConfigCase):
|
||||
(folder / "config.toml").write_text(CLIENT + 'touch-predictions = "docs/touch-predictions.md"\n', encoding="utf-8")
|
||||
self.assertIn("`touch-predictions` is 'docs/touch-predictions.md', not \"checkout:<path>\"", self.failure())
|
||||
|
||||
def test_coding_conventions_is_an_optional_list_of_paths_spelt_as_the_others_are(self) -> None:
|
||||
folder = self.write("acme", CLIENT)
|
||||
left_out = load(self.checkout, self.checkout, self.home)
|
||||
assert isinstance(left_out, ProjectConfig)
|
||||
self.assertEqual(left_out.coding_conventions, ())
|
||||
(folder / "config.toml").write_text(CLIENT + 'coding-conventions = ["checkout:CONVENTIONS.md", "folder:style.md", "~/shared/php.md"]\n', encoding="utf-8")
|
||||
found = load(self.checkout, self.checkout, self.home)
|
||||
assert isinstance(found, ProjectConfig)
|
||||
self.assertEqual(found.coding_conventions, (self.checkout / "CONVENTIONS.md", folder / "style.md", self.home / "shared/php.md"))
|
||||
|
||||
def test_coding_conventions_fails_where_it_is_not_a_list_or_one_of_its_paths_is_misspelt(self) -> None:
|
||||
folder = self.write("acme", CLIENT)
|
||||
for value, shown in (('"checkout:CONVENTIONS.md"', "'checkout:CONVENTIONS.md'"), ('["checkout:CONVENTIONS.md", "docs/style.md"]', "['checkout:CONVENTIONS.md', 'docs/style.md']"), ("[7]", "[7]")):
|
||||
with self.subTest(value=value):
|
||||
(folder / "config.toml").write_text(CLIENT + f"coding-conventions = {value}\n", encoding="utf-8")
|
||||
self.assertIn(f"`coding-conventions` is {shown}, not a list of paths, each \"checkout:<path>\"", self.failure())
|
||||
|
||||
def test_wait_for_approval_is_an_optional_boolean_that_is_false_where_left_out(self) -> None:
|
||||
folder = self.write("acme", CLIENT)
|
||||
left_out = load(self.checkout, self.checkout, self.home)
|
||||
@@ -526,7 +543,7 @@ class LoadTest(ConfigCase):
|
||||
|
||||
def test_the_failure_for_a_misplaced_env_file_and_a_missing_setting_names_both_and_lists_every_setting(self) -> None:
|
||||
folder = self.write("acme", "".join(line + "\n" for line in CLIENT.splitlines() if not line.startswith("plan")) + 'env-file = "checkout:.env"\n')
|
||||
self.assertEqual(self.failure(), f"{folder / 'config.toml'}: `plan` is missing; `env-file` is 'checkout:.env', not {OUTSIDE}. The settings are {', '.join(SETTINGS)}, and optionally branch, commit-title, env-file, jira-finish-status, jira-finish-transition, jira-score-bar, jira-score-formula, language, notifier, parallel-chunks, pull-request-title, readability-floor, tooling-on-host, touch-predictions and wait-for-approval.")
|
||||
self.assertEqual(self.failure(), f"{folder / 'config.toml'}: `plan` is missing; `env-file` is 'checkout:.env', not {OUTSIDE}. The settings are {', '.join(SETTINGS)}, and optionally branch, coding-conventions, commit-title, env-file, jira-finish-status, jira-finish-transition, jira-score-bar, jira-score-formula, language, notifier, parallel-chunks, pull-request-title, readability-floor, tooling-on-host, touch-predictions and wait-for-approval.")
|
||||
|
||||
def test_two_configs_naming_one_checkout_fail_naming_both(self) -> None:
|
||||
self.write("acme", CLIENT)
|
||||
@@ -660,6 +677,16 @@ class ToolTest(ConfigCase):
|
||||
one = self.run_tool("changelog", cwd=self.checkout / "src")
|
||||
self.assertEqual((one.returncode, one.stdout), (0, f"{self.checkout}/CHANGELOG.md\n"))
|
||||
|
||||
def test_prints_the_coding_conventions_one_path_a_line_where_the_config_sets_them(self) -> None:
|
||||
folder = self.write("acme", CLIENT)
|
||||
unset = self.run_tool("coding-conventions")
|
||||
self.assertEqual((unset.returncode, unset.stdout, unset.stderr), (1, "", f"{folder / 'config.toml'} sets no `coding-conventions`\n"))
|
||||
self.assertNotIn("coding-conventions", self.run_tool().stdout)
|
||||
(folder / "config.toml").write_text(CLIENT + 'coding-conventions = ["checkout:CONVENTIONS.md", "folder:style.md"]\n')
|
||||
one = self.run_tool("coding-conventions")
|
||||
self.assertEqual((one.returncode, one.stdout), (0, f"{self.checkout}/CONVENTIONS.md\n{folder}/style.md\n"))
|
||||
self.assertIn(f"coding-conventions: {self.checkout}/CONVENTIONS.md, {folder}/style.md\n", self.run_tool().stdout)
|
||||
|
||||
def test_prints_the_env_file_where_the_config_sets_one_and_fails_asking_for_it_where_it_does_not(self) -> None:
|
||||
folder = self.write("acme", CLIENT)
|
||||
unset = self.run_tool("env-file")
|
||||
|
||||
@@ -0,0 +1,122 @@
|
||||
"""The waits that cannot end in a Bash or Monitor command, for the `endless-wait` rule: a loop that sleeps with no time or count cap, and a `pgrep -f` or `pkill -f` whose pattern matches the command line that holds it.
|
||||
|
||||
A sleeping loop with no cap never ends. A `pgrep -f` or `pkill -f` finds the shell that runs it when its pattern matches that shell's command line, so a loop that waits for the process to disappear, as in `until [ -s f ] && ! pgrep -f "chunk-pr merg"; do sleep 15; done`, never ends either. A session that waits on one hangs.
|
||||
It reads the command's own text. A loop in a script file or in a variable's value isn't read, and a counter or deadline it doesn't recognise leaves the loop refused, which an override waives.
|
||||
"""
|
||||
import itertools
|
||||
import re
|
||||
|
||||
from command_lines.shell_command import launched, segments, Simple
|
||||
|
||||
# What stands before a command in a segment without being part of it, as in `do sleep 15` or `! pgrep -f x`.
|
||||
KEYWORDS = frozenset({"!", "do", "elif", "else", "if", "then", "{"})
|
||||
# The keywords of a loop whose condition is a command, as in `while sleep 30`.
|
||||
CONDITIONS = frozenset({"until", "while"})
|
||||
LOOPS = frozenset({"for", "until", "while"})
|
||||
SHELLS = frozenset({"bash", "dash", "sh", "zsh"})
|
||||
# A word with which a loop counts its rounds: `[ "$n" -lt 40 ]`.
|
||||
COUNTERS = frozenset({"-ge", "-gt", "-le", "-lt"})
|
||||
# `for ((;;))` has no condition. The lexer splits at its parentheses, so the check reads the command's text.
|
||||
FOREVER = re.compile(r"\bfor\s*\(\(\s*[^;)]*;\s*;")
|
||||
# A signal given to pkill, as -9 or -KILL, which is not a cluster of options.
|
||||
SIGNAL = re.compile(r"-(?:\d+|[A-Z]{2,})")
|
||||
# pgrep's and pkill's options that take a value, as short letters and as long names.
|
||||
VALUED = frozenset("dFgGPrstuU")
|
||||
VALUED_LONG = frozenset({"--delimiter", "--euid", "--group", "--ns", "--nslist", "--parent", "--pgroup", "--pidfile", "--runstates", "--session", "--signal", "--terminal", "--uid"})
|
||||
HOW = "use `~/.claude/bin/wait-for <file> [<pattern>] --timeout <seconds>`"
|
||||
# What the refusal of a self-matching pgrep or pkill suggests first. Only a pgrep waits, so only it is pointed to wait-for.
|
||||
INSTEAD = {"pgrep": f"{HOW}, a `pgrep -x` on the process name", "pkill": "use a `pkill -x` on the process name"}
|
||||
|
||||
|
||||
def endless_waits(command: str, simples: list[Simple], capped: bool) -> list[tuple[str, str]]:
|
||||
"""Each endless wait the command starts, as its detail and the directory it runs in. capped is whether something ends every loop in the simple commands: a Monitor call's timeout_ms, or a `timeout` around the shell, as in `timeout 60 bash -c '…'`."""
|
||||
found = [] if capped else [(f"a loop that sleeps, `{' '.join(loop[0].words)[:60]}`, has neither a time limit nor a count cap; {HOW}, or give the loop a deadline compared with `date` or $SECONDS, or a counter, as in `for i in $(seq 1 40)`", loop[0].directory) for loop in loops(simples) if endless(loop, command)]
|
||||
for simple in simples:
|
||||
if (found_match := self_match(simple.words, command)) is not None:
|
||||
tool, pattern = found_match
|
||||
found.append((f"`{pattern}` matches the command line that holds this `{tool} -f`, so `{tool}` finds the shell that runs the command; {INSTEAD[tool]}, or a pattern the command doesn't contain, such as `[c]hunk` for `chunk`", simple.directory))
|
||||
if (script := shell_script(simple.words)) is not None:
|
||||
found += endless_waits(command, [Simple(words, simple.directory) for words in segments(script)], capped or launched(simple.words, {"timeout"}) is not None)
|
||||
return found
|
||||
|
||||
|
||||
def core(words: list[str]) -> list[str]:
|
||||
"""The words of a segment without the keywords before its command or its loop keyword."""
|
||||
return list(itertools.dropwhile(KEYWORDS.__contains__, words))
|
||||
|
||||
|
||||
def invoked(words: list[str]) -> list[str]:
|
||||
"""The command a segment runs, which a loop's condition may be: `until ! pgrep -f x` runs pgrep."""
|
||||
return list(itertools.dropwhile((KEYWORDS | CONDITIONS).__contains__, words))
|
||||
|
||||
|
||||
def loops(simples: list[Simple]) -> list[list[Simple]]:
|
||||
"""Each loop as the segments from its keyword to its `done`, those of a loop nested in it included."""
|
||||
open_loops: list[list[Simple]] = []
|
||||
closed = []
|
||||
for simple in (Simple(core(simple.words), simple.directory) for simple in simples):
|
||||
kind = simple.words[0] if simple.words else None
|
||||
for loop in open_loops:
|
||||
loop.append(simple)
|
||||
if kind in LOOPS:
|
||||
open_loops.append([simple])
|
||||
elif kind == "done" and open_loops:
|
||||
closed.append(open_loops.pop())
|
||||
return closed + open_loops
|
||||
|
||||
|
||||
def endless(loop: list[Simple], command: str) -> bool:
|
||||
"""Whether the loop sleeps and nothing bounds it."""
|
||||
if not any(launched(invoked(simple.words), {"sleep"}) for simple in loop):
|
||||
return False
|
||||
head = loop[0].words
|
||||
if head[0] == "for":
|
||||
# A list ends the loop. An arithmetic `for` ends it only with a condition; its words stop at the lexer's split at `((`.
|
||||
return head == ["for"] and FOREVER.search(command) is not None
|
||||
# `while ((i < 10))` splits the same way, so a bare keyword reads as a count.
|
||||
if len(head) == 1:
|
||||
return False
|
||||
# A counter or a clock is judged by its words alone: a stricter test would refuse the bounded loops people write, and none can tell that the count advances or the clock is compared. So `-ge` on a file's line count, or a `date` that only logs, passes.
|
||||
words = {word for simple in loop for word in simple.words}
|
||||
return not (COUNTERS & words or any("SECONDS" in word for word in words) or any(launched(invoked(simple.words), {"date"}) for simple in loop))
|
||||
|
||||
|
||||
def shell_script(words: list[str]) -> str | None:
|
||||
"""The script of `bash -c <script>`, whose inner commands the lexer keeps as one word; None for any other command."""
|
||||
shell = launched(words, SHELLS)
|
||||
if shell is None:
|
||||
return None
|
||||
flags = [i for i, argument in enumerate(shell.arguments) if re.fullmatch(r"-[a-z]*c[a-z]*", argument)]
|
||||
return shell.arguments[flags[0] + 1] if flags and flags[0] + 1 < len(shell.arguments) else None
|
||||
|
||||
|
||||
def self_match(words: list[str], command: str) -> tuple[str, str] | None:
|
||||
"""The tool and the pattern of a `pgrep -f` or `pkill -f` whose pattern matches the command's own text, which is the shell's command line; None where there is none."""
|
||||
launch = launched(invoked(words), {"pgrep", "pkill"})
|
||||
if launch is None:
|
||||
return None
|
||||
full, patterns, rest = False, [], iter(launch.arguments)
|
||||
for word in rest:
|
||||
if word.startswith("--"):
|
||||
full = full or word == "--full"
|
||||
if word in VALUED_LONG:
|
||||
next(rest, None)
|
||||
elif word.startswith("-") and len(word) > 1 and not SIGNAL.fullmatch(word):
|
||||
for at, letter in enumerate(word[1:], 1):
|
||||
full = full or letter == "f"
|
||||
if letter in VALUED:
|
||||
# `-u root` takes the next word; `-uroot` has it in the cluster.
|
||||
if at == len(word) - 1:
|
||||
next(rest, None)
|
||||
break
|
||||
elif not word.startswith("-") or len(word) == 1:
|
||||
patterns.append(word)
|
||||
return next(((launch.tool, pattern) for pattern in patterns if full and matches(pattern, command)), None)
|
||||
|
||||
|
||||
def matches(pattern: str, text: str) -> bool:
|
||||
"""Whether pgrep's regular expression finds a match in text; an expression Python cannot read is taken as plain text."""
|
||||
try:
|
||||
return re.search(pattern, text) is not None
|
||||
except re.error:
|
||||
return pattern in text
|
||||
+11
-7
@@ -3,14 +3,14 @@
|
||||
usage: rule-hook (a PreToolUse hook: reads the call as JSON on stdin)
|
||||
rule-hook overrides (prints this chunk's overrides)
|
||||
|
||||
settings.json runs it before each Agent, Bash, Edit, Grep, MultiEdit, Read, Skill and Write call, in every session and
|
||||
settings.json runs it before each Agent, Bash, Edit, Grep, Monitor, MultiEdit, Read, Skill and Write call, in every session and
|
||||
subagent. The rules:
|
||||
|
||||
{rules}
|
||||
|
||||
A call overrides a rule with `# rule-override <rule>: <reason>`:
|
||||
|
||||
- anywhere in a Bash command, such as a trailing comment
|
||||
- anywhere in a Bash or Monitor command, such as a trailing comment
|
||||
- in a file, as a comment line in the text the edit writes
|
||||
- in Markdown, as `<!-- rule-override <rule>: <reason> -->`
|
||||
|
||||
@@ -64,6 +64,10 @@ from rule_hook.todo_check import todo_breaches
|
||||
from rule_hook.transcript_read import transcript_breaches
|
||||
|
||||
|
||||
# The tools whose `command` is a shell command. Claude Code ignores a hook's rewrite of a Monitor command, but rule-hook only blocks, so it reads the two alike; its endless-wait loop check is the exception, since a Monitor call ends at its timeout_ms.
|
||||
COMMAND_TOOLS = ("Bash", "Monitor")
|
||||
|
||||
|
||||
def main(argv: list[str], stdin: str) -> int:
|
||||
if argv in (["-h"], ["--help"]) or not argv and not stdin:
|
||||
print(__doc__.strip().replace("{rules}", rules_help()))
|
||||
@@ -84,7 +88,7 @@ def main(argv: list[str], stdin: str) -> int:
|
||||
if found is None:
|
||||
return 0
|
||||
written, what, breaches = found
|
||||
return answer(check(breaches, written, text(call.given, "file_path").endswith(".md"), call.tool == "Bash"), what, time.time())
|
||||
return answer(check(breaches, written, text(call.given, "file_path").endswith(".md"), call.tool in COMMAND_TOOLS), what, time.time())
|
||||
|
||||
|
||||
def breaches_of(call: Call, home: str, environ: typing.Mapping[str, str]) -> tuple[str, str, list[Breach]] | None:
|
||||
@@ -93,9 +97,9 @@ def breaches_of(call: Call, home: str, environ: typing.Mapping[str, str]) -> tup
|
||||
return text(call.given, "prompt"), text(call.given, "subagent_type"), reviewer_breaches(call, environ, home)
|
||||
if call.tool == "Skill":
|
||||
return text(call.given, "args"), text(call.given, "skill"), skill_breaches(call, environ, home)
|
||||
if call.tool == "Bash":
|
||||
if call.tool in COMMAND_TOOLS:
|
||||
command = text(call.given, "command")
|
||||
return command, command.split("\n", 1)[0], bash_breaches(command, call.cwd, home) + read_breaches(call, home) + env_file_breaches(call, home)
|
||||
return command, command.split("\n", 1)[0], bash_breaches(command, call.cwd, home, call.tool == "Monitor") + read_breaches(call, home) + env_file_breaches(call, home)
|
||||
if call.tool == "Read":
|
||||
return "", text(call.given, "file_path"), read_breaches(call, home) + env_file_breaches(call, home) + transcript_breaches(call, home)
|
||||
if call.tool == "Grep":
|
||||
@@ -126,13 +130,13 @@ def answer(checked: Checked, what: str, now: float) -> int:
|
||||
return 2 if unloggable else 0
|
||||
|
||||
|
||||
def bash_breaches(command: str, cwd: str, home: str) -> list[Breach]:
|
||||
def bash_breaches(command: str, cwd: str, home: str, monitor: bool = False) -> list[Breach]:
|
||||
"""The breaches of the command's own words, then of each commit it makes, then of the files those commits may take."""
|
||||
simples = simple_commands(command, cwd, home)
|
||||
found = commits(simples, home)
|
||||
in_commits = [breach for commit in found for breach in commit_breaches(commit, pathlib.Path(home))]
|
||||
in_files = [breach for directory in dict.fromkeys(commit.directory for commit in found) for breach in committed_file_breaches(directory)]
|
||||
return command_breaches(command, simples) + in_commits + in_files
|
||||
return command_breaches(command, simples, monitor) + in_commits + in_files
|
||||
|
||||
|
||||
def commit_breaches(commit: CommitCall, home: pathlib.Path) -> list[Breach]:
|
||||
|
||||
@@ -5,6 +5,7 @@ import typing
|
||||
|
||||
from review_rules.round_titles import CAP, COUNTS, EXAMPLE, lacks_counts, OPENING, RELEASE_REVIEW_CAP
|
||||
from git_cli.git_command import CommitCall
|
||||
from rule_hook.endless_wait import endless_waits
|
||||
from run_heavy.capped_docker import finds_this_docker
|
||||
from rule_hook.heavy_command import heavy
|
||||
from command_lines.shell_command import launched, LAUNCHERS, Simple
|
||||
@@ -12,7 +13,7 @@ from review_rules.review_folder import REPORTS
|
||||
from project_config import templates
|
||||
from command_lines.docker_command import unlimited
|
||||
|
||||
RuleName = typing.Literal["action-pin", "commit-one-line", "commit-title", "docker-run-memory", "env-file-read", "ignorefile-sorted", "image-pin", "no-ai-attribution", "repeat-read", "reviewer-report", "reviewer-rung", "round-cap", "round-title-counts", "run-heavy", "todo-rank-check", "transcript-read"]
|
||||
RuleName = typing.Literal["action-pin", "commit-one-line", "commit-title", "docker-run-memory", "endless-wait", "env-file-read", "ignorefile-sorted", "image-pin", "no-ai-attribution", "repeat-read", "reviewer-report", "reviewer-rung", "round-cap", "round-title-counts", "run-heavy", "todo-rank-check", "transcript-read"]
|
||||
|
||||
|
||||
@dataclasses.dataclass(frozen=True)
|
||||
@@ -40,6 +41,10 @@ RULES: dict[RuleName, Rule] = {
|
||||
"a container made with docker run or docker create has a memory limit and a swap limit, as large as its work needs, such as `--memory 4g --memory-swap 4g`, so a runaway container fails alone instead of starving the machine; a swap limit equal to the memory limit keeps it out of swap",
|
||||
"docker run, docker create, docker container run and docker container create, whether direct or through a launcher such as nice or timeout. One under run-heavy passes, as run-heavy's docker adds the limits on Linux, unless it names docker by its path, or changes or clears PATH, as env -i, sudo or doas do. A container a script or docker compose starts is not checked",
|
||||
),
|
||||
"endless-wait": Rule(
|
||||
"a wait ends: a loop that sleeps has a time limit or a count cap, and a `pgrep -f` or `pkill -f` has a pattern that its own command line doesn't match, since a pattern that line matches finds the shell that runs the command, and a loop that waits for that process to end never does; wait with `~/.claude/bin/wait-for <file> [<pattern>] --timeout <seconds>`, or find a process by name with `pgrep -x`",
|
||||
"a Bash command with an `until`, `while` or `for ((;;))` loop that runs `sleep` and has no `date` or $SECONDS comparison and no counter compared with -lt, -le, -gt or -ge, so a loop over a list, such as `for i in $(seq 1 40)`, passes; a Bash or Monitor command with a `pgrep -f` or `pkill -f` whose pattern, read as a regular expression, matches the command's text; the same inside the script of a shell's -c, where a `timeout` around the shell lifts only the loop check. A Monitor call's `timeout_ms` ends its loops, so only the `pgrep -f` and `pkill -f` check applies to it",
|
||||
),
|
||||
# A marker would let the credentials into the transcript all the same, so no marker waives it.
|
||||
"env-file-read": Rule(
|
||||
"an agent never reads ~/.claude/.env or a project's env-file, the file of credentials the project's config names, since a value the agent reads lands in its transcript, which loop-claude archives and the backups copy; it leaves a tool that needs a credential to read the file itself, gets the file's path from `~/.claude/bin/project-config env-file`, and spells the path another way, such as \"the .env in ~/.claude\", in a command that must mention it without reading it, such as a commit's title, and searches only a folder without it",
|
||||
@@ -158,11 +163,13 @@ def check(breaches: list[Breach], written: str, markdown: bool, bash: bool) -> C
|
||||
return Checked(messages, bool(blocking), [(breach, grant[breach.rule]) for breach, grant in zip(breaches, grants) if breach.rule in grant])
|
||||
|
||||
|
||||
def command_breaches(command: str, simples: list[Simple]) -> list[Breach]:
|
||||
def command_breaches(command: str, simples: list[Simple], monitor: bool = False) -> list[Breach]:
|
||||
"""The breaches of the command's own words; monitor is whether a Monitor call runs it, which ends every loop at its timeout_ms."""
|
||||
breaches = []
|
||||
publishing = [simple for simple in simples if posixpath.basename(simple.words[0]) in ("chunk-pr", "gh", "git", "tea")]
|
||||
if publishing and ATTRIBUTION.search(command):
|
||||
breaches.append(Breach("no-ai-attribution", "the command carries an attribution", publishing[0].directory))
|
||||
breaches += [Breach("endless-wait", detail, directory) for detail, directory in endless_waits(command, simples, monitor)]
|
||||
for simple in simples:
|
||||
if heavy(simple.words):
|
||||
breaches.append(Breach("run-heavy", f"run `{' '.join(simple.words)[:80]}` under `~/.claude/bin/run-heavy`, in the background", simple.directory))
|
||||
|
||||
@@ -144,6 +144,43 @@ class CommandBreaches(unittest.TestCase):
|
||||
with self.subTest(command):
|
||||
self.assertEqual(checked(command), [])
|
||||
|
||||
def test_a_loop_that_sleeps_without_a_time_or_count_cap_breaks_endless_wait(self):
|
||||
for command in ["until [ -s /tmp/x.log ]; do sleep 15; done", "while true; do sleep 1; done", "while ! curl -sf localhost:80; do sleep 2; done", "until [ -s /tmp/merge.log ] && ! pgrep -x chunk-pr; do sleep 15; done", "for ((;;)); do sleep 1; done", "echo a && until test -f f; do sleep 1; done", "bash -c 'until [ -s f ]; do sleep 1; done'", "if x; then while true; do sleep 1; done; fi", "for i in 1 2; do until [ -s f ]; do sleep 1; done; done", "tail -f x | while read l; do sleep 1; done", "until timeout 5 curl -sf x; do sleep 1; done", "until [ -s f ]; do echo seconds; sleep 1; done", "until [ -s f ]\ndo\n sleep 1\ndone", "bash -x -c 'until [ -s f ]; do sleep 1; done'", "while sleep 30; do echo x; done", "until ! pgrep -x chunk-pr; do sleep 5; done"]:
|
||||
with self.subTest(command):
|
||||
self.assertEqual(checked(command), ["endless-wait"])
|
||||
|
||||
def test_a_loop_with_a_deadline_a_count_or_no_sleep_passes_endless_wait(self):
|
||||
for command in ["until [ -s f ]; do sleep 15; [ $((n+=1)) -ge 40 ] && break; done", "end=$((SECONDS+600)); until [ -s f ] || [ $SECONDS -gt $end ]; do sleep 5; done", "until [ -s f ] || [ $(date +%s) -ge $end ]; do sleep 5; done", "n=0; while [ $n -lt 40 ]; do sleep 1; n=$((n+1)); done", "while ((n < 40)); do sleep 1; done", "until [ -s f ] || [ \"$SECONDS\" = 600 ]; do sleep 5; done", "until [ -s f ] || [ $(date +%s) = $end ]; do sleep 5; done", "while read l; do echo $l; done < f; sleep 5", "bash script.sh", "bash -c", "bash -x", "for i in $(seq 1 40); do [ -s f ] && break; sleep 15; done", "for f in a b c; do sleep 1; done", "for ((i=0; i<40; i++)); do sleep 1; done", "timeout 600 bash -c 'until [ -s f ]; do sleep 1; done'", "~/.claude/bin/wait-for /tmp/x.log 'merged' --timeout 600", "while read l; do echo $l; done < f", "until [ -s f ]; do echo waiting; done", "echo 'until x; do sleep 1; done'", "until ! pgrep -x chunk-pr || [ $SECONDS -gt 600 ]; do sleep 15; done"]:
|
||||
with self.subTest(command):
|
||||
self.assertEqual(checked(command), [])
|
||||
|
||||
def test_a_pgrep_or_pkill_f_whose_pattern_the_command_contains_breaks_endless_wait(self):
|
||||
for command in ["pgrep -f chunk-pr", "pkill -f 'loop-claude'", "pgrep -fa chunk-pr", "pgrep -u me -f chunk-pr", "pgrep --full chunk-pr", "pkill -9 -f loop-claude", "pkill -KILL -f loop-claude", "pgrep -f chunk-pr -u", "pkill --full chunk-pr --signal", "pgrep -f -", "if pgrep -f loop-claude; then echo up; fi", "until ! pgrep -f \"chunk-pr merg\" || [ $SECONDS -gt 600 ]; do sleep 15; done", "pgrep -U me -f chunk-pr", "pgrep -fUME chunk-pr", "pgrep -f9 chunk-pr", "pgrep --signal TERM --full chunk-pr", "pgrep -f 'chunk[pr'", "pgrep -f 'chunk-pr .*merg'", "nice pgrep -f chunk-pr", "bash -c 'pgrep -f chunk-pr'"]:
|
||||
with self.subTest(command):
|
||||
self.assertEqual(checked(command), ["endless-wait"])
|
||||
ending = ", or a pattern the command doesn't contain, such as `[c]hunk` for `chunk`"
|
||||
self.assertEqual(breaches("pgrep -f chunk-pr")[0].detail, "`chunk-pr` matches the command line that holds this `pgrep -f`, so `pgrep` finds the shell that runs the command; use `~/.claude/bin/wait-for <file> [<pattern>] --timeout <seconds>`, a `pgrep -x` on the process name" + ending)
|
||||
self.assertEqual(breaches("pkill -f chunk-pr")[0].detail, "`chunk-pr` matches the command line that holds this `pkill -f`, so `pkill` finds the shell that runs the command; use a `pkill -x` on the process name" + ending)
|
||||
|
||||
def test_an_endless_wait_names_its_loop_and_the_directory_it_runs_in(self):
|
||||
head = "until [ -s /tmp/a-file-whose-name-takes-the-head-past-sixty-characters-by-itself ]"
|
||||
found = breaches(f"cd /w && {head}; do sleep 1; done")
|
||||
self.assertEqual([breach.directory for breach in found], ["/w"])
|
||||
self.assertIn(f"`{head[:60]}`, has neither a time limit nor a count cap; use `~/.claude/bin/wait-for", found[0].detail)
|
||||
self.assertEqual([breach.directory for breach in breaches("cd /w && bash -c 'pgrep -f x; until [ -s f ]; do sleep 1; done'")], ["/w", "/w"])
|
||||
self.assertEqual([breach.directory for breach in breaches("cd /w && until [ -s f ] && cd /x && true; do sleep 1; done")], ["/w"])
|
||||
self.assertEqual(len(breaches("pgrep -f aa; bash -c 'pgrep -f bb'")), 2)
|
||||
|
||||
def test_a_loop_that_waits_on_its_own_pgrep_breaks_endless_wait_twice(self):
|
||||
command = 'until [ -s /tmp/merge-402.log ] && ! pgrep -f "chunk-pr merg"; do sleep 15; done'
|
||||
self.assertEqual(checked(command), ["endless-wait", "endless-wait"])
|
||||
self.assertEqual(checked(command.replace("-f ", "-x ")), ["endless-wait"])
|
||||
|
||||
def test_a_pgrep_f_on_a_pattern_the_command_lacks_or_a_pgrep_without_f_passes_endless_wait(self):
|
||||
for command in ["pgrep -f '[c]hunk-pr merg'", "pgrep -f \"$name\"", "pgrep -f '^python3 .*loop-claude$'", "pgrep -x chunk-pr", "pgrep chunk-pr", "pgrep -u me -x chunk-pr", "pkill -f -u me '[l]oop-claude'", "pkill --signal TERM --full '[c]hunk'", "pkill -KILL -f '[l]oop-claude'", "pkill -9 -f '[l]oop-claude'", "pkill --signal=TERM --full '[c]hunk'", "pgrep -f -U me '[c]hunk' -u", "echo pgrep -f chunk-pr", "git commit -m 'Refuse pgrep -f chunk-pr'", "pgrep -f"]:
|
||||
with self.subTest(command):
|
||||
self.assertEqual(checked(command), [])
|
||||
|
||||
def test_an_attribution_breaks_only_in_a_git_gh_tea_or_chunk_pr_command(self):
|
||||
self.assertEqual(checked(f"tea pr create --description '{TRAILER}'"), ["no-ai-attribution"])
|
||||
self.assertEqual(checked(f"~/.claude/bin/chunk-pr open 'Do it' '{TRAILER}'"), ["no-ai-attribution"])
|
||||
@@ -959,6 +996,21 @@ class Hook(unittest.TestCase):
|
||||
self.assertIn("Blocked by rule image-pin: ", ran.stderr)
|
||||
self.assertIn("`# rule-override image-pin: <reason>`", ran.stderr)
|
||||
|
||||
def test_a_monitor_command_is_checked_for_a_self_matching_pgrep_but_not_for_a_loop_its_timeout_ends(self):
|
||||
monitor = {"command": "pgrep -f chunk-pr", "description": "d", "timeout_ms": 60000}
|
||||
ran = hook({"cwd": self.repo, "tool_input": monitor, "tool_name": "Monitor"}, self.repo)
|
||||
self.assertEqual(ran.returncode, 2)
|
||||
self.assertIn("Blocked by rule endless-wait: ", ran.stderr)
|
||||
self.assertIn("`# rule-override endless-wait: <reason>` to the command", ran.stderr)
|
||||
looping = monitor | {"command": "until [ -s f ]; do sleep 15; done"}
|
||||
self.assertEqual(hook({"cwd": self.repo, "tool_input": looping, "tool_name": "Monitor"}, self.repo).returncode, 0)
|
||||
self.assertEqual(hook({"cwd": self.repo, "tool_input": looping | {"command": looping["command"] + " # x"}, "tool_name": "Bash"}, self.repo).returncode, 2)
|
||||
|
||||
def test_settings_hooks_a_monitor_call(self):
|
||||
settings = json.loads((HOOK.parent.parent / "settings.json").read_text())
|
||||
matchers = [entry["matcher"].split("|") for entry in settings["hooks"]["PreToolUse"] if "rule-hook" in entry["hooks"][0]["command"]]
|
||||
self.assertIn("Monitor", matchers[0])
|
||||
|
||||
def test_an_edit_of_a_fifo_or_a_device_finishes(self):
|
||||
fifo = f"{self.repo}/pipe"
|
||||
os.mkfifo(fifo)
|
||||
|
||||
@@ -2854,3 +2854,37 @@ Read most (opens and searches):
|
||||
- `bin/do_epic/backend/protocol.py` 2
|
||||
- `bin/do_epic/ranking.py` 2
|
||||
- `bin/plan_store/test_jira_epic.py` 2
|
||||
|
||||
## Reading cost, chunk 410d6dbe665d, finished 2026-11-18T19:41:25Z
|
||||
|
||||
159659 new input tokens before the first commit.
|
||||
|
||||
Read most (opens and searches):
|
||||
|
||||
- `bin/project_config/settings.py` 7
|
||||
- `README.md` 6
|
||||
- `bin/larv_review/test_larv_review.py` 5
|
||||
- `bin/project_config/main.py` 5
|
||||
- `skills/larv-review/SKILL.md` 5
|
||||
- `bin/larv_review/reviewer_header.py` 4
|
||||
- `bin/project_config/test_project_config.py` 4
|
||||
- `CLAUDE.md` 3
|
||||
- `agents/stability-reviewer.md` 3
|
||||
- `bin/chunk_pr/main.py` 3
|
||||
|
||||
## Reading cost, chunk 93fadde84de7, finished 2026-11-18T21:42:40Z
|
||||
|
||||
106794 new input tokens before the first commit.
|
||||
|
||||
Read most (opens and searches):
|
||||
|
||||
- `bin/rule_hook/test_rule_hook.py` 6
|
||||
- `bin/rule_hook/main.py` 5
|
||||
- `bin/rule_hook/rules.py` 5
|
||||
- `bin/command_lines/shell_command.py` 3
|
||||
- `bin/rule_hook/call.py` 3
|
||||
- `settings.json` 3
|
||||
- `bin/rule_hook/heavy_command.py` 2
|
||||
- `README.md` 1
|
||||
- `bin/rule_hook/endless_wait.py` 1
|
||||
- `bin/rule_hook/env_file.py` 1
|
||||
|
||||
@@ -10,7 +10,12 @@
|
||||
- Services and networking: a deploy trigger, health probe, backup job or admin path gets its own way in, since one routed through the application it operates on fails in exactly the state it exists for. BANNED: a deploy webhook reached through the app's own reverse proxy. GOOD: its own listener, answering while the app is down.
|
||||
- Modules: dependencies point one way. Callers may know the service; the service never knows its callers, and neither it nor its comments name or assume the delivery mechanism (controller, HTTP, request validation, route), because a queue worker, a CLI or another service may call it too. BANNED: `// The controller's validator guarantees these fields`. GOOD: "callers must supply X", or the guard and the type signature alone.
|
||||
- Functions: a function takes what it needs as arguments and returns what it produces. One that works only after another has set up shared state, or leaves state for the next to find, is entangled with it. BANNED: `validate(conf)` that fills defaults `send(conf)` relies on. GOOD: `send(withDefaults(conf))`.
|
||||
- Tests and tooling: a test, script or pipeline stage that passes only because another ran first is entangled; it states what it needs and gets it.
|
||||
- Tests and tooling: a test, script or pipeline stage that passes only because another ran first is entangled; it states what it needs and gets it. A shared environment is one that other tests, people or a second copy of the test use at the same time. A test on one also holds these rules:
|
||||
- Assert only on records the test created and can name, never on a count or the first row. BANNED: `expect(rows.length).toBe(3)`; `expect(rows[0].name).toBe("Ada")`. GOOD: `expect(rows.find((row) => row.id === created.id)).toMatchObject({ name: "Ada" })`.
|
||||
- Never change state the test doesn't own. BANNED: a test that turns off a setting every tenant shares, or empties a table to start clean. GOOD: the test creates a tenant and changes the setting there.
|
||||
- Pass in any order, and beside a second copy of the test running at the same time. BANNED: a fixture user named `test-user@example.com`. GOOD: `user-${unique}@example.com`, where the test made `unique` for this run.
|
||||
- A helper registers its teardown before it creates anything, keyed by a value it made itself, and the teardown deletes only what it can name. BANNED: create the order, then register `DELETE FROM orders WHERE created_at > :start`. GOOD: make a reference, register `DELETE FROM orders WHERE reference = :reference`, then create the order under it.
|
||||
- A helper that saves a record checks what was saved, never the status code alone. BANNED: `expect(response.status).toBe(200)` as the helper's only check. GOOD: read the record back and compare each field the helper set.
|
||||
- Proximity is not a reason. Reusing a listener, config file, table, module or service because it is already there, when the new thing has no relationship to it, is how entanglement gets in. If you cannot name the seam, there is none.
|
||||
* Functional core, imperative shell — a core rule beside "Compose, do not entangle": no other principle overrides it.
|
||||
- Decisions live in pure functions, data in and data out; the shell around them performs the effects and holds no branching of its own.
|
||||
@@ -24,6 +29,7 @@
|
||||
- When this pulls against "Explicit over implicit", the deep module wins, unless hiding the work makes it harder for someone new to the project to tell what the call does.
|
||||
* Make invalid states unrepresentable.
|
||||
- Example: using a time-only type in the database when we actually want to store a time of day introduces risk for errors.
|
||||
- A function's inputs too: take only inputs that cannot disagree, instead of checking that they agree. BANNED: a test helper that takes a token and a message, and checks that the message holds the token. GOOD: the helper makes the token and builds the message. When a review finds a second edge case in a check, change the signature so the input can't occur.
|
||||
* Always store timestamps as full ISO datetime in UTC.
|
||||
- Always communicate timestamps as full ISO datetime in UTC from APIs with database access.
|
||||
* Always grant explicit access to data, both read and write.
|
||||
@@ -38,12 +44,14 @@
|
||||
- For example, parse a form into a strictly typed DTO as the first thing that happens instead of passing strings down to be validated deep inside a service.
|
||||
- A cast (`x as Foo`) asserts what the compiler could not check and stops it checking — so when the type later changes, nothing tells you. Derive the real type instead: infer it, name the return type, or parse the input once into a typed shape. Where a value genuinely arrives untyped (HTTP body, `JSON.parse`, DB row), the boundary owes a **type guard validating the fields it claims**; past that boundary everything is typed. `as unknown as T` and non-null `!` are the same defect wearing a hat. BANNED: `const user = body as User` — one rename and it is a silent lie. GOOD: `function isUser(v: unknown): v is User` checking each field, then `if (!isUser(body)) return { error: … }`.
|
||||
- DTOs, enums, and value objects are pure data — no logic. They stand in for the structs/records a language lacks.
|
||||
- Don't loosen a type when refactoring. A function that returned a concrete type keeps returning it when its implementation changes, never `object`, `array`, `mixed` or `any`; introduce a DTO or value object instead. BANNED: `totals(): Totals` becomes `totals(): array` once it reads from two sources. GOOD: `totals(): Totals` stays, and a new `SourceTotals` value object holds what each source returns.
|
||||
* Always use explicit state machines.
|
||||
* Most, if not all, code should have automated tests, and each test earns its keep.
|
||||
- A valuable test checks behaviour through the unit's interface, fails when that behaviour breaks, and still passes after a refactor that keeps that behaviour.
|
||||
- Write the test first and watch it fail on its assertion, not on an error, before implementing.
|
||||
- Take expected values from the requirement — the item, ticket, spec or a hand-worked example — never from running the code or calling its helpers. A test that records today's output locks in today's bug. BANNED: `assert text.endswith(applications_text(applied))`, where `applications_text` is the code's own helper. GOOD: the expected text written out for one small input.
|
||||
- Assert the outcome — returned values, stored state, emitted output — not how the code reached it. Use real collaborators or fakes; mock only slow, nondeterministic or external edges. BANNED: asserting which internal function ran, or scanning the source with `ast` or a regex. GOOD: `assertEqual(saved_row, {...})` against a fake store; a fake clock.
|
||||
- Never mock a service your own team runs. Test the seam to it against its real build, in a harness that runs the real stack; mock only a third party that can't be run locally in a reasonable way. The rule binds the test that covers the seam: a unit test of the caller's own logic may still use a fake, as "Use real collaborators or fakes" above allows. BANNED: the only test of the call to the team's billing service stubs its HTTP responses. GOOD: that test calls the billing service's own image, started in the test stack.
|
||||
- Pin wording only where the wording is the contract: a message a consumer parses, a published format. For prompts, help and error text, assert the facts the text must carry — an item ID, a model argument, an error code — not the sentence. BANNED: `assertIn("<a 600-character prompt sentence>", prompt)`. GOOD: `assertIn("model opus, effort high", prompt)`.
|
||||
- One behaviour per test, named for it, tested once, at the lowest level that reproduces it. No loops or branches in a test body; parametrize the cases.
|
||||
- A test doesn't decide at run time whether to check anything: no conditional skip, early return, or catch around its assertions. A test that needs a state creates it, or fails and names what is missing. BANNED: `test.skip(created.every((count) => count === 0))` after the payroll run under test, since a broken payroll also creates zero rows. GOOD: before running the payroll, check each precondition and fail naming the one that is missing; after it, `expect(created).toEqual([1, 2, 1])`.
|
||||
|
||||
+1
-1
@@ -32,7 +32,7 @@
|
||||
"type": "command"
|
||||
}
|
||||
],
|
||||
"matcher": "Agent|Bash|Edit|Grep|MultiEdit|Read|Skill|Write"
|
||||
"matcher": "Agent|Bash|Edit|Grep|Monitor|MultiEdit|Read|Skill|Write"
|
||||
}
|
||||
],
|
||||
"SubagentStart": [
|
||||
|
||||
@@ -22,7 +22,12 @@ The bar a chunk is reviewed to: `quality.md` in the project's review standards,
|
||||
|
||||
## 2. Ship the branch (idempotent — skip whatever already exists)
|
||||
|
||||
Follow `~/.claude/CLAUDE.md` → "Git, commits, and PRs". Never commit to the default branch. Commit, then run `~/.claude/bin/chunk-pr open '<title>' '<summary>'`: it pushes with upstream set and opens a **draft** PR, so CI cycles while the review runs. No remote → review locally and say so in the summary.
|
||||
Follow `~/.claude/CLAUDE.md` → "Git, commits, and PRs". Never commit to the default branch. Commit. Then read in the repo's CI config, such as a workflow file's `on:`, what starts a CI run:
|
||||
|
||||
- **A push to the chunk's branch starts one** → open no pull request yet. Push with `git push --set-upstream origin <branch>` now and after each commit, so CI cycles while the review runs. §4 opens the pull request once our own review is done: human reviewers see a draft, and a forge's auto-reviewer may review one, so an early draft draws findings our passes would have caught.
|
||||
- **Only a pull request starts one, or the repo has no CI** → run `~/.claude/bin/chunk-pr open '<title>' '<summary>'` now: it pushes with upstream set and opens a **draft** PR, so CI cycles while the review runs.
|
||||
|
||||
No remote → review locally and say so in the summary.
|
||||
|
||||
**Work in the worktree.** Enter the chunk's worktree with the `EnterWorktree` tool, `path` set to it, unless the session already works there. A reviewer, a seat and the security pass's skill read the diff of the session's working directory, and a subagent starts there; from the checkout root they find the branch's diff empty.
|
||||
|
||||
@@ -32,6 +37,8 @@ Follow `~/.claude/CLAUDE.md` → "Git, commits, and PRs". Never commit to the de
|
||||
|
||||
**Mutation tests.** Where the branch changes code, run the project's mutation command in the chunk's worktree, with every change committed, before each stability round: the one the project's README documents, else `~/.claude/bin/run-heavy ~/.claude/bin/mutate-changes --prefix '<how the project runs its tools>'`. `mutate-changes --help` says how to set `--prefix` and `--jobs`. Where a mutant of a changed line survives and changes behaviour, kill it: add or strengthen a test that fails on it, commit, and run the command again. Hand stability-reviewer what the last run printed, with the commit it ran on. On exit 1, repair what its message names and run it again; when you cannot, hand the reviewer the message.
|
||||
|
||||
Where `mutate-changes` prints `Not mutated, as no tool covers their language:` and that line names a file of code, not only Markdown or config files, file a plan item titled `**Add a mutation tool for <language>.**`, scored per `~/.claude/rules/todo-items.md`. Its detail names the language's mutation tool, pinned to a version that supports the project's language version, and the code files the line named. Where an earlier chunk filed the item, add this chunk's files to its detail instead.
|
||||
|
||||
## 3. Passes
|
||||
|
||||
A pass is one kind of review, a row of the table, named by its first column. Its trigger says when it first runs, on the chunk's branch; "Re-entry" says when a fix reruns it. Its reviewer reports the findings.
|
||||
@@ -65,7 +72,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 and each round commit's counts, the paired ruling's base and vote count, the scoring run's trigger; the history's format, its latest places and its count of how often seats agree; and the header of each reviewer's prompt. Run it in the chunk's worktree; `~/.claude/bin/larv-review --help` states each rule. On exit 1, repair what its message names and run it again; when you cannot, ask the user.
|
||||
|
||||
**Reports.** Run `~/.claude/bin/larv-review reviewer-header <pass>` in the chunk's worktree, and open each prompt to an agent under `~/.claude/agents/` with what it prints; then say in a few lines what the change does and which files it touches. The command makes the chunk's review folder and writes the branch diff and the plan's listing into it. The header names that diff, the reviewer's full report, `<pass>-round-<n>.md`, in the folder, the folders of technical principles and review standards the project's config sets, the listing, and for architecture and stability the places too. For a reviewer whose definition starts it without `CLAUDE.md`, the header's last line names the file that holds the project principles and decision titles, which the reviewer reads first. For a relaunch one rung up, add `--rerun`: the report becomes `<pass>-round-<n>-rerun.md`, and the header names the report that asked. Before you answer a 🔴 or 🟡, read its entry: Grep the report for the finding's place, with the lines after it, rather than Read the whole report. rule-hook refuses a reviewer's Edit and MultiEdit, and any Write outside `~/.local/state/larv-review/`. Keep the folder after the merge: `review-replay` replays a round from the reports its prompt names, and `compress-archives` gzips each file 30 days after it last changed.
|
||||
**Reports.** Run `~/.claude/bin/larv-review reviewer-header <pass>` in the chunk's worktree, and open each prompt to an agent under `~/.claude/agents/` with what it prints; then say in a few lines what the change does and which files it touches. The command makes the chunk's review folder and writes the branch diff and the plan's listing into it. The header names that diff, the reviewer's full report, `<pass>-round-<n>.md`, in the folder, the folders of technical principles and review standards the project's config sets, the files of coding conventions where it lists any, the listing, and for architecture and stability the places too. For a reviewer whose definition starts it without `CLAUDE.md`, the header's last line names the file that holds the project principles and decision titles, which the reviewer reads first. For a relaunch one rung up, add `--rerun`: the report becomes `<pass>-round-<n>-rerun.md`, and the header names the report that asked. Before you answer a 🔴 or 🟡, read its entry: Grep the report for the finding's place, with the lines after it, rather than Read the whole report. rule-hook refuses a reviewer's Edit and MultiEdit, and any Write outside `~/.local/state/larv-review/`. Keep the folder after the merge: `review-replay` replays a round from the reports its prompt names, and `compress-archives` gzips each file 30 days after it last changed.
|
||||
|
||||
**Precedent, then ask** — for the full scan:
|
||||
|
||||
@@ -142,7 +149,7 @@ Launch systems-architect: review the whole project as the release leaves it; the
|
||||
|
||||
### Principles
|
||||
|
||||
Launch one principles-auditor on the trigger in §3, so the project is read once per round. Hand it the goals file's goals, from the header's `Goals and audience:` line, and code health (`~/.claude/CLAUDE.md` → "Shared goal") unless that file voids it, and each file in the config's principles folder (`~/.claude/bin/project-config principles` prints it) whose `Applies to` line the project meets, judged from the README, `git ls-files` and the branch diff. A file without the line applies to every project. Unsure → hand it the file.
|
||||
Launch one principles-auditor on the trigger in §3, so the project is read once per round. Hand it the goals file's goals, from the header's `Goals and audience:` line, and code health (`~/.claude/CLAUDE.md` → "Shared goal") unless that file voids it, and each file in the config's principles folder (`~/.claude/bin/project-config principles` prints it) whose `Applies to` line the project meets, judged from the README, `git ls-files` and the branch diff. A file without the line applies to every project. Unsure → hand it the file. Hand it each file the header's `Coding conventions:` line names too.
|
||||
|
||||
### Comprehension check
|
||||
|
||||
@@ -183,7 +190,7 @@ Launch override-reviewer with each line `rule-hook overrides` prints that no ear
|
||||
|
||||
### Stability and product-owner
|
||||
|
||||
Launch the reviewer with the change — stability-reviewer also with the places per "Comprehension check" → "Places", the commit §2's tests and static analysis last passed on, and what the mutation command printed, with its commit, per §2 → "Mutation tests", product-owner-reviewer with the external surface it touches. Each reports only a defect, a requirement of the plan or the goals the change breaks, a breach of a technical principle, or, for stability-reviewer, a place per "Comprehension check" → "Places"; drop any other finding. Fix along the reviewer's Fix guidance (delete > simplify > modify > add). The defect a persona hits is as often in wording or an upgrade path as in code, so a product-owner fix is as often a message or a doc.
|
||||
Launch the reviewer with the change — stability-reviewer also with the places per "Comprehension check" → "Places", the commit §2's tests and static analysis last passed on, and what the mutation command printed, with its commit, per §2 → "Mutation tests", product-owner-reviewer with the external surface it touches. Each reports only a defect, a requirement of the plan or the goals the change breaks, a breach of a technical principle or of a coding convention, or, for stability-reviewer, a place per "Comprehension check" → "Places"; drop any other finding. Fix along the reviewer's Fix guidance (delete > simplify > modify > add). The defect a persona hits is as often in wording or an upgrade path as in code, so a product-owner fix is as often a message or a doc.
|
||||
|
||||
### Prose
|
||||
|
||||
@@ -195,8 +202,8 @@ Launch prose-reviewer with what the diff touched and every section this review c
|
||||
2. Run the project's test suite locally unless a run at the head, §2's or a stability round's, left it verified green.
|
||||
3. The forge's checks: `chunk-pr merge` waits for them to pass (§5 step 4). A red check is a finding.
|
||||
4. No CI configured → the gate is local tests only; note it in the summary.
|
||||
5. The local tests green → mark the PR ready with `~/.claude/bin/chunk-pr ready '<final title>'`, which sets the title as it marks the PR ready.
|
||||
6. **External auto-reviewer**, when the repo has one — its config file (`.coderabbit.yaml` and the like), or its comments on earlier PRs; none → skip it, say so. Marking the PR ready is what summons it. Wait up to **10 minutes** for its first review, checking about once a minute; nothing by then → note it in the summary and carry on, never waiting twice. Its rounds, §3 → "Round cap". Once it has reviewed, each later return here before its cap, after a fix re-entered per §3, waits up to **5 minutes** for its re-review of the new commit. A fix of its finding ends with the setup change that `~/.claude/CLAUDE.md` → "Working loop", "Change the setup for each reasonable fix an outside reviewer asked for on a PR" asks for.
|
||||
5. The local tests green → where §2 left the pull request unopened, open it with `~/.claude/bin/chunk-pr open '<final title>' '<summary>'` and mark it ready at once with `~/.claude/bin/chunk-pr ready`. Otherwise mark the PR ready with `~/.claude/bin/chunk-pr ready '<final title>'`, which sets the title as it marks the PR ready.
|
||||
6. **External auto-reviewer**, when the repo has one — its config file (`.coderabbit.yaml` and the like), or its comments on earlier PRs; none → skip it, say so. Marking the PR ready summons it, unless it reviewed the draft already. Wait up to **10 minutes** for its first review, checking about once a minute; nothing by then → note it in the summary and carry on, never waiting twice. Its rounds, §3 → "Round cap". Once it has reviewed, each later return here before its cap, after a fix re-entered per §3, waits up to **5 minutes** for its re-review of the new commit. Each of its findings, fixed or declined, ends with the setup change that `~/.claude/CLAUDE.md` → "Working loop", "Change the setup for each finding an outside reviewer raises on a PR, deterministic tools first" asks for.
|
||||
|
||||
## 5. Goal alignment, then merge
|
||||
|
||||
@@ -207,7 +214,7 @@ Launch prose-reviewer with what the diff touched and every section this review c
|
||||
- **A merge conflict.** Resolve it, commit and push. Rerun only the passes whose triggers the resolution's own lines meet (§3), each in a round of its own.
|
||||
- **A paired ruling to run again.** `chunk-pr merge` has merged the default branch in and pushed. Run the ruling at that head, record it, commit and push. Don't return to §4 for it: the next turn waits for the checks at the new head.
|
||||
- **An owed scoring run, or a queue another pull request holds.** Record the run, or wait, as the message says.
|
||||
- **A reviewer's comment**, where the project's config sets `wait-for-approval` (`chunk-pr --help`) and the pull request waits for a human's approval. Answer it in its thread on the forge, and fix what it asks as a finding of the chunk. A fix of it ends with the same setup change (§4 step 6). The wait doesn't hold the queue, so other chunks merge meanwhile.
|
||||
- **A reviewer's comment**, where the project's config sets `wait-for-approval` (`chunk-pr --help`) and the pull request waits for a human's approval. Answer it in its thread on the forge, and fix what it asks as a finding of the chunk. Fixed or declined, it ends with the same setup change (§4 step 6). The wait doesn't hold the queue, so other chunks merge meanwhile.
|
||||
|
||||
A repo whose `AGENTS.md` names another method merges that way with the forge's CLI instead, after it finishes the chunk's items with `todo-item finish` in the branch, and once the pull request's checks pass, `~/.claude/bin/larv-review scoring-run-owed` exits 0 and, where `~/.claude/bin/project-config wait-for-approval` prints `true`, GitHub reports the pull request approved. A repo withholds this in its `AGENTS.md` → leave the PR ready and unmerged, and say which line withheld it.
|
||||
5. Merged → run `~/.claude/bin/chunk-pr clean` in the chunk's worktree, and put a failure it prints in the summary.
|
||||
@@ -215,4 +222,4 @@ Launch prose-reviewer with what the diff touched and every section this review c
|
||||
|
||||
## 6. Wrap up
|
||||
|
||||
Summarize: PR URL and final state, every reviewer's verdict, rounds per pass, passes skipped, principles files left out with why, findings fixed vs answered vs declined vs open — each answer with what settles it, each decline with its reason, a 🟡's with the goal or technical principle it rests on — CI status, rule overrides with their rulings, decisions recorded (file paths), for each fixed outside-reviewer comment, the setup change it led to, or that no setup gap caused it, `todo.md`/`CHANGELOG.md` updated, and any 🔀 escalation left for the user.
|
||||
Summarize: PR URL and final state, every reviewer's verdict, rounds per pass, passes skipped, principles files left out with why, findings fixed vs answered vs declined vs open — each answer with what settles it, each decline with its reason, a 🟡's with the goal or technical principle it rests on — CI status, rule overrides with their rulings, decisions recorded (file paths), whether the pull request opened before the review or after it (§2), for each outside reviewer's finding, the setup change it led to, or that no setup gap caused it, `todo.md`/`CHANGELOG.md` updated, and any 🔀 escalation left for the user.
|
||||
|
||||
@@ -14,6 +14,8 @@ A reviewer reads and reports; it doesn't edit anything. It writes no file but it
|
||||
|
||||
A finding against a technical principle names it and the file in the config's principles folder it lives in. A finding against `quality.md`, in the folder your prompt's `Review standards:` line names, names that file and the rule it breaks.
|
||||
|
||||
Where your prompt has a `Coding conventions:` line, read each file it names beside the principles and the standards: they are the rules of the project's team, and a breach of one counts as a breach of a technical principle. Where one conflicts with a principle or a standard, the team's rule wins, and a finding against a convention names its file.
|
||||
|
||||
## Misread
|
||||
|
||||
Mark a 🔴 or 🟡 `[misread]`, right after its severity mark, where it arose because the implementer misread code that shipped before this change: a wrong belief about what that code does, what a name means or what a contract promises. Don't mark a finding about a defect in the change's own new code. `score-outcomes` counts the marked findings per chunk, as code health's counter-signal (`~/.claude/CLAUDE.md` → "Shared goal").
|
||||
|
||||
@@ -6,7 +6,7 @@
|
||||
|
||||
`Bar = 0.1`
|
||||
|
||||
`Next ID = 442`
|
||||
`Next ID = 443`
|
||||
|
||||
## Items
|
||||
|
||||
@@ -24,9 +24,7 @@
|
||||
| 414 | 0.12.0 | 410 | | **DM the human through the notifier when a human-task issue blocks the epic's next item, and poll until it closes.** | 2 | 2 | 2 | 4 | 3 | 1 by 5 | 1.9 |
|
||||
| 417 | 0.12.0 | 410 | | **Run do-epic end to end against a sandbox epic on a real Jira site with a command of its own, outside `run-tests`.** | 2 | 1 | 1 | 2 | 3 | 1 by 5 | 1.9 |
|
||||
| 440 | 0.12.0 | | | **End the shell that the interrupt test of `mutate-changes` starts within a minute, so a mutation run of this repo never waits on it for ever.** | 1 | 1 | 2 | 2 | 2 | 1 by 4 | 1.7 |
|
||||
| 421 | 0.12.0 | | | **Refuse in rule-hook a Bash or Monitor wait that has no end: a loop without a time or count cap, and a `pgrep -f` or `pkill -f` whose pattern the same command line contains.** | 2 | 2 | 3 | 5 | 3 | 1.5 by 4 | 1.3 |
|
||||
| 439 | 0.12.0 | 410 | | **Have `do-epic <EPIC-KEY>` split each open issue by repo, pick the repo of each issue that no label names one for, asking the human where unclear, and re-rank the epic, before it starts chunks.** | 3 | 2 | 3 | 6 | 5 | 1 by 5 | 1.2 |
|
||||
| 429 | 0.12.0 | | | **Bring nine lessons from a client setup into the principles, the reviewers, larv-review and the project config, and rank a deterministic tool first where an outside reviewer's finding changes the setup.** | 4 | 2 | 3 | 7 | 7 | 1.1 by 5, 1.6 by 5 | 0.9 |
|
||||
| 442 | 0.12.0 | 410 | | **Have `do-epic <EPIC-KEY>` split each open issue by repo, pick the repo of each issue that no label names one for, asking the human where unclear, and re-rank the epic, before it starts chunks.** | 3 | 2 | 3 | 6 | 5 | 1 by 5 | 1.2 |
|
||||
| 310 | 0.12.0 | | | **Compact a waiting worker's session shortly before its prompt cache expires, only when the human has not answered an interrupt by then.** | 3 | 2 | 3 | 6 | 4 | 1.4 by 3 | 0.9 |
|
||||
| 422 | 0.12.0 | 420 | | **Check every 5 minutes whether a tmux window of the loop looks stuck by other signs than a lingering worker, investigate it with a headless claude, and kill only the process the investigation names.** | 3 | 2 | 3 | 6 | 5 | 1.5 by 4 | 0.8 |
|
||||
| 365 | 0.13.0 | | | **Have `score-outcomes` read the finished and dropped items of a plan outside the checkout, from the project repo's history or from Jira's issue changelogs.** | 3 | 2 | 2 | 5 | 4 | 1.6 by 2, 1.1 by 2 | 1.2 |
|
||||
@@ -213,24 +211,7 @@ Today a `mutate-changes` run on this repo can wait for ever: mutmut runs `bin/mu
|
||||
Touches:
|
||||
- `bin/mutate_changes/test_mutate_changes.py`: `test_an_interrupt_reaches_the_tool_before_the_run_kills_it` (small)
|
||||
|
||||
### 421. Refuse in rule-hook a Bash or Monitor wait that has no end: a loop without a time or count cap, and a `pgrep -f` or `pkill -f` whose pattern the same command line contains.
|
||||
|
||||
On 2026-11-18 a worker in the item 402 chunk started `until [ -s /tmp/merge-402.log ] && ! pgrep -f "chunk-pr merg"; do sleep 15; done` in the background. The `pgrep -f` pattern is part of the loop's own command line, so it matched itself and the loop never ended; the worker's `claude -p` waited on it for 95 minutes and its slot started no new chunk (item 420 ends such a worker; item 422 handles other stuck windows). A wait that cannot end is cheaper to refuse before it starts.
|
||||
|
||||
rule-hook refuses a Bash command, or a Monitor call, that starts a wait of either kind. A loop (`until`, `while`, `for`) that sleeps and has neither a time limit (`timeout`, a deadline compared with `date`) nor a bounded count (`for i in $(seq …)`); `~/.claude/bin/wait-for` always passes, since it takes `--timeout`. A `pgrep -f` or `pkill -f` whose pattern text also appears in the command line that holds it, quoted or not, so it can match its own shell. The refusal names which kind it found and says to use `wait-for <file> [<pattern>] --timeout <seconds>`, or a `pgrep -x` on the process name.
|
||||
|
||||
`settings.json` hooks only `Agent|Bash|Edit|Grep|MultiEdit|Read|Skill|Write`, so rule-hook never sees a Monitor call: add `Monitor` to that matcher, and have rule-hook read a Monitor call's command as it reads a Bash one. Claude Code 2.1.314 and later send Monitor-started commands to a PreToolUse hook; a hook's allow and updatedInput are ignored for them, so rule-hook can refuse but not rewrite (docs: code.claude.com/docs/en/hooks.md).
|
||||
|
||||
The test covers each kind refused, a bounded loop that passes, `wait-for` passing, and a `pgrep -f` on a pattern absent from the command passing. The rule's reason goes in rule-hook's rule table beside the other rules.
|
||||
|
||||
Touches:
|
||||
|
||||
- `bin/rule_hook/rules.py`: `RULES` (small)
|
||||
- `bin/rule_hook/endless_wait.py`
|
||||
- `bin/rule_hook/test_rule_hook.py`: `CommandBreaches` (small)
|
||||
- `settings.json`
|
||||
|
||||
### 439. Have `do-epic <EPIC-KEY>` split each open issue by repo, pick the repo of each issue that no label names one for, asking the human where unclear, and re-rank the epic, before it starts chunks.
|
||||
### 442. Have `do-epic <EPIC-KEY>` split each open issue by repo, pick the repo of each issue that no label names one for, asking the human where unclear, and re-rank the epic, before it starts chunks.
|
||||
|
||||
Today `do-epic <EPIC-KEY>` starts only an issue whose label already records its repo, and prints that every other one waits (`bin/do_epic/scheduler.py` → `chunks`). `split.split`, `repo_pick.picked` and `ranking` exist and nothing calls them. Each is a headless claude call on a rung: route it on `repoless-model`'s rung of the shipped ladder. An `Unclear` pick is an interrupt on the terminal of the `do-epic <EPIC-KEY>` the human runs. A chunk that finishes starts the next chunks without planning again, so no window waits on a question.
|
||||
|
||||
@@ -240,33 +221,6 @@ Touches:
|
||||
- `bin/do_epic/planning.py`
|
||||
- `bin/do_epic/test_main.py`
|
||||
|
||||
### 429. Bring nine lessons from a client setup into the principles, the reviewers, larv-review and the project config, and rank a deterministic tool first where an outside reviewer's finding changes the setup.
|
||||
|
||||
Lessons from running this setup in a client's repo, shipped as one chunk. Each part names the gap it closes; none names the client, its code or its reviewers' text.
|
||||
|
||||
1. **Open the pull request after our own review, where CI runs on pushed branches.** Today larv-review §2 opens a draft first. A forge's auto-reviewer reviews drafts and human reviewers see them, so in a client's chunk about six outside findings landed that our passes would have caught. Nothing in larv-review needs a pull request before the gate: `reviewer-header` prints `PR: none open at the pushed head`, and round counts read commit titles. Push early so CI runs; run `chunk-pr open` once every §3 pass is done and §2's tests, static analysis and mutation tests pass; mark it ready at once. Where CI runs only on pull requests, keep the draft-first order. Decide which from the repo's CI config, and say in the summary which order the chunk took.
|
||||
2. **Rules for tests on a shared environment**, in the "Tests and tooling" bullet under "Compose, do not entangle", one BANNED/GOOD pair each: assert only on records the test created and can name, never on a count or the first row; never change state the test doesn't own; pass in any order and beside a second copy of itself running at the same time; a helper registers its teardown before it creates anything, keyed by a value it made itself, and the teardown deletes only what it can name; a helper that saves checks what was saved, never the status code alone.
|
||||
3. **"Make invalid states unrepresentable" gets an example about function inputs.** Its only example is a database time type, so in a client's chunk nobody connected it to a test helper that validated its caller's input, over four review rounds. BANNED: a helper that takes a token and a message, and checks that the message holds the token. GOOD: the helper makes the token and builds the message. Add: "When a review finds a second edge case in a check, change the signature so the input can't occur."
|
||||
4. **stability-reviewer checks a change that stores a value differently**, in "Data Integrity & Persistence": where a change escapes, converts or grows a stored value, the longest value it can now write must fit the column, and every search, filter or comparison on the column must still find what users type. In a client's chunk, escaping text into a TEXT column lowered its overflow limit fivefold, and a LIKE search stopped matching apostrophes; stability missed both.
|
||||
5. **A `conventions` setting in the project config**: an optional list of paths, in the other settings' path syntax, such as `checkout:CONVENTIONS.md`. `reviewer-header` prints them, every reviewer reads them beside the principles and standards, and the team's rule wins where they conflict. A missing file fails as an empty principles folder does. Today a team's conventions reach reviewers only by hand.
|
||||
6. **larv-review §2 files an item to add a mutation tool** when `mutate-changes` prints its line naming changed files no tool covers, or refreshes the item an earlier chunk filed: the language's mutation tool, pinned to a version that supports the project's language version. In a client's PHP repo without one, three findings were surviving mutants a tool would have reported before review.
|
||||
7. **The principle "Never mock a service your own team runs."** Test the seam to it against its real build, in a harness that runs the real stack; mock only a third party that can't be run locally in a reasonable way. The rule binds the test that covers the seam: a unit test of the caller's own logic may still use a fake, as "Use real collaborators or fakes" allows.
|
||||
8. **The principle "Don't loosen a type when refactoring"**, under "Validate data and build DTOs as early as possible.", with one BANNED/GOOD pair: a function that returned a concrete type keeps returning it when its implementation changes, never `object`, `array`, `mixed` or `any`; introduce a DTO or value object instead.
|
||||
9. **Reflect on every outside reviewer's finding, deterministic tools first.** `CLAUDE.md` → "Working loop" → "Change the setup for each reasonable fix an outside reviewer asked for on a PR" already asks why our review missed it, but ranks reviewer agents and larv-review with the hooks and tools, and covers only fixes. Make it cover every finding an outside reviewer raises, and rank the places: 1. a deterministic tool that would have caught it, such as a rule-hook rule, a gate check, a linter setting or `mutate-changes`; 2. the technical principles or review standards; 3. anything else: the reviewers' agents, `larv-review`'s text, or the project's own settings, principles folder or `AGENTS.md`.
|
||||
|
||||
Touches:
|
||||
- `CLAUDE.md`: `## Working loop` (small)
|
||||
- `skills/larv-review/SKILL.md`: `## 2. Ship the branch`, `## 4. Gate`, `### Principles` (small)
|
||||
- `bin/chunk_pr/main.py`: `opened` (small)
|
||||
- `bin/chunk_pr/test_chunk_pr.py`
|
||||
- `principles/technical-principles.md`: `Compose, do not entangle`, `Make invalid states unrepresentable.`, `Validate data and build DTOs as early as possible.`, `Most, if not all, code should have automated tests, and each test earns its keep.`
|
||||
- `agents/stability-reviewer.md`: `### 7. Data Integrity & Persistence` (small), `### 11. Tests` (small)
|
||||
- `bin/project_config/settings.py`: `SETTINGS`
|
||||
- `bin/project_config/test_project_config.py`
|
||||
- `bin/larv_review/reviewer_header.py`
|
||||
- `bin/larv_review/test_larv_review.py`
|
||||
- `README.md`: `## Install` (small)
|
||||
|
||||
### 310. Compact a waiting worker's session shortly before its prompt cache expires, only when the human has not answered an interrupt by then.
|
||||
|
||||
281 worker resumes after the 1-hour cache expired rewrote a whole context, $379 of the $9,154 measured from 2026-09-30 to 2026-11-11 (4.1%). A compaction while the cache is warm reads the context at a twentieth of the input price and leaves about 20k tokens to rewrite later.
|
||||
|
||||
Reference in New Issue
Block a user