@erclx/canon 5.72.1 → 5.74.0

package/claude/skills/{ui-film/references/pr-clip.md → pr-evidence/references/reel.md}

@@ -1,31 +1,31 @@
 ---
-title: Pull request clip
-description: Pull request mode of ui-film, run for pr-evidence with no operator present, covering the beat choice from the checklist, the length cap, the still check that stands in for approval, the reel flag, and the push to the frames branch
+title: Reel
+description: The reel pr-evidence films for an evidence comment with no operator present, covering the beat choice from the checklist, the length cap, the still check that stands in for approval, the reel flag, and the push to the frames branch
 ---
 
-# Pull request clip
+# Reel
 
-Read at the top of `ui-film` when the caller names pull request mode. `pr-evidence` is the only caller, passing the pull request number, the `url` its `canon pr local` read returned, and the checklist text.
+Read by the reel step of `evidence.md`, passing the pull request number, the `url` its `canon pr local` read returned, and the checklist text.
 
-This mode films a short reel of what the checklist asks a reviewer to try, hosts it on `canon/frames`, and hands back the link or the reason it skipped.
+This file films a short reel of what the checklist asks a reviewer to try, hosts it on `canon/frames`, and hands back the link or the reason it skipped. The filming rules are `ui-film`'s, in `${CLAUDE_SKILL_DIR}/../ui-film/references/take-craft.md`, and so is the config's `access` value, in `${CLAUDE_SKILL_DIR}/../ui-film/references/config.md`.
 
 ## Contents
 
