|
|
|
@@ -22,12 +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. When the pull request opens depends on what starts the repo's CI, which its CI config says, as a workflow file's `on:` does:
|
|
|
|
|
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:
|
|
|
|
|
|
|
|
|
|
- **CI runs on pushed branches** → 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: a forge's auto-reviewer reviews a draft, and human reviewers see it, so an early draft draws findings our passes would have caught.
|
|
|
|
|
- **CI runs only on pull requests, 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.
|
|
|
|
|
- **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.
|
|
|
|
|
|
|
|
|
|
Say in the summary which order the chunk took. No remote → review locally and say so in the summary.
|
|
|
|
|
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.
|
|
|
|
|
|
|
|
|
@@ -37,7 +37,7 @@ Say in the summary which order the chunk took. No remote → review locally and
|
|
|
|
|
|
|
|
|
|
**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 names code among those 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 files the line named. Where an earlier chunk filed the item, add this chunk's files to its detail instead. A file that holds no code, such as Markdown or a config file, files no item.
|
|
|
|
|
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
|
|
|
|
|
|
|
|
|
@@ -149,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, and each file the header's `Coding conventions:` line names. 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
|
|
|
|
|
|
|
|
|
@@ -190,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
|
|
|
|
|
|
|
|
|
@@ -203,7 +203,7 @@ Launch prose-reviewer with what the diff touched and every section this review c
|
|
|
|
|
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 → 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 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. 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.
|
|
|
|
|
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
|
|
|
|
|
|
|
|
|
@@ -214,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. It ends with the same setup change (§4 step 6), fixed or declined. 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.
|
|
|
|
|