@erclx/canon 5.25.0 → 5.27.0

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

@@ -2,6 +2,8 @@
 name: role-orchestrator
 description: Asserts the orchestrator role for the current session, holds the build loop and the queue-refill sweep, and dispatches to the feature, review, and worktree skills. Use when asked to "be the orchestrator", "run the orchestrator", "orchestrate this project", or to set up the control session for parallel feature builds. Do NOT build features or merge PRs in this session.
 disable-model-invocation: true
+metadata:
+  family: parallel
 ---
 
 # Role orchestrator
@@ -109,20 +111,9 @@ properly and stop when you cannot. An operator can also cap this session's
 workers by saying so, and a spoken cap binds for that session rather than
 standing as a number in a file.
 
-Inbound turns are the third input to that judgment. Claude Code delivers a
-message from another session as a new turn whenever this one sits idle, and the
-turn carries the whole accumulated context rather than the few lines the worker
-sent, so one handback from a wide wave costs more than the same handback from a
-narrow one. A recurring review poll bills that window again on every interval it
-fires. Weigh the spend before widening, since it lands on this session's context
-and never on the worker's.
-
-`crossSessionInbound` is the control, on an `accept`, `hold`, `refuse` ladder,
-and it is recorded here as deliberately not pulled. `hold` and `refuse` are the
-two values that bound the cost, and both break the handback this loop runs on,
-since a held message reaches nobody until a later `accept` applies and a refused
-one is dropped outright. `accept` bounds nothing. Read the ladder before turning
-concurrency up rather than after, and leave it unset.
+Read `${CLAUDE_SKILL_DIR}/references/orchestrator-inbound.md` before widening a
+wave, for what each inbound turn costs this session and why the one control over
+it stays unset.
 
 Serialize any track that touches a shared wiring seam with another in flight, and
 serialize one whose sets are disjoint when a stated reason still puts it behind

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

@@ -9,6 +9,14 @@ Run this once `orchestrator-dispatch.md` has cleared a row and picked cloud for
 
 The shape needs a `SessionStart` hook in the repository that, on the VM alone, copies the plugin skills into `.claude/skills/` and puts `canon` on the path. A repository without one cannot take this shape, so fall back to a local worker there. Where the hook exists, the launch prompt calls `/auto-ship` with no `canon:` prefix, since the copied skills list as project skills.
 