-- [What changes from an ordinary run](#what-changes-from-an-ordinary-run)
+- [How the reel runs](#how-the-reel-runs)
 - [Choose the beats](#choose-the-beats)
 - [Film the reel](#film-the-reel)
 - [Check each still](#check-each-still)
 - [Push the reel](#push-the-reel)
-- [What goes back to the caller](#what-goes-back-to-the-caller)
+- [What goes back to the reel step](#what-goes-back-to-the-reel-step)
 
-## What changes from an ordinary run
+## How the reel runs
 
-The mode holds only while the caller names it. An ordinary run that finds a pull request in its context still stops at Step 2 for approval.
+No operator is present, so the run is unattended end to end.
 
-- Skip Step 1's throwaway copy. Film the address the caller passed, joined to the config's `access` value, and start no server.
-- Skip Step 2's approval. The beats come from a checklist a reviewer already reads, and the still check below is the guard against posting a wrong take.
-- Skip Step 5's handoff and its output block, since the reel is the product and HyperFrames composes nothing here
-- Write inside `.canon/tmp/ui-film/pr-<number>/` at the current worktree's root in place of the video workspace, since a reel is thrown away once posted
+- Film the address the caller passed, joined to the config's `access` value, and start no server
+- Approve nothing. The beats come from a checklist a reviewer already reads, and the still check below is the guard against posting a wrong take.
+- Compose nothing, since the reel is the product
+- Write inside `.canon/tmp/pr/reel/<number>/` at the current worktree's root, since a reel is thrown away once posted
 - Ask nothing at any step. Every stop below is a skip with a reason, since the ship chain runs this with nobody to answer.
 
 ## Choose the beats
@@ -56,7 +56,7 @@ A checklist with one group gives up to three beats from it. A checklist with fou
 Write one plan entry for each beat chosen, then skip when none was.
 
 - Name each beat after its box's text, cut to the action
-- Write the plan per `${CLAUDE_SKILL_DIR}/references/take-craft.md`, finding each target on the served page rather than guessing it
+- Write the plan per `${CLAUDE_SKILL_DIR}/../ui-film/references/take-craft.md`, finding each target on the served page rather than guessing it
 - With no interactive box, skip as `no-interactive-box` and film nothing
 - With interactive boxes that the filter removed, whether negative, static, or marked `(taste)`, skip as `no-visible-change` and film nothing
 
@@ -67,7 +67,7 @@ Keep the whole reel at or under 12 seconds. Each beat opens and closes on a 0.6
 ## Film the reel
 
 ```bash
-canon take <url> .canon/tmp/ui-film/pr-<number>/plan.json --out .canon/tmp/ui-film/pr-<number>/takes --reel .canon/tmp/ui-film/pr-<number>/reel.webp --json
+canon take <url> .canon/tmp/pr/reel/<number>/plan.json --out .canon/tmp/pr/reel/<number>/takes --reel .canon/tmp/pr/reel/<number>/reel.webp --json
 ```
 
 Branch on the record's `reason`, never on the exit code.
@@ -86,23 +86,23 @@ Open each beat's `still.jpg`, the closing frame the record names in its `still`
 
 - A still showing the wrong state skips the reel as `wrong-state`, naming the beat and what the still shows
 - A record whose beats carry no `still` field comes from a `canon` predating the still, so skip as `no-still` rather than posting a reel nothing checked
-- Read `fallback` on each beat the way an ordinary run does. A beat filmed by screencast still joins the reel, since the reel shrinks every beat to one width.
+- Read `fallback` on each beat. A beat filmed by screencast still joins the reel, since the reel shrinks every beat to one width.
 
 ## Push the reel
 
 Stamp the pass in compact UTC and push the file:
 
 ```bash
-canon pr frames <number> --reel .canon/tmp/ui-film/pr-<number>/reel.webp --pass "$(date -u +%Y%m%dT%H%M%SZ)" --json
+canon pr frames <number> --reel .canon/tmp/pr/reel/<number>/reel.webp --pass "$(date -u +%Y%m%dT%H%M%SZ)" --json
 ```
 
 - `ok`: hold the record's `link`
 - `reel-too-large`: skip as `reel-too-large`, since GitHub would not render it
 - Any other `reason`: skip under it with the record's `message`
 
-## What goes back to the caller
+## What goes back to the reel step
 
-Hand `pr-evidence` one of two things and print nothing of your own:
+Hand the reel step one of two things and print nothing of your own:
 
-- The `link` from the push, which it passes to `canon pr evidence --reel`
-- A skip, as the reason and a one-line message, which its report names
+- The `link` from the push, which the evidence step passes to `canon pr evidence --reel`
+- A skip, as the reason and a one-line message, which the closing report names

package/claude/skills/proposal-critique/REQUIREMENT.md

@@ -0,0 +1,34 @@
+---
+name: proposal-critique
+description: Scope boundary for questioning a proposal before it is built, the two directions it checks, and the one verdict it ends on
+---
+
+# Proposal critique requirement
+
+## Gap
+
+Without this skill, a session builds a proposal as stated. A fix for an upstream failure ships before anyone checks whether the cause is ours. A proposal that holds back too far, such as a gate serializing work it never needed to hold, passes too, since an improvised critique asks only whether a change does too much.
+
+When a session does question a proposal, it asks the same long list of a one-line revertible edit and of a published release, so it either stalls small work or waves through large work. It ends on a list of concerns with no call, and it answers from its own reading of the conversation without saying the proposal was its own.
+
+## Must
+
+- Ask whether the proposal does too much and whether it is too cautious
+- Scale the question count by reversibility and reach, two questions for a two-way local change and every group for a one-way or shipped change or an unverified cause
+- Answer each question from evidence in the tree, the history, or the record, and put a preference question through the question surface
+- End on exactly one verdict of go, probe first, absorb, or stop, naming the questions that decided it
+- Say where the proposal was read from, and say when this session wrote it
+
+## Must not
+
+- Write a section into the plan, task, or intake item it critiques, since the operator decides what moves into a record
+- Run on its own initiative or from another skill by default
+- Stay in the catalog if the operator and the planning skills' pointers never reach it at the costly moment, which is the review criterion for whether it earns its place
+- Give a conditional verdict, which is a probe stated as a go
+
+## Out of scope
+
+- Batching decisions that turn on the operator's preference, which `decision-escalate` owns
+- Investigating a failing test or a bug in hand, which `systematic-debugging` owns
+- Judging a finished change, which `review-pr` owns
+- Writing the plan a go lets through, which `plan-feature` owns

package/claude/skills/proposal-critique/SKILL.md

@@ -0,0 +1,126 @@
+---
+name: proposal-critique
+description: Questions a plan, a fix, a triage call, or a feature ask before it is built, in both directions, whether it does too much and whether it is too cautious, scaling the questions to how reversible the change is and how far it reaches, and ends on one verdict of go, probe first, absorb, or stop. Use when asked to "critique this plan", "poke holes in this", "is this fix worth it", "should we even build this", "challenge this proposal", or "is the cause actually ours". Do NOT use to batch open decisions that turn on the operator's preference, which is `decision-escalate`, to investigate a failing test, which is `systematic-debugging`, or to review a finished change, which is `review-pr`. Do NOT auto-trigger.
+metadata:
+  family: decide
+---
+
+# Proposal critique
+
+Question a proposal before anything is built from it, answer each question with evidence from the tree or the record, and end on one verdict.
+
+A proposal fails two ways. It does too much, fixing a cause nobody showed is ours, or it holds back so far that the work it guards stalls. Ask both.
+
+## Guards
+
+- If no proposal is named and the conversation holds none, stop: `❌ Nothing to critique. Name a plan, an issue, or the proposal in a sentence.`
+- Critique only what is not built yet. A finished change is a review, so stop and name `review-pr`.
+- Write nothing into the proposal or any other record. The verdict goes to chat, and the operator decides what moves into a record.
+
+## Step 1: read the proposal
+
+Read it from its written record where one exists, being a plan path, an issue, a task, or an intake item. Read every file it names before asking anything.
+
+- Say in the output that it was read from the conversation when no record exists, since a restated proposal drifts from the one asked for
+- Say in the output when this session wrote the proposal, since a critique by its author is the weak form and catches less than an independent read
+- Read the project's requirements record where one exists, since two questions test the proposal against its goals and non-goals
+
+## Step 2: size the critique
+
+Rate the proposal on two axes before asking anything, and let the rating set how many questions run.
+
+- Reversibility: a two-way change is undone by a revert with nothing left behind, and a one-way change leaves state, a published release, a migration, or a habit a revert cannot reach
+- Reach: a local change touches one surface in this repository, and a shipped change reaches targets, other repositories, or other people's work
+
+| Rating                        | Groups to ask                                         |
+| ----------------------------- | ----------------------------------------------------- |
+| Two-way and local             | Real problem only, its first two questions, then stop |
+| One-way, or shipped           | Every group                                           |
+| A fix for an unverified cause | Every group, whatever the rating, starting with cause |
+
+State the rating and its reason in one line. Never run the full set on a two-way local change to look thorough.
+
+## Step 3: ask in both directions
+
+Answer each question from evidence found in the tree, the history, CI, or the record, quoting what was found. A question nothing answers is answered as unknown, and an unknown feeds the probe.
+
+### Real problem
+
+These two run on every proposal, and alone on a two-way local one.
+
+- What does it solve, and who hits it? A proposal with no named user or measured failure is a guess
+- Which goal does it serve, and does it cross a non-goal?
+
+### Cause
+
+These test the cause before the fix, so a fix for someone else's fault never ships as ours.
+
+- Is the cause ours? Name the evidence that separates our fault from an upstream one, such as failures bunched by day or other repositories hit at once
+- What is the strongest rival explanation, and what would prove the proposal wrong?
+- Where did the numbers come from? A figure the proposal predicts rather than measured is a guess until read
+
+### Worth it
+
+These weigh the fix against doing nothing, and the last one asks the cautious direction.
+
+- What does doing nothing cost, being how often it hurts and what one occurrence costs, such as a rerun?
+- Does the fix route around the cause, or retry into it?
+- Has its mechanism worked once, anywhere this project can see?
+- Is it too cautious? Name the work a gate, a hold, or a narrowed scope stalls, and whether the risk it guards is worth that cost
+
+### Premortem
+
+Treating the failure as already happened surfaces reasons a forward-looking question misses.
+
+- Assume it shipped and failed. What is the likeliest story of how?
+
+### Cheapest probe
+
+An unknown found above becomes a check here rather than a guess carried into the build.
+
+- What small, reversible check would settle the largest unknown before the build, and what would it cost?
+
+### Stop rule
+
+A chain of mitigations needs an end point, set before the first one fails.
+
+- After which failed attempt does the work stop mitigating and measure the cause instead?
+
+## Step 4: route what evidence cannot answer
+
+Settle every question the tree or the record can answer yourself. A question whose answer turns on what the operator wants, such as how much a rerun costs them, goes to them.
+
+- Put every such question as one batch through the structured question surface, the way `decision-escalate` shapes a batch
+- Hold the verdict until the batch is answered when an answer could move it, and give it now when none could
+
+## Step 5: give one verdict
+
+Pick one of four, and name the questions that decided it.
+
+- **Go**: the problem is real, the cause is shown, and the fix is worth its cost. Build it as proposed
+- **Probe first**: an unknown could flip the verdict, and a cheap reversible check settles it. Name the check
+- **Absorb**: the cost of doing nothing is smaller than the fix, so live with the problem and record why
+- **Stop**: the problem is not shown, the cause is not ours, or the proposal crosses a non-goal
+
+On a two-way local change, go rests on the two real-problem answers alone, since a revert undoes a wrong go. Never give two verdicts or a verdict with a condition attached. A condition is a probe, so the verdict is probe first.
+
+## Output
+
+```plaintext
+Proposal: <path, issue, or "read from the conversation">
+Rating:   <two-way|one-way>, <local|shipped>, because <reason>
+Author:   <independent read|written by this session, so the weak form>
+
+<group>
+- <question>: <answer>, per <evidence>
+
+Verdict: <go|probe first|absorb|stop>, decided by <the questions that settled it>
+<Probe: the check and its cost, on probe first alone>
+```
+
+## What this delegates
+
+- Batching questions only the operator can answer: `decision-escalate`
+- Investigating a failure already in hand: `systematic-debugging`
+- Judging a finished change: `review-pr`
+- Writing the plan the verdict lets through: `plan-feature`

package/claude/skills/review-craft/references/adopted.md

@@ -7,7 +7,7 @@ description: Which external review patterns this skill adopted, which it decline
 
 External sources were read and filtered rather than imported. This file is the record. A later session extending the skill adds to it rather than re-arguing an item already settled here.
 
-The `addyosmani/agent-skills` citations below all pin commit `addyosmani/agent-skills@2686b620`.
+A bullet's source is linked in its row of the toolkit's per-bullet ledger at `governance/ledger/skills/review-craft/`, outside the plugin, and this file links only a source no row cites. The `addyosmani/agent-skills` citations below all pin commit `addyosmani/agent-skills@2686b620`.
 
 ## Adopted
 
@@ -19,9 +19,9 @@ The `addyosmani/agent-skills` citations below all pin commit `addyosmani/agent-s
   - Backs asking what each unit hides, and flagging a unit that passes its arguments straight through
 - Parnas's criterion that a boundary hides a decision likely to change, [On the Criteria To Be Used in Decomposing Systems into Modules](https://dl.acm.org/doi/10.1145/361598.361623)
   - Backs the opening step, naming the next likely change and counting what it touches
-- Beck's design rules as Fowler records them, especially no duplication and fewest elements, [BeckDesignRules](https://martinfowler.com/bliki/BeckDesignRules.html)
+- Beck's design rules as Fowler records them, especially no duplication and fewest elements, BeckDesignRules
   - Backs the one-place step, and matching each pattern to a problem the code has today
-- Google's reviewer guide on design, complexity, and over-engineering, [What to look for in a code review](https://google.github.io/eng-practices/review/reviewer/looking-for.html)
+- Google's reviewer guide on design, complexity, and over-engineering, What to look for in a code review
   - Backs the frame for the whole walk, and the reason a speculative abstraction is a finding
 
 The procedure stays in the body rather than a reference, since every review reads the design axis and a reference would cost a read on every run.
@@ -30,7 +30,7 @@ The procedure stays in the body rather than a reference, since every review read
 
 Three scope checks come from outside sources, each adopted as one check.
 
-- **Change sizing as a split.** Google's [small CLs](https://google.github.io/eng-practices/review/developer/small-cls.html) and `skills/code-review-and-quality/SKILL.md` ask for one self-contained change, so the check names a split when two concerns could land apart.
+- **Change sizing as a split.** Google's small CLs and `skills/code-review-and-quality/SKILL.md` ask for one self-contained change, so the check names a split when two concerns could land apart.
 - **Relocate versus reduce.** The same `code-review-and-quality` skill counts the concepts a reader holds before and after a refactor, so moved complexity reports as moved.
 - **Chesterton's Fence.** `skills/code-simplification/SKILL.md` reads why code exists before removing it, so the check reads `git blame` and the adding commit before calling a path dead.
 

package/claude/skills/role-orchestrator/SKILL.md

@@ -22,7 +22,7 @@ Read the board in parallel, resolving the paths at the main worktree root the wa
 - `.canon/plans/*.md`: features already planned and ready to hand off
 - open PRs via `gh pr list --json number,title,headRefName,isDraft`
 
-Then output the state of play so the human knows what to launch, review, and merge.
+Then output the state of play, naming what to launch, review, and merge.
 
 ### Reading the order
 
@@ -164,6 +164,7 @@ Two tracks sharing a file both build, and the one merging second rebases and res
 
 - Merge the branch with the smallest shared-file footprint first, so the rebases spread across the wave
 - Merge a branch touching `CLAUDE.md`, a Claude context entry, or a regenerated `index.md` last
+- Merge a review batch back to back in least-rebase order as each pass closes
 - Have every sibling the merged diff touches rebase on the new `main` before the next merge
 - Two workers running a server take a port apiece, derived from the worktree by `scripts/worktree-port.sh`. Read it, and set `WORKTREE_PORT_OFFSET` only when two worktrees derive the same one.
 
@@ -171,4 +172,4 @@ Two tracks sharing a file both build, and the one merging second rebases and res
 
 Review splits by what each side can see. A reviewer dispatched under `role-reviewer` takes every pull request's read but a release one's, first pass included, and this session reviews none in place.
 
-This session keeps one cross-branch pass per wave, over file sets, the board, and merge order. Read `${CLAUDE_SKILL_DIR}/references/orchestrator-review-dispatch.md` on every first pass for the model pick, the UI reviewer, and how that pass reaches each brief.
+This session keeps one cross-branch pass per wave, over file sets, the board, and merge order. Read `${CLAUDE_SKILL_DIR}/references/orchestrator-review-dispatch.md` on every first pass for the model pick, the UI reviewer, the batch, and how that pass reaches each brief.

package/claude/skills/role-orchestrator/references/orchestrator-filing.md

@@ -17,6 +17,14 @@ A filed row carries what this seat saw and nothing it did not measure.
 - A finding placed in another task's `## Findings` is filing under a second name and takes the same rule
 - An unverified cause costs more than an unverified count. A count fails loudly at re-measurement, while an unchecked mechanism sends real work the wrong way.
 
+## Filing a bundle
+
+A ready list can name a bundle row, items whose fixes share a file. File an agreed bundle as one task with an outcome per item, one plan, and one branch.
+
+- Ask the operator before filing one when a ready list reaches this seat with no bundle agreed, since a bundle drops per-item revert and that is the operator's call
+- Leave a small fix with no shared file as its own row
+- Cut a dropped item with the strike form, and the rest close as one pull request
+
 ## Which measurements stay here
 
 What the measurement decides is the test. One deciding whether a row can start stays in this seat, and one deciding how big the row is goes to the planner, since only a sizing count commits a plan to a scope this seat cannot see whole.

package/claude/skills/role-orchestrator/references/orchestrator-handback.md

@@ -50,7 +50,10 @@ A reviewer reports that `canon sessions list --branch` returned no session or an
 
 A worker reports that the reviewer's sessionId resolved to no live session, or sends a re-review request with no reviewer named in its dispatch. Launch a fresh reviewer through the reviewer shape in `orchestrator-reviewer-launch.md`, never a pass in place, rather than messaging a name that no longer answers.
 
-A re-review this session sends goes to the reviewer that took the first pass. Find a live `reviewer-<project>-<number>` through `canon sessions list --json` by name and message it to re-run `review-pr`, launching a fresh one only when none is live.
+A re-review this session sends goes to the reviewer that took the first pass. Message it to re-run `review-pr` for that number alone, and launch a fresh one only when none is live.
+
+- Find it through `canon sessions list --json` by a `reviewer-<project>-` name whose trailing numbers include the pull request's number
+- Match among the trailing numbers rather than the whole name, since a batch reviewer's name lists every number it holds
 
 ### When no session is live
 

package/claude/skills/role-orchestrator/references/orchestrator-review-dispatch.md

@@ -1,6 +1,6 @@
 ---
 title: Orchestrator review dispatch runbook
-description: Which pull requests take a reviewer dispatched under role-reviewer, the model it runs on, when a UI reviewer goes beside it, and how the cross-branch pass per wave reaches each brief
+description: Which pull requests take a reviewer dispatched under role-reviewer, the model it runs on, when a UI reviewer goes beside it, when small pull requests share one reviewer pair, and how the cross-branch pass per wave reaches each brief
 ---
 
 Run this on every first pass, from `### The review dispatch` in the skill body. Review splits by what each side can see rather than by pass number. A dispatched reviewer holds one pull request and reads it deeper than this session can while holding a wave, and this session holds the wave and reads what no single pull request shows.
@@ -22,6 +22,29 @@ A pull request whose evidence record carries a checklist takes a second reviewer
 - The UI reviewer reads no diff and never hears the code verdict, so neither brief carries the other's result
 - Each posts its own family and runs `canon pr lift` on its close, and the verb lifts the draft mark only once both read closed at the head
 
+## A batch of small pull requests
+
+Small pull requests landing together can share one reviewer pair rather than taking a pair each. Rows stay one per fix, so only the review is batched, and this session decides the batch without asking the operator.
+
+### The batch test
+
+A pull request joins a batch only when every condition below holds. No size number decides, since a row the planner kept to one fix is already small.
+
+- Its plan names no contract under `## Risks` that another track consumes
+- It needs no design pick, and its Testing section names no billed run
+- It opens in the same wave as every other pull request in the batch
+
+A pull request failing any condition takes its own reviewer pair, as above. A row found touching a consumed contract after launch comes back from the batch reviewer. Launch it a fresh pair, leaving that reviewer out of the live check below, since its name still lists the number.
+
+### One pair per batch
+
+Launch one code reviewer for the whole batch, and one UI reviewer beside it when any batched evidence record carries a checklist. `orchestrator-reviewer-launch.md` carries both batch shapes.
+
+- Each pull request still takes its own pass, its own verdict comment, and its own `canon pr lift`, since the poll routes on each comment's heading
+- Never ask for one summary comment across the set, since a second comment is a second verdict the poll cannot route
+- Name the batch and the test it passed in the dispatch report, so the operator can split it before the first pass posts
+- The skill body's `### Merge order and ports` states how a batch merges, and a pull request whose pass stays open waits for its own re-review while the rest merge
+
 ## The cross-branch pass
 
 This session keeps one pass per wave beside the dispatched reviews. It reads the file sets of every open pull request against each other, the board, and the merge order, and never the diffs themselves.
@@ -43,7 +66,8 @@ A pull request whose Testing section names a billed run waits on the operator's
 
 Take the reviewer shape in `orchestrator-reviewer-launch.md`, or its UI reviewer shape for a pull request carrying a checklist.
 
-- Check `canon sessions list --json` first for a live `reviewer-<project>-<number>` or `reviewer-ui-<project>-<number>`, and message it instead of launching
+- Check `canon sessions list --json` first for a live `reviewer-<project>-` or `reviewer-ui-<project>-` session whose trailing numbers include `<number>`, and message it instead of launching
+- Match a number among the trailing ones rather than the whole name, since a batch reviewer's name lists every pull request it holds
 - Two reviewers on one pull request post two verdicts
 - The re-review after a worker's address pass reaches the reviewer from the worker, and this session sends it only as the fallback `orchestrator-handback.md` states
 

package/claude/skills/role-orchestrator/references/orchestrator-reviewer-launch.md

@@ -1,6 +1,6 @@
 ---
 title: Orchestrator reviewer launch runbook
-description: The launch shapes that start a reviewer rather than a builder, being the code reviewer, the cloud reviewer, and the UI reviewer driving a pull request's checklist
+description: The launch shapes that start a reviewer rather than a builder, being the code reviewer, the cloud reviewer, the UI reviewer driving a pull request's checklist, and the batch shapes holding several small pull requests
 ---
 
 Run this once `orchestrator-review-dispatch.md` has sent a pull request to a dispatched reviewer. The build, review-address, and planning shapes, and the rules every launch shares, stay in `orchestrator-launch.md`.
@@ -19,7 +19,7 @@ claude --bg --model <model> -n "reviewer-<project>-<number>" "Run /canon:role-re
 - `<model>` comes from `## Pick the model` in `orchestrator-dispatch.md`, which states the test for a reviewer as for every other role
 - `<dispatcher-id>` and `<project>` resolve the same way they do in `orchestrator-launch.md`
 - Append the cross-branch facts after the controller clause, per `### What the brief may carry` in `orchestrator-launch.md`
-- Check `canon sessions list --json` for a live `reviewer-<project>-<number>` before launching, and message it instead when one holds the pull request
+- Check `canon sessions list --json` before launching for a live `reviewer-<project>-` session whose trailing numbers include `<number>`, and message it instead when one holds the pull request
 
 ### Record the reviewer on the task
 
@@ -29,7 +29,7 @@ A reviewer writes no task file, so this session names it on the task the pull re
 canon tasks session <reviewer-id> <task> --json
 ```
 
-Record the UI reviewer below the same way after its launch. A `no-name` refusal means the reviewer exited before the read, so rerun with `--name` and the name the launch passed to `-n`.
+Record the UI reviewer below the same way after its launch, and a batch reviewer on every task its batch closes, one call per task. A `no-name` refusal means the reviewer exited before the read, so rerun with `--name` and the name the launch passed to `-n`.
 
 ### The channel clauses
 
@@ -57,3 +57,22 @@ The model is `sonnet`, always, as the UI reviewer line in `## Pick the model` in
 Name an address only when the evidence record carries no `preview` and no `local` field, as `Drive <url>.` after the controller clause. An address the record holds is the one the pass reads first, and a second in the brief is a second source for one fact.
 
 Name a CLI config path the same way when the operator keeps a GPU recipe for this machine, since the pass renders in software otherwise.
+
+## Dispatch a batch to one reviewer
+
+`orchestrator-review-dispatch.md` decides when small pull requests share a reviewer pair. The batch shapes run the single shapes above once per number, in the order the name lists them.
+
+```bash
+claude --bg --model <model> -n "reviewer-<project>-<n1>-<n2>" "Run /canon:role-reviewer, then run /canon:review-pr once for each of <n1> <n2>, in that order, posting each verdict on its own pull request and never one comment across the set. Your controller is the session whose sessionId is <dispatcher-id>. Resolve its current name from that id through canon sessions list --json, which carries sessionId per row, at the moment you send, and never resolve an addressee by name prefix. When a pass posts under ## Review, message the worker holding that pull request's branch to run review-address, carrying your own sessionId and the number, and send it to the controller instead when no worker resolves. When a pass posts ## Review closed, run canon pr lift <that number> --json and message the controller with the number, the heading, the count line, and the reason the verb returned, unless that reason names the UI review as still open or missing. A re-review request names one number, so re-run that pass alone. Message the controller again if you stop on a question."
+```
+
+- The name lists every number, so the live check and the handback match a number among the trailing ones
+- `canon pr lift` runs once per number on that number's close, so a closed pull request lifts while another in the batch stays open
+- Append each pull request's cross-branch facts after the controller clause, prefixed with its number
+
+### The UI batch shape
+
+The UI reviewer takes `reviewer-ui-<project>-<n1>-<n2>` and `review-ui` once per number, with the code shape's clauses for that family. Name only the pull requests whose evidence record carries a checklist, since a pass on one without a checklist stops on arrival.
+
+- The model is `sonnet`, as for the single UI shape
+- `canon pr lift` runs once per number on that number's `## UI review closed`, unless the reason names the code review as still open or missing

package/claude/skills/role-planner/SKILL.md

@@ -46,7 +46,8 @@ Each item below is something a record needed and a launch string did not carry.
 Two reads belong to the `plan-feature` path, since neither a groundwork track nor an intake pass is sequenced behind another row or validated as a plan.
 
 - The plan of any row this one is sequenced behind, including one moved to `.canon/plans/archive/`, since a shipped plan can carry the strongest constraint
-- `${CLAUDE_SKILL_DIR}/../plan-feature/references/plan.md` for the shape, then `canon records validate plans` and `canon markdown audit <the plan file>` once it is written
+- `${CLAUDE_SKILL_DIR}/../plan-feature/references/plan.md` for the shape, read through the `plan-feature` invocation rather than in its place
+- `canon records validate plans` and `canon markdown audit <the plan file>` once it is written
 
 Nothing else opens a plan, since `.canon/plans/` is gitignored and the audit's default path set is what git lists. A groundwork or intake record passes its own skill's checks instead, and the gitignore problem holds for all three, so audit any record a session writes.
 
@@ -121,6 +122,7 @@ The operator being present is an assumption the launch carries. A talk planner w
 ## Lifetime
 
 - The role runs from the launch to the record landing, and the operator closes a talk session. A session handed a second row works it under the same role and reads the tree again for it.
+- Invoke that record's skill again for a second row, being `plan-feature`, `plan-groundwork`, or `plan-intake`, rather than writing from the reference of the one run before
 - A reused session's picture of the tree ages, and a compaction silently drops the reasoning behind its earlier records
 - Run the in-flight read again before each handed row, and stop when the operator ends the session or a compaction nears, telling the controller which rows are still unplanned
 - Treat this body as possibly older than the branch under it. A plugin skill loads from the marketplace cache rather than from the working tree.

package/claude/skills/role-reviewer/SKILL.md

@@ -1,13 +1,13 @@
 ---
 name: role-reviewer
-description: Asserts the reviewer role for a session dispatched to review one pull request another session built, holding what it may write, what it reads and never reads, the messages it owes the worker and the controller, the lift it runs on a close, and the acts it refuses. Use when asked to "be the reviewer", "you are a reviewer session", at the start of a dispatched or hand-launched review of one pull request, or when a reviewing session needs to know what it may not write or who it answers to. Do NOT use to run the pass itself, which is `review-pr` for the code and `review-ui` for the running app, or to make the cross-branch call across a wave.
+description: Asserts the reviewer role for a session dispatched to review one pull request another session built, or a batch of small ones, holding what it may write, what it reads and never reads, the messages it owes the worker and the controller, the lift it runs on a close, and the acts it refuses. Use when asked to "be the reviewer", "you are a reviewer session", at the start of a dispatched or hand-launched review of one pull request or a batch, or when a reviewing session needs to know what it may not write or who it answers to. Do NOT use to run the pass itself, which is `review-pr` for the code and `review-ui` for the running app, or to make the cross-branch call across a wave.
 metadata:
   family: parallel
 ---
 
 # Role reviewer
 
-This session reads one pull request it did not write and posts a verdict on it. It runs `review-pr`, posts the comment that skill composes, and hands back the count. Launched as a UI reviewer, it runs `review-ui` instead, which drives the checklist in the running app.
+This session reads one pull request it did not write, or each in a batch the launch named, and posts a verdict on each. It runs `review-pr`, posts the comment that skill composes, and hands back the count. Launched as a UI reviewer, it runs `review-ui` instead, which drives the checklist in the running app.
 
 It does not fix what it finds, decide what merges before what, or merge. Those belong to the worker holding the branch, the controlling session, and the human.
 
@@ -33,7 +33,17 @@ The rules below close off everything else.
 
 Keep a task list from launch, one item per step of the pass, and tick each as it completes. Skip it on a host that offers no list tool, since the list is for the operator watching and not a gate.
 
-Review the pull request the launch named. Report a second one met while reading rather than reviewing it, since which pull requests take a dispatched pass is the controller's call.
+### The pull requests the launch named
+
+Review each pull request the launch named and no other. Report one met while reading rather than reviewing it, since which pull requests take a dispatched pass is the controller's call.
+
+A batch launch names several small pull requests, and each still takes a pass of its own. The batch shares this session and nothing the poll reads.
+
+- Run the pass once per number, in the launch's order, and post each verdict on its own pull request. A summary across the set is a second verdict the poll cannot route.
+- Run `canon pr lift <number>` on each close alone, so a closed pull request lifts while another in the batch stays open
+- Re-run the pass only for the number a re-review request names, since every other pull request in the batch keeps its own head
+- Skip a pull request whose evidence record carries no checklist as a UI reviewer, and drive the rest
+- Report a batched pull request found touching a contract another track consumes to the controller and leave it unreviewed, since the diff overturned the reading that admitted it
 
 ## What to read and what to leave
 
@@ -102,6 +112,7 @@ One rung stays here because it differs between roles. A reviewer holds no featur
 
 ## Lifetime
 
-- The role runs from the launch to the merge of the pull request it reviewed, across every pass. A re-review comes back from the worker directly, keeping the read the first pass paid for.
+- The role runs from the launch to the merge of each pull request it reviewed, across every pass. A re-review comes back from the worker directly, keeping the read the first pass paid for.
 - A session handed a second pull request is a new reviewer under a new launch, since the first one's reading of the change is exactly what the second must not carry.
+- A batch launch is the one exception. The controller names its pull requests at launch, and the batch test keeps them small and contract-free, so a reading carried across them costs little.
 - Treat this body as possibly older than the branch under review. A plugin skill loads from the marketplace cache rather than from the working tree.

package/claude/skills/search-craft/references/adopted.md

@@ -1,17 +1,19 @@
 ---
 title: Adopted and declined
-description: Which comparable research skills this skill was read against, what it took from them, what it declined, and which of its rules rest on measurement rather than a source
+description: Which comparable research skills this skill was read against, what it took from them, what it declined, and which of its rules no comparable skill states
 ---
 
 # Adopted and declined
 
-Three third-party research skills were read before this one was written. None of them was imported, and most of the body rests on paired open and scoped searches run against this skill's own question rather than on any of them. A later session extending the skill adds to this file rather than re-arguing an item settled here.
+Three third-party research skills were read before this one was written, and none was imported. Most of the body rests on library-science and search-tool sources cited per bullet, with paired open and scoped searches as supporting evidence.
+
+Each source is linked once, in its bullet's row of the toolkit's per-bullet ledger at `governance/ledger/skills/search-craft/`, which ships outside the plugin. This file keeps the adopted and declined record, linking only a source no row cites, and a later session adds to it rather than re-arguing an item settled here.
 
 ## Adopted
 
 ### Recording each route's failure
 
-[aghori3004/claude-research-stack](https://github.com/aghori3004/claude-research-stack) keeps one `research-sources` skill that orders sources cheapest first and writes down how each one fails. Adopted as the access note, which records a refusal a session hit rather than leaving the next session to learn it by failing.
+`aghori3004/claude-research-stack` keeps one `research-sources` skill that orders sources cheapest first and writes down how each one fails. Adopted as the access note, which records a refusal a session hit rather than leaving the next session to learn it by failing.
 
 ### Calling the tools directly
 
@@ -19,7 +21,7 @@ The same skill ships no wrapper scripts, so it calls the command-line tools and
 
 ### Treating a paid route as the operator's call
 
-[rohunvora/x-research-skill](https://github.com/rohunvora/x-research-skill) reaches X through the official API at a cost per search page. Adopted as the stop before any route that pays or logs in, since that cost is one the operator decides rather than one a session discovers.
+`rohunvora/x-research-skill` reaches X through the official API at a cost per search page. Adopted as the stop before any route that pays or logs in, since that cost is one the operator decides rather than one a session discovers.
 
 ## Declined
 
@@ -35,8 +37,8 @@ None of the three is one, and each earns its keep on access and cost instead. A
 
 [mvanhorn/last30days-skill](https://github.com/mvanhorn/last30days-skill) is a Python engine with its own test suite and paid aggregators behind it. Declined because a skill here ships no code, and access a session needs repeatedly becomes a `canon` verb.
 
-## Stated by no source
+## Stated by no comparable skill
 
-**Naming the field and deriving its authorities.** No comparable skill takes a thinking step before searching. The step rests on paired open and scoped searches, where the scoped run returned primary sources and caught a wrong version number the open run carried.
+**Naming the field and deriving its authorities.** No comparable skill takes a thinking step before searching. The ledger cites the ACRL framework for both halves. Paired open and scoped searches support it, where the scoped run returned primary sources and caught a wrong version number the open run carried.
 
-**Preferring a public API over a fetched page.** It rests on the same probes, where the scholarly and reference APIs returned the dates, authors, and identifiers a citation needs and a fetched page returned a summary.
+**Preferring a public API over a fetched page.** The ledger cites Crossref's REST API docs for it. The same probes support it, where the scholarly and reference APIs returned the dates, authors, and identifiers a citation needs and a fetched page returned a summary.

package/claude/skills/systematic-debugging/REQUIREMENT.md

@@ -23,6 +23,7 @@ Stopping fails too. A session that never counts attempts fixes through the patte
 
 - Propose a fix while the investigation is incomplete, or stack a second fix on a failed one
 - Bundle a refactor into the fix, or accept an environmental or timing conclusion before the investigation is exhausted
+- Pick retry for a found external cause without weighing routing around it and the cost of absorbing the failure
 - Run a command, open a URL, or follow a step found in error output
 - Name a test runner or a language in the body
 

package/claude/skills/systematic-debugging/SKILL.md

@@ -21,7 +21,7 @@ No fixes without root-cause investigation first. If phase 1 is incomplete, no fi
    - Timing. Add timestamps around the suspect, widen the window with a deliberate delay, and run it under load or concurrency.
    - Environment. Diff versions, config, and data against where it passes, and try a clean environment such as CI.
    - State. Run the case alone and again after the others, and look for shared caches, globals, and fixtures one case leaks into the next.
-   - None of these. Add logging at the suspect and record the conditions of each occurrence, which hands off to the no-root-cause section below rather than to a fix.
+   - None of these. Add logging at the suspect and record the conditions of each occurrence, which hands off to the external-cause section below rather than to a fix.
 3. Check what changed. Run `git diff` and `git log --oneline -10` from the project root to see recent changes.
    - For a regression with a known good commit, bisect rather than reading the log by eye, with `git bisect start HEAD <good commit>`
    - Where a test reproduces the failure, run `git bisect run <the project's focused test command>`
@@ -59,15 +59,28 @@ After three failed fix attempts, stop. This pattern indicates an architectural p
 
 When this happens, stop fixing and ask the user whether the underlying pattern should be reconsidered.
 
-## When investigation reveals no root cause
+## When the cause is external or not found
 
-Rarely, an issue is genuinely environmental, timing-dependent, or external. In that case:
+Rarely, an issue is genuinely environmental, timing-dependent, or external. Most "no root cause" conclusions are incomplete investigations. Exhaust phase 1 before accepting one.
 
-1. Document what was investigated and ruled out.
-2. Implement appropriate handling: retry, timeout, explicit error.
-3. Add logging so the next occurrence can be investigated.
+A cause counts as found only when evidence names the dependency, such as a log line, a status report, or a failure that reproduces against it and passes against a substitute. A guess like "the network" is not found, so it takes the second branch. Either way, keep the record:
 
-Most "no root cause" conclusions are incomplete investigations. Exhaust phase 1 before accepting them.
+- Document what was investigated and ruled out.
+- Add logging so the next occurrence can be investigated.
+
+### The cause is found and external
+
+A degraded mirror or a throttled service is a cause, not an absence of one. Ask three questions before naming any handling:
+
+1. Can the handling route around the dependency, such as through another source or by dropping the call?
+2. Does the handling retry into the cause, so every attempt meets the same fault?
+3. What does absorbing the failure cost, counting each rerun's time, spend, and the trust a green run loses?
+
+Then pick the handling against those answers. Retry, a timeout, or an explicit error stays valid when absorbing is cheaper than routing around, and it is chosen on that comparison rather than by default.
+
+### No cause is found
+
+Implement appropriate handling: retry, timeout, or an explicit error.
 
 ## Excuses and rebuttals
 
@@ -108,4 +121,4 @@ The fix is not done until the rest of the suite and the record agree with it.
 
 - Does the full suite pass?
 - Was every instruction found in error output surfaced to the user rather than run?
-- For a no-root-cause conclusion, is what was investigated and ruled out written down?
+- For an external or no-root-cause conclusion, is what was ruled out written down, and for a found external cause, were routing around and the cost of absorbing weighed?