+## Contents
+
+- [Check the row is unclaimed](#check-the-row-is-unclaimed)
+- [The prompt](#the-prompt)
+- [The create](#the-create)
+- [Recognize the pull request](#recognize-the-pull-request)
+- [Dispatch a review to a cloud reviewer](#dispatch-a-review-to-a-cloud-reviewer)
+
 ## Check the row is unclaimed
 
 A cloud worker never appears in `canon sessions list` and never pushes the derived branch, since the cloud assigns it a `claude/` branch of its own. So the roster and the refs read clear on a row a cloud worker is already building. Run the local check in `orchestrator-dispatch.md` anyway, since a local worker on the same row still collides, then read the two places a cloud worker does show:

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

@@ -5,6 +5,19 @@ description: The plan-answer gate, the collision check before a self-dispatch, t
 
 Run this at loop step 4, for a `## Run now` row whose plan is verified, in place of handing the worktree to a human. The disjointness gate below is where that row's file set is tested against every track in flight.
 
+## Contents
+
+- [Derive the candidate](#derive-the-candidate)
+- [Check the plan waits on nobody](#check-the-plan-waits-on-nobody)
+- [Check the branch is unclaimed](#check-the-branch-is-unclaimed)
+- [Hold what this pass already launched](#hold-what-this-pass-already-launched)
+- [Check the file sets are disjoint](#check-the-file-sets-are-disjoint)
+- [Pick the model](#pick-the-model)
+- [Pick local or cloud](#pick-local-or-cloud)
+- [Dispatch](#dispatch)
+- [Fall back to the human](#fall-back-to-the-human)
+- [Stop the loop](#stop-the-loop)
+
 ## Derive the candidate
 
 Run `canon tasks plan-branch <plan> --json` against the row's plan file and read `branch`, `type`, `slug`, and `conforms` off the record.

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

@@ -13,7 +13,7 @@ Read this at loop step 6, once a review pass has posted anything owed and the se
 - Name the skill for the reader to run rather than writing an invocation, which arrives as text
 - Read the pull request's own draft flag rather than the state a worker reports, and report what the read returned and when rather than the state alone. `canon docs pr-reads` states why a reported field can lag and say nothing about it. The flag settles the question only once the worker's chain has run its undo, and nothing marks that moment, so a read taken between the pull request opening and that call sees a genuinely ready pull request about to become a draft and has told an operator the opposite of what the worker had said.
 
-A re-review goes back to the reviewer that took the first pass. Find a live `reviewer-<project>-<number>` for that pull request through `canon sessions list --json` by name and message it to re-run `review-pr`. When none is live, launch a fresh reviewer through the reviewer shape in `orchestrator-launch.md` or review in place, under the same trigger `orchestrator-review-dispatch.md` states, rather than messaging a name that no longer answers.
+A re-review goes back to the reviewer that took the first pass. Find a live `reviewer-<project>-<number>` for that pull request through `canon sessions list --json` by name and message it to re-run `review-pr`. When none is live, launch a fresh reviewer through the reviewer shape in `orchestrator-reviewer-launch.md` or review in place, under the same trigger `orchestrator-review-dispatch.md` states, rather than messaging a name that no longer answers.
 
 A session is reachable when it appears in a live listing, which reads what each session registered on disk rather than probing it, and a message carries plain text and no authority. When no live session holds the branch, report the invocation for the human, naming the branch, the pull request, and the skill to run, then stop. Retrying or waiting leaves the loop believing it is open while nothing acts on it.
 

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

@@ -0,0 +1,23 @@
+---
+title: Inbound turn cost
+description: What each message from another session costs the orchestrator's context, why a wide wave spends against it, and why the crossSessionInbound control stays unset
+---
+
+# What an inbound turn costs
+
+Part of `role-orchestrator`'s `## Parallelism`. The session reads this file before widening a wave, since collision is what binds the track count and this is what it costs.
+
+Inbound turns are the third input to that judgment. Claude Code delivers a
+message from another session as a new turn whenever this one sits idle, and the
+turn carries the whole accumulated context rather than the few lines the worker
+sent, so one handback from a wide wave costs more than the same handback from a
+narrow one. A recurring review poll bills that window again on every interval it
+fires. Weigh the spend before widening, since it lands on this session's context
+and never on the worker's.
+
+`crossSessionInbound` is the control, on an `accept`, `hold`, `refuse` ladder,
+and it is recorded here as deliberately not pulled. `hold` and `refuse` are the
+two values that bound the cost, and both break the handback this loop runs on,
+since a held message reaches nobody until a later `accept` applies and a refused
+one is dropped outright. `accept` bounds nothing. Read the ladder before turning
+concurrency up rather than after, and leave it unset.

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

@@ -1,9 +1,9 @@
 ---
 title: Orchestrator launch runbook
-description: The launch every dispatch kind shares, being the build, cloud build, review-address, planning, reviewer, and UI reviewer templates, the session name and controller id each carries, why the command sits at position zero, and what the brief may carry
+description: The launch every dispatch kind shares, being the build, cloud build, review-address, and planning templates, the session name and controller id each carries, why the command sits at position zero, and what the brief may carry
 ---
 
-Run this once `orchestrator-dispatch.md` has cleared a row, or from its planning, review-address, or reviewer shape below when that runbook's checks do not bind. The model each template names comes from `## Pick the model` in that runbook.
+Run this once `orchestrator-dispatch.md` has cleared a row, or from its planning or review-address shape below when that runbook's checks do not bind. The model each template names comes from `## Pick the model` in that runbook.
 
 ## Dispatch
 
@@ -34,7 +34,7 @@ Put a command whose skill carries `disable-model-invocation: true` at position z
 
 Never depend on the `Skill` tool route for a flagged skill. A refusal there tells the session not to replicate the workflow by other means, so a refused worker stops with a clean worktree, which is the correct outcome. The refusal is sticky inside a session, so recovery belongs to whoever writes the next prompt: re-dispatch onto the same branch with the build template above.
 
-The review-address, planning, and reviewer shapes below depend on no expansion at all. None of `role-worker`, `review-address`, `role-planner`, `plan-feature`, `role-reviewer`, or `review-pr` carries the flag, so all three correctly keep their leading word regardless of the delimiter or the position it sits at.
+The review-address and planning shapes below, and the reviewer shapes in `orchestrator-reviewer-launch.md`, depend on no expansion at all. None of `role-worker`, `review-address`, `role-planner`, `plan-feature`, `role-reviewer`, or `review-pr` carries the flag, so all three correctly keep their leading word regardless of the delimiter or the position it sits at.
 
 The same rule reaches a human relay. Hand an operator one message carrying one command at position zero, since two chained blocks pasted as separate messages can land as one, where everything after the first command's name reads as that command's argument and the second never fires.
 
@@ -89,34 +89,6 @@ What a planning dispatch owes instead is the reverse reading, because the plan i
 
 One row per dispatch. A session reused across a batch pays the context load once and ages its picture of the tree while it works, which is what puts the in-flight read on the task rather than on the batch, and one that compacts mid-batch loses the reasoning behind its earlier plans with nothing reporting it. Cap a reused session where the saving is worth it and say what the cap was.
 
-## Dispatch to review a pull request
+## Dispatch a reviewer
 
-`review-pr` is a single pass rather than a role, so a launch naming it alone reaches no `role-reviewer` and owes no message. Reach the role first on this launch, the way the planning shape reaches `role-planner`. `orchestrator-review-dispatch.md` decides whether a pull request takes this shape at all.
-
-No branch and no worktree are entered here. The reviewer reads the pull request at the head `review-pr` resolves and writes the comment and its body file alone.
-
-```bash
-claude --bg --model <model> -n "reviewer-<project>-<number>" "Run /canon:role-reviewer, then /canon:review-pr <number>. 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. Message it when the pass posts, carrying the heading and the count line, and message it again if you stop on a question."
-```
-
-`<number>` is the pull request's number, and the brief pins no head, since `review-pr` resolves the head itself and stamps the range it covered in its marker. `<dispatcher-id>`, `<model>`, and `<project>` resolve the same way they do above. Append the cross-branch facts after the controller clause, per `### What the brief may carry`.
-
-Check `canon sessions list --json` for a live `reviewer-<project>-<number>` before launching, and message that session instead when one holds the pull request.
-
-## Dispatch a review to a cloud reviewer
-
-Read `${CLAUDE_SKILL_DIR}/references/orchestrator-cloud-launch.md` when the operator picked cloud for a code review. Its prompt opens with `/role-reviewer`, carries the cross-branch facts, and makes the posted review the announcement.
-
-## Dispatch to drive a pull request's checklist
-
-`review-ui` is the second pass `role-reviewer` may run, so this shape reaches the role first the way the code reviewer's does. `orchestrator-review-dispatch.md` decides whether a pull request takes it, and it runs beside the code reviewer rather than after it.
-
-```bash
-claude --bg --model sonnet -n "reviewer-ui-<project>-<number>" "Run /canon:role-reviewer, then /canon:review-ui <number>. 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. Message it when the pass posts, carrying the heading and the count line, and message it again if you stop on a question."
-```
-
-The model is fixed at Sonnet rather than taken from `## Pick the model`. A cheaper tier was measured on the same checklist and passed real defects as clean while judging the taste boxes it was told to leave, at a higher cost per run.
-
-Name an address in the brief only when the evidence record carries no `preview` and no `local` field, as `Drive <url>.` after the controller clause. An address the record already 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. Carry nothing else: the UI reviewer reads no diff and no code verdict, so the cross-branch facts the code brief carries stay out of this one.
-
-`<number>`, `<dispatcher-id>`, and `<project>` resolve the same way they do above. The prefix reads `reviewer-ui-` so a roster read for `reviewer-<project>-<number>` never matches the UI reviewer, and the two passes on one pull request stay two sessions.
+Read `${CLAUDE_SKILL_DIR}/references/orchestrator-reviewer-launch.md` when `orchestrator-review-dispatch.md` sends a pull request to a dispatched reviewer, for the code, cloud, and UI reviewer shapes.

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

@@ -13,7 +13,7 @@ Start the poll on an open pull request and stop it when the last one merges with
 
 A dispatch no longer starts it. The script reads pull requests and a building worker has none, so every interval between the launch and the push is a fixed cost returning nothing, measured as five consecutive runs reporting no movement across roughly fifteen minutes while one worker built. What replaces it is the worker announcing its own pull request the moment it opens one, per the `role-worker` skill that session loads, which covers exactly the transition the poll cannot observe.
 
-The dispatched-worker condition survives as a fallback rather than as a trigger. Start the poll against any dispatch still out after thirty minutes with no announcement, which is past the upper end of the ten to thirty minutes a row here takes. The announcement is newer than the narrowing it justifies, so a silent failure would otherwise leave a finished worker unnoticed the way one already sat idle for eighteen minutes, and the fallback keeps the cover a straight narrowing would have removed. `${CLAUDE_SKILL_DIR}/scripts/watch.ts` covers the same window at a lower cost, since it reads the roster alongside the pull request list and reports a worker that vanished as well as one that finished.
+The dispatched-worker condition survives as a fallback rather than as a trigger. Start the poll against any dispatch still out after thirty minutes with no announcement, which is past the upper end of the ten to thirty minutes a row here takes. The announcement is newer than the narrowing it justifies, so a silent failure would otherwise leave a finished worker unnoticed the way one already sat idle for eighteen minutes, and the fallback keeps the cover a straight narrowing would have removed. `${CLAUDE_SKILL_DIR}/scripts/watch.ts` covers the same window at a lower cost, since it reads the roster alongside the pull request list and reports a worker that vanished as well as one that finished. Read `${CLAUDE_SKILL_DIR}/references/orchestrator-watch.md` before starting it, since it carries the stall alarm and the notification each alarm line owes the operator.
 
 A session holding a recurring-prompt scheduler starts the loop itself on that condition and cancels it on the same test, without waiting for the operator. Both halves belong to whoever holds the loop, since a session that can start one can stop one, and a runbook stating only the start leaves the always-on failure unaddressed on the side that causes it.
 
@@ -80,23 +80,3 @@ The pass now carries its own record instead. `review-pr` writes the commit it re
 Read `source` on the record before trusting a `SEEN` on a thread whose newest pass is old. `marker` is the read-time record. `fallback` is a pass posted before the mechanism shipped, or a target whose CLI predates the verb, and it carries the defect above unchanged, so a `SEEN` under it is worth one read of the pull's reviews before it is believed. `none` is a thread carrying no pass at all.
 
 The other side of that comparison used to lag as well, which made the two errors compound rather than cancel. The pull read's `head.sha` answers from the pull request object and that object trails the branch ref by up to a minute after a push, reporting nothing about the trail, so a pass stamped ahead of the commit it read was compared against a head stamped behind the commit that exists. The head now comes from `canon pr head`, which resolves the tip through `git ls-remote` and reports which commit each source names, and the object's head stays behind it as the fallback for a target whose CLI predates the verb. Both halves of the comparison now answer about a commit somebody named rather than one GitHub stamped, which is what lets a `SEEN` be read as covered.
-
-## The watch beside it
-
-`${CLAUDE_SKILL_DIR}/scripts/watch.ts` is a long-running loop rather than a scheduled prompt, started as `bun <path>`. It reads the open pull request list and the session roster together every sixty seconds and prints one line per new pull request, per worker whose name, branch, or status changed, and per worker that dropped out of the roster. Start it in the background and read what it emits. It writes nothing.
-
-Coverage is what it buys over the poll. A worker that finishes goes idle and a worker that crashes disappears, so a trigger reading pull requests alone stays silent through the second, and the roster read is the half `poll.ts` cannot make. It ran a full afternoon over four concurrent workers and caught every transition, while the three-minute poll it replaced reported no movement five times in a row.
-
-It classifies nothing and routes nothing. A line it prints says a pull request opened or a worker moved, and the routing block above is still what decides whether a review follows, so the two compose rather than replace each other.
-
-Every session in the repository holding a branch other than the base one counts as a worker, whoever launched it. The prototype matched the `orchestrator-` prefix instead, which reads a dispatched worker and misses every hand-launched one. A failed read of either source reports itself on a `watch:` line and leaves the baseline untouched, since reading an empty result as current state would report every worker gone on the pass after.
-
-## The stall alarm
-
-`watch.ts` prints `WORKER-STOPPED <name> <branch> <dwell>s` once a `waiting` row crosses `STALL_THRESHOLD_S`, and `WORKER-UNMEASURABLE <name> <branch>` for one whose record carries neither timestamp the dwell falls back to. Both are prints, not alerts, so the operator learns of one only when a session already reading the loop's output relays it further. The toolkit ships no notification verb, since the surface a stall reaches the operator through is a session tool rather than a command a shell loop can call.
-
-The two lines carry different confidence and the push has to say so rather than treat them as one signal. `WORKER-STOPPED` fires only once the dwell has already crossed the threshold, so it reports a wait already confirmed long. `WORKER-UNMEASURABLE` has no dwell to threshold on, so it fires on the first pass that meets a `waiting` row carrying neither stamp, whether that row has sat five seconds or fifty minutes.
-
-On meeting either line, push a notification to the operator through whatever notification surface the client offers, `PushNotification` in this repository's client and one example among the surfaces a different client exposes. Name the worker, the branch, which of the two lines fired, and the dwell where `WORKER-STOPPED` carries one, and send it once per stall the same way `watch.ts` prints it once, rather than repeating it on every interval the row stays stopped.
-
-The bound stays open. The alarm reaches the operator only through the controller's own read, so a controller mid-turn does not see the line for as long as the turn runs, and a controller that is itself stopped never does. Neither case closes here, since the watch loop and the notification surface both live inside the same session that has to be free to act on either.

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

@@ -32,7 +32,7 @@ Hand what it finds to each reviewer as facts in the brief, per `### What the bri
 
 ## Launching the reviewer
 
-Take the reviewer shape in `orchestrator-launch.md`, or its UI reviewer shape for the UI trigger. Check `canon sessions list --json` for a live `reviewer-<project>-<number>`, or `reviewer-ui-<project>-<number>`, first and message it instead of launching a second, since two reviewers on one pull request post two verdicts. The re-review after a worker's address pass goes back the same way, per `orchestrator-handback.md`.
+Take the reviewer shape in `orchestrator-reviewer-launch.md`, or its UI reviewer shape for the UI trigger. Check `canon sessions list --json` for a live `reviewer-<project>-<number>`, or `reviewer-ui-<project>-<number>`, first and message it instead of launching a second, since two reviewers on one pull request post two verdicts. The re-review after a worker's address pass goes back the same way, per `orchestrator-handback.md`.
 
 ## Local or cloud
 

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

@@ -0,0 +1,38 @@
+---
+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
+---
+
+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`.
+
+## Dispatch to review a pull request
+
+`review-pr` is a single pass rather than a role, so a launch naming it alone reaches no `role-reviewer` and owes no message. Reach the role first on this launch, the way the planning shape in `orchestrator-launch.md` reaches `role-planner`. `orchestrator-review-dispatch.md` decides whether a pull request takes this shape at all.
+
+No branch and no worktree are entered here. The reviewer reads the pull request at the head `review-pr` resolves and writes the comment and its body file alone.
+
+```bash
+claude --bg --model <model> -n "reviewer-<project>-<number>" "Run /canon:role-reviewer, then /canon:review-pr <number>. 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. Message it when the pass posts, carrying the heading and the count line, and message it again if you stop on a question."
+```
+
+`<number>` is the pull request's number, and the brief pins no head, since `review-pr` resolves the head itself and stamps the range it covered in its marker. `<dispatcher-id>`, `<model>`, 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 that runbook.
+
+Check `canon sessions list --json` for a live `reviewer-<project>-<number>` before launching, and message that session instead when one holds the pull request.
+
+## Dispatch a review to a cloud reviewer
+
+Read `${CLAUDE_SKILL_DIR}/references/orchestrator-cloud-launch.md` when the operator picked cloud for a code review. Its prompt opens with `/role-reviewer`, carries the cross-branch facts, and makes the posted review the announcement.
+
+## Dispatch to drive a pull request's checklist
+
+`review-ui` is the second pass `role-reviewer` may run, so this shape reaches the role first the way the code reviewer's does. `orchestrator-review-dispatch.md` decides whether a pull request takes it, and it runs beside the code reviewer rather than after it.
+
+```bash
+claude --bg --model sonnet -n "reviewer-ui-<project>-<number>" "Run /canon:role-reviewer, then /canon:review-ui <number>. 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. Message it when the pass posts, carrying the heading and the count line, and message it again if you stop on a question."
+```
+
+The model is fixed at Sonnet rather than taken from `## Pick the model` in `orchestrator-dispatch.md`. A cheaper tier was measured on the same checklist and passed real defects as clean while judging the taste boxes it was told to leave, at a higher cost per run.
+
+Name an address in the brief only when the evidence record carries no `preview` and no `local` field, as `Drive <url>.` after the controller clause. An address the record already 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. Carry nothing else: the UI reviewer reads no diff and no code verdict, so the cross-branch facts the code brief carries stay out of this one.
+
+`<number>`, `<dispatcher-id>`, and `<project>` resolve the same way they do in `orchestrator-launch.md`. The prefix reads `reviewer-ui-` so a roster read for `reviewer-<project>-<number>` never matches the UI reviewer, and the two passes on one pull request stay two sessions.

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

@@ -0,0 +1,26 @@
+---
+title: Orchestrator watch runbook
+description: The long-running watch that reads pull requests and the session roster together, and the stall alarm it prints for a worker left waiting
+---
+
+Run the watch beside the poll when the dispatch fallback in `orchestrator-poll.md` is in force, or whenever a worker's exit has to be seen as well as its pull request. The poll classifies and routes, and this loop only reports.
+
+## The watch beside it
+
+`${CLAUDE_SKILL_DIR}/scripts/watch.ts` is a long-running loop rather than a scheduled prompt, started as `bun <path>`. It reads the open pull request list and the session roster together every sixty seconds and prints one line per new pull request, per worker whose name, branch, or status changed, and per worker that dropped out of the roster. Start it in the background and read what it emits. It writes nothing.
+
+Coverage is what it buys over the poll. A worker that finishes goes idle and a worker that crashes disappears, so a trigger reading pull requests alone stays silent through the second, and the roster read is the half `poll.ts` cannot make. It ran a full afternoon over four concurrent workers and caught every transition, while the three-minute poll it replaced reported no movement five times in a row.
+
+It classifies nothing and routes nothing. A line it prints says a pull request opened or a worker moved, and the routing block in `orchestrator-poll.md` is still what decides whether a review follows, so the two compose rather than replace each other.
+
+Every session in the repository holding a branch other than the base one counts as a worker, whoever launched it. The prototype matched the `orchestrator-` prefix instead, which reads a dispatched worker and misses every hand-launched one. A failed read of either source reports itself on a `watch:` line and leaves the baseline untouched, since reading an empty result as current state would report every worker gone on the pass after.
+
+## The stall alarm
+
+`watch.ts` prints `WORKER-STOPPED <name> <branch> <dwell>s` once a `waiting` row crosses `STALL_THRESHOLD_S`, and `WORKER-UNMEASURABLE <name> <branch>` for one whose record carries neither timestamp the dwell falls back to. Both are prints, not alerts, so the operator learns of one only when a session already reading the loop's output relays it further. The toolkit ships no notification verb, since the surface a stall reaches the operator through is a session tool rather than a command a shell loop can call.
+
+The two lines carry different confidence and the push has to say so rather than treat them as one signal. `WORKER-STOPPED` fires only once the dwell has already crossed the threshold, so it reports a wait already confirmed long. `WORKER-UNMEASURABLE` has no dwell to threshold on, so it fires on the first pass that meets a `waiting` row carrying neither stamp, whether that row has sat five seconds or fifty minutes.
+
+On meeting either line, push a notification to the operator through whatever notification surface the client offers, `PushNotification` in this repository's client and one example among the surfaces a different client exposes. Name the worker, the branch, which of the two lines fired, and the dwell where `WORKER-STOPPED` carries one, and send it once per stall the same way `watch.ts` prints it once, rather than repeating it on every interval the row stays stopped.
+
+The bound stays open. The alarm reaches the operator only through the controller's own read, so a controller mid-turn does not see the line for as long as the turn runs, and a controller that is itself stopped never does. Neither case closes here, since the watch loop and the notification surface both live inside the same session that has to be free to act on either.

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

@@ -1,6 +1,8 @@
 ---
 name: role-planner
 description: Asserts the planner role for a session writing one plan, groundwork track, or intake pass under one row, holding what it reads before deciding, what may be written and where, how to read what is already in flight, and what it hands back. Use when asked to "be the planner", "you are a planner session", at the start of a dispatched or hand-launched planning, groundwork, or intake run, or when a planning session needs to know what it may not write. Do NOT use to write the record itself, which is `plan-feature`, `plan-groundwork`, or `plan-intake`, to make the cross-feature merge call, or to implement.
+metadata:
+  family: parallel
 ---
 
 # Role planner

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

@@ -57,7 +57,7 @@ a tree the pull request never changed.
 - Restate a boundary `role-orchestrator`, `role-worker`, or `role-planner` states about itself
 - Report progress through the channel, which rebuilds on the sender's side the poll the announcement exists to retire
 - Post outside `review-pr` and `review-ui`, since every reader of the review headings breaks at once when one pass invents its own
-- Be a skill nothing invokes but its author typing the name. `orchestrator-launch.md` names it on the reviewer launch the way it names `role-planner` on a planning one, so a stretch where only a typed invocation reaches it is the signal that the role never took.
+- Be a skill nothing invokes but its author typing the name. `orchestrator-reviewer-launch.md` names it on the reviewer launch the way `orchestrator-launch.md` names `role-planner` on a planning one, so a stretch where only a typed invocation reaches it is the signal that the role never took.
 
 ## Guards
 

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

@@ -1,6 +1,8 @@
 ---
 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 one message it owes on posting, 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, to review local changes, which is `review-branch`, or to make the cross-branch call across a wave.
+metadata:
+  family: parallel
 ---
 
 # Role reviewer

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

@@ -1,6 +1,8 @@
 ---
 name: role-worker
 description: Asserts the worker role for a building session, holding the boundary set, the lifetime, and the two channel obligations a session owes whoever dispatched it. Use when asked to "be the worker", "you are a worker session", at the start of a dispatched or hand-launched build, or when a building session needs to know what it may not write. Do NOT use to plan the next feature, to run the independent review pass, or to merge.
+metadata:
+  family: parallel
 ---
 
 # Role worker

package/claude/skills/search-craft/REQUIREMENT.md

@@ -18,7 +18,7 @@ The miss is measured. On 2026-10-02 two queries ran twice each with identical te
 
 The authorities in both pairs were named by the session unprompted once it was asked to, which is the argument for a method over a list. Two queries at one run each show the effect exists and do not size it.
 
-Access is a second gap a session cannot derive. Probed on 2026-10-02, Reddit refused its JSON search with a 403 and refused `WebFetch`, while its RSS feed answered 200. X redirected `curl` to a login page and returned 402 to `WebFetch`, so no free route reaches it.
+Access is a second gap a session cannot derive. Probed on 2026-10-02, Reddit refused its JSON search with a 403 and refused `WebFetch`, while its RSS feed answered 200. X redirected `curl` to a login page and returned 402 to `WebFetch`, so no free route reaches it. Re-probed on 2026-10-04, Reddit's RSS feed, its search feed, and its JSON listing and search all answered 403, so the feed that answered two days earlier no longer does.
 
 ## Must
 

package/claude/skills/search-craft/SKILL.md

@@ -1,6 +1,8 @@
 ---
 name: search-craft
 description: Carries the thinking step a session takes before it searches outside the project, naming the field, deriving who that field treats as authoritative, and running a search scoped to those sources beside an open one, plus a dated note on which sites refuse access. Use before any outside search for evidence, papers, documentation, statistics, or opinion, when a procedure loads it at its sourcing step, or when asked "find me the strongest evidence on X", "where should I look for this", "what does the research say", "find papers on", "look up the docs for", or "what are people saying about". Do NOT use to format a citation, which belongs to the surface writing it, to source a Claude Code subject, which is the `claude-code-guide` agent, or to generate an image, which is not search.
+metadata:
+  family: build
 ---
 
 # Search craft
@@ -44,10 +46,12 @@ The procedure that loaded this skill owns what the result is for and where it is
 
 Each line is a claim measured once, and `${CLAUDE_SKILL_DIR}/REQUIREMENT.md` records the date under its Gap. Sites change their blocking without notice, so re-check a line before relying on it. Add a line only for a failure a session actually hit, and record the date it hit in the requirement beside it.
 
-- Reddit answers its RSS feed and refuses its JSON search with a 403. `WebFetch` is refused for the site.
+- Reddit refuses its RSS feed and its JSON search alike with a 403. `WebFetch` is refused for the site, so no keyless route reaches it.
 - X answers nothing without paying or a login. `curl` redirects to a login page and `WebFetch` returns 402.
 - Stop and ask the operator before any route that pays, logs in, or works around a refusal. Never suggest scraping behind a login.
 
+Read `${CLAUDE_SKILL_DIR}/references/adopted.md` only when extending this guidance or arguing against a rule in it. It records which comparable skills were read, what was adopted and declined, and why.
+
 ## Excuses and rebuttals
 
 | Excuse                                   | Rebuttal                                                                                                                                    |

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

@@ -0,0 +1,30 @@
+---
+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
+---
+
+# 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 searches measured in this skill's `REQUIREMENT.md` rather than on any of them. A later session extending the skill adds to this file 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.
+
+**Calling the tools directly.** The same skill ships no wrapper scripts, so it calls the command-line tools and servers it names. Adopted as the rule to reach a keyless API with a plain request rather than writing a wrapper for one search.
+
+**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.
+
+## Declined
+
+**A directory of sites per category.** None of the three is one, and each earns its keep on access and cost instead. A site list also rots with nobody noticing, so the body derives a field's authorities per question rather than reading them off a list.
+
+**Reaching walled sites through a logged-in browser.** `claude-research-stack` reaches Reddit and X through a desktop Chrome session holding the operator's login. Declined because the body never suggests working around a login.
+
+**A bundled engine.** [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
+
+**Naming the field and deriving its authorities.** No comparable skill takes a thinking step before searching. The step rests on the paired open and scoped searches recorded in `REQUIREMENT.md` under `Gap`, 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.

package/claude/skills/seed-sync/SKILL.md

@@ -1,6 +1,8 @@
 ---
 name: seed-sync
 description: Audits a project's installed Claude seed docs against the toolkit's current seed source and proposes per-section edits without overwriting customizations. Use when asked to "sync seeds", "update my seeds", "check seed drift", "did the toolkit seeds change", or when reconciling `CLAUDE.md` and `.claude/` preambles after an upstream toolkit update.
+metadata:
+  family: upkeep
 ---
 
 # Seed sync

package/claude/skills/session-compact/SKILL.md

@@ -1,6 +1,8 @@
 ---
 name: session-compact
 description: Captures a session's memory, then writes one handoff note to .canon/compact/ so the session after a compaction picks up where this one stopped. Use before running /compact, when asked to "write a handoff", "prepare for compaction", "save where we got to", or before moving a session to another machine, or when a PreCompact hook blocks and names this skill. Do NOT use for a session holding the orchestrator role, whose board handoff is `session-map`. Do NOT use to record a decision a groundwork track owns, which is `plan-groundwork`.
+metadata:
+  family: parallel
 ---
 
 # Session compact

package/claude/skills/session-map/SKILL.md

@@ -1,6 +1,8 @@
 ---
 name: session-map
 description: Writes the session map, the board-side handoff at `.canon/tasks/session-<slug>.md`, for an orchestrating session or on a request naming the session map or the task board, running the skill-drift step the write procedure opens with. Use when asked to "write the session map", "write the board handoff", or when a session holding `canon:role-orchestrator` hands off before a compaction. Do NOT use for a plain session about to compact, which is `session-compact` and writes a note outside the board. Do NOT use to route session facts to a context entry or the memory folder, which is `memory-capture` and writes a different artifact, and do NOT use to read a handoff back, which is `session-resume`.
+metadata:
+  family: parallel
 ---
 
 # Session map

package/claude/skills/session-relay/SKILL.md

@@ -1,6 +1,8 @@
 ---
 name: session-relay
 description: Relays a message to another session, turning the sessionId the caller named into an address at the moment of sending and composing a copyable block where no send tool exists. Use when asked to "relay this", "message the controller", "send this over to the session that dispatched me", or "tell the other session", with or without a role, and when a session stuck on a question owes the session that dispatched it a message before it stops to ask. Do NOT use to decide what the message says, and do NOT use to assert what a session may write or is on the hook for, which is `role-worker` or `role-planner`.
+metadata:
+  family: parallel
 ---
 
 # Session relay

package/claude/skills/session-resume/SKILL.md

@@ -1,6 +1,8 @@
 ---
 name: session-resume
 description: Resumes a previous session by reading the handoff it left behind, tracked work, and relevant context. Use when starting a new session, or when asked to "pick up where we left off", "what was I working on", or "resume".
+metadata:
+  family: parallel
 ---
 
 # Session resume

package/claude/skills/session-worktree/SKILL.md

@@ -1,6 +1,8 @@
 ---
 name: session-worktree
 description: Enters a Claude Code worktree at `.claude/worktrees/<name>/` with a name derived from the active plan or branch. Use when asked to "enter a worktree", "start a worktree", "work in a worktree", or at the plan-to-execute boundary after `/plan-feature`. Also use when an `Edit` or `Write` to a main-root file such as a plan, a task, or a memory entry was refused for session isolation. Do NOT use to list, clean up, or rotate worktrees (use `git-worktree`).
+metadata:
+  family: build
 ---
 
 # Session worktree
@@ -125,17 +127,7 @@ Read the worktree root and evaluate node and python independently against a lite
 
 Name the ecosystem in both installed lines rather than leaving `Dependencies are installed.` unqualified. Both checks can fire on one project, so an unqualified line reported the same sentence twice for a dual-root project with both folders present, and a reader could not tell which half each line answered.
 
-Take `<install>` from the lockfile beside the manifest, checked in this order, first match wins:
-
-| Lockfile                  | Install command |
-| ------------------------- | --------------- |
-| `bun.lock` or `bun.lockb` | `bun install`   |
-| `pnpm-lock.yaml`          | `pnpm install`  |
-| `yarn.lock`               | `yarn install`  |
-| `package-lock.json`       | `npm install`   |
-| none of the above         | `bun install`   |
-
-The order matters only when more than one lockfile sits beside the manifest, such as a project mid-migration between package managers. It is fixed rather than derived from anything about the project, so a reader hitting that rare case checks which manager the project actually uses rather than trusting the row the table picked first.
+Take `<install>` from the lockfile beside the manifest. Read `${CLAUDE_SKILL_DIR}/references/install-command.md` when the Node line reports dependencies not installed, for the order the lockfiles are checked in and the command each one names.
 
 Emit the closing line only on its own direct test, run ahead of the two checks above rather than reached by falling through them unmatched: `[ ! -f package.json ] && [ ! -f pyproject.toml ] && [ ! -f requirements.txt ]`: `No package manifest, so there is nothing to install.` A dual-root project matches both checks above, and a fallthrough test would route it here by accident.
 

package/claude/skills/session-worktree/references/install-command.md

@@ -0,0 +1,20 @@
+---
+title: Install command
+description: Which install command session-worktree Step 6 names when a Node worktree has no dependencies, read off the lockfile beside the manifest in a fixed order
+---
+
+# Name the install command
+
+Part of Step 6 of `session-worktree`. The session reads this file when the Node check reports dependencies not installed, to fill `<install>` in that line.
+
+Take `<install>` from the lockfile beside the manifest, checked in this order, first match wins:
+
+| Lockfile                  | Install command |
+| ------------------------- | --------------- |
+| `bun.lock` or `bun.lockb` | `bun install`   |
+| `pnpm-lock.yaml`          | `pnpm install`  |
+| `yarn.lock`               | `yarn install`  |
+| `package-lock.json`       | `npm install`   |
+| none of the above         | `bun install`   |
+
+The order matters only when more than one lockfile sits beside the manifest, such as a project mid-migration between package managers. It is fixed rather than derived from anything about the project, so a reader hitting that rare case checks which manager the project actually uses rather than trusting the row the table picked first.

package/claude/skills/sketch-design/SKILL.md

@@ -1,6 +1,8 @@
 ---
 name: sketch-design
 description: Runs a reference-and-pick loop against operator-supplied images and URLs, then writes the picked reference's traced color, type, and spacing values to a handoff file `design-extract` reads. Use when asked to "sketch a design direction", "compare these reference sites", "pick a look before we build DESIGN.md", "show me a few design directions", or as the first move on `design-extract`'s greenfield path when nothing has been rendered yet. Do NOT use when a value is already anchored to running code or a stylesheet, which is `design-extract`'s source path, or to draft the design system document itself, which stays `design-extract`'s job.
+metadata:
+  family: setup
 ---
 
 # Sketch design

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

@@ -1,6 +1,8 @@
 ---
 name: systematic-debugging
 description: Forces root-cause investigation before any fix when a test fails, a bug surfaces, or unexpected behavior appears. Auto-triggers on "test is failing", "it's broken", "why does X happen", "this isn't working". Do NOT use for trivial typo fixes or when the cause is already agreed on.
+metadata:
+  family: build
 ---
 
 # Systematic debugging

package/claude/skills/target-check/SKILL.md

@@ -1,6 +1,8 @@
 ---
 name: target-check
 description: Reports what a target project holds against what the toolkit currently ships, one section per domain, reading through `canon` verbs rather than inspecting files. Use when asked to "check this target", "what has this project fallen behind on", "is this project current with the toolkit", "run the target check", or as the first thing a rollout worker runs after entering a target. Do NOT use to repair a finding, which the owning command or skill does, and do NOT use in the toolkit repository itself.
+metadata:
+  family: upkeep
 ---
 
 # Target check

package/claude/skills/target-setup/SKILL.md

@@ -1,6 +1,8 @@
 ---
 name: target-setup
 description: Gets a project onto the toolkit. Detects the stack, resolves per-domain arguments, previews the chain, runs `canon init`, then verifies at a stated depth and bootstraps the `index.md` system. Use when asked to "set up this project", "init this project", "bootstrap the toolkit", "install governance", "install gov rules", "set up indexes", "verify the scaffold", "run the smoke tests", or "one-shot install". Assumes the `canon` CLI is on PATH. Do NOT use on a project that already carries the toolkit, which is `canon-operator`, or to report per-domain drift without repairing it, which is `target-check`.
+metadata:
+  family: setup
 ---
 
 # Setup

package/claude/skills/target-setup/references/detect.md

@@ -9,6 +9,14 @@ What the `install` and `gov` phases both do before they write anything. Stated
 once here rather than twice in the body, since the two phases differ in what
 they install rather than in how they read the project.
 
+## Contents
+
+- [Read the catalogs](#read-the-catalogs)
+- [Detect](#detect)
+- [Resolve arguments](#resolve-arguments)
+- [Gap handling](#gap-handling)
+- [Preview](#preview)
+
 ## Read the catalogs
 
 Run in parallel. Never hardcode stack, rule, or standards names. The

package/claude/skills/target-setup/references/indexes.md

@@ -12,6 +12,19 @@ user, and writes. The CLI handles validation and regeneration only.
 Read `canon docs indexes` from the toolkit if context on the system is needed
 before scanning.
 
+## Contents
+
+- [Scope](#scope)
+- [Scan](#scan)
+- [Present candidates](#present-candidates)
+- [Draft frontmatter](#draft-frontmatter)
+- [Scaffold the folder index](#scaffold-the-folder-index)
+- [Inject](#inject)
+- [Validate](#validate)
+- [Offer the convention seed](#offer-the-convention-seed)
+- [Closeout](#closeout)
+- [Reference](#reference)
+
 ## Scope
 
 - Bootstrap un-indexed folders only. Skip folders that already contain an `index.md`.

package/claude/skills/target-setup/references/verify.md

@@ -12,6 +12,14 @@ Two depths over one contract. Both read the `scripts` block from the project's
 own `package.json` and run what is declared there, so neither hardcodes a script
 name and a stack exposing a different set is covered without an edit here.
 
+## Contents
+
+- [Guards](#guards)
+- [Step 1: read scripts](#step-1-read-scripts)
+- [Step 2: run the chain](#step-2-run-the-chain)
+- [Step 3: report](#step-3-report)
+- [Out of scope](#out-of-scope)
+
 ## Guards
 
 A monorepo syncs each language root into its own subfolder, so the project root