@erclx/canon 4.118.0 → 4.120.0

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

@@ -15,17 +15,17 @@ Refilling on a merge and on a thinning ready list leaves the window between them
 
 Every one of those triggers looks forward, so a row already parked is measured once and re-tested never. A blocker cell is a claim about the tree that was true the day it was written, and a merge changes the tree under every parked row at once rather than under the rows naming it. A row therefore sits on a condition that stopped holding weeks earlier with nothing reporting the gap.
 
-Re-measuring one goes wrong twice over, and both ways return a confident number rather than an error. A count read looser than its consumer defines the shape answers a question nobody asked, and a condition measured against the tree at hand reads as unreachable while it stays live in the corpus a shipped command runs against. Waiting is not evidence either, so a row untouched for weeks invites promotion on its age, and a task colliding with everything by construction gets re-measured every pass rather than split.
+Re-measuring one goes wrong twice over, and both ways return a confident number rather than an error. A count read looser than its consumer defines the shape answers a question nobody asked, and a condition measured against the tree at hand reads as unreachable while it stays live in the corpus a shipped command runs against. Waiting is not evidence either, and a task colliding with everything by construction gets re-measured every pass rather than split.
 
 Writing those plans against the tree alone is the second half, since several branches are already changing the shape a plan describes. A plan carrying a bare path list rather than a constraint per in-flight track leaves the worker guessing which act each path forbids, which is the dangling citation the rule against bare paths already exists to prevent.
 
-The session also writes surfaces it is told only how to read. Refilling the queue promotes and demotes rows in the priority file with no stated method, so a session invents one, and an inline rewrite exits clean when it matches nothing and leaves the board wrong with nothing reporting it. A row carrying prose where a plan pointer belongs costs a worker dispatch, because the ship chain refuses at its guard after the worktree is already open. A plan archived from a worker's own branch strands the pointer the board still carries, and the row reads as correct until someone follows it.
+The session also writes surfaces it is told only how to read. With no stated method for rewriting the priority file, a session invents one that can exit clean on a non-match, carry prose where a plan pointer belongs, or keep a pointer to a plan a worker's branch archived, and each reads as correct until a dispatch spends on it.
 
 The ban on writing at all fails on a different axis, which is that nothing enforces it and a session weighs proportionality against it. A one-line prose correction found while orchestrating satisfies the root instruction to handle a small edit immediately and violates this rule, and a session given no statement of which one wins takes the smaller apparent cost and authors the change.
 
 That removes the independent pass the repository built to catch what a self-review misses, and the vantage does not come back, since no later session can review the change without re-deriving the context that produced it. A correction no open task owns has nowhere to go either, so the route matters as much as the ban.
 
-The contract also stops one state short of what the session holds. Its sections cover what the human launches and what they review, which was the whole state space while every build was hand-launched, and a self-dispatching session adds a third that sits between them for ten to thirty minutes. A session holding four running workers reports them under no section and invents a shape per report, which the same block forbids while offering no term to use, and the launch section keeps recommending a plan a worker is already building because the plan file sits in place for the whole build.
+The contract also stops one state short of what the session holds. Its sections cover what the human launches and what they review, and a self-dispatching session adds a third that sits between them for ten to thirty minutes, which a session reports under no section while the launch section keeps recommending a plan a worker is already building.
 
 Output drifts everywhere the contract stops. The specified shape covers invocation alone, so a sweep report, a board report, and an analysis each end in a decision the human owns and each buries it under the evidence they would have skipped. A compaction is the same failure one step earlier, since the file that survives it has a stated reader and no stated writer, and the session improvises what to save and loses the reasoning the board never held.
 
@@ -33,17 +33,17 @@ Naming that reader without naming the way in fails on the next axis, and it fail
 
 The runbooks the session cannot run from memory fail on a third axis, which is where they are kept. A runbook reached by an installed path is a dependency on a channel this skill does not travel on, so a project holding the plugin and running no install follows the citation to nothing, and nothing reports the break because a missing file produces no error until someone opens the path.
 
-Every one of them therefore has to ship inside the skill, the four covering the moments the loop cannot detect and the fifth holding the review trigger. That last one fails on an axis of its own, since it names one client's command as the way to start the loop, so a session holding a different recurring-prompt scheduler reaches no path and a client without that command reaches none either, and the file ships to every target holding the plugin.
+Every one of them therefore has to ship inside the skill. The review trigger fails on an axis of its own when it names one client's command as the way to start the loop, since the file ships to every target holding the plugin and a client without that command reaches no path.
 
 The dispatch's return leg is unplaced for the same reason. A reply reaches this session as a message and settles a finding, corrects which session holds which branch, or names a gate a worker's edits pass through, and reading it is the whole of what happens to it. Both sessions then end, so the half that belonged on the pull request never reaches it and the half that belonged on the board is rediscovered by whoever needs it next.
 
-Both halves of that channel are written here and one of them is performed elsewhere, so a worker owes what nothing it loads states. The review trigger inherits the same asymmetry: it fires on a dispatch as well as on a pull request, spending an interval against a building worker that has none, which five consecutive runs measured as reporting nothing across roughly fifteen minutes. The one reading that would close the gap is the roster read the poll script cannot make, since a worker that finishes goes idle and one that crashes vanishes, so a trigger matching pull requests alone stays silent through the second. The loop that did make it ran for an afternoon in a session's temporary directory against a hardcoded repository path, and it died with that session with no runbook naming it.
+Both halves of that channel are written here and one of them is performed elsewhere, so a worker owes what nothing it loads states. The review trigger inherits the same asymmetry: firing on a dispatch spends an interval against a building worker that has no pull request, and a trigger matching pull requests alone stays silent through a worker that crashes, which only a roster read the poll script cannot make would catch.
 
 Cost never enters the decision to widen a wave. The rule weighing how many tracks to open measures collision and review attention, and both describe what a worker writes rather than what the loop spends. Claude Code delivers a message from another session as a fresh turn carrying the whole accumulated context, and a recurring poll bills that same window on its own interval, so a wave's spend tracks this session's context rather than the work coming back. The one setting that bounds it reads as available to whoever finds it, and the two values that would bound it break the handback the loop runs on.
 
 The session also records nothing of what it learns. Both other callers of memory capture are ship-chain skills and this one never ships, so the session taking every operator correction is the session with no moment that writes one down. Hanging that moment on the merge sweep answers it and bills the operator a capture pass per batch of merges while nothing is being built, which is a cost paid on the days shipping is fastest.
 
-Dispatch parts from what it checked in three measured ways. The gate and the worker each derived the branch from their own reading of one plan until 2026-09-06: one run checked `docs/remaining-skill-verdicts` against a worker that took `docs/skill-verdicts-decide`, another checked `fix/path-form-hook` against `feat/path-form-hook`, and four dispatches on 2026-09-05 produced three strings for one plan. A launched worker inherits its launcher's model rather than the configured default, measured on 2026-08-27 with `~/.claude/settings.json` set to `sonnet` while both dispatched workers ran `claude-opus-5`. A cleared file set does not hold either, since three tracks in the wave of 2026-09-08 crossed a set they had cleared against and every one merged clean.
+Dispatch parts from what it checked in three ways. The gate and the worker each derive the branch from their own reading of one plan and reach different strings, a launched worker inherits its launcher's model rather than the configured default, and a cleared file set does not hold, since a track can cross the set it cleared against and still merge clean.
 
 ## Must
 
@@ -52,24 +52,18 @@ Dispatch parts from what it checked in three measured ways. The gate and the wor
 - Verify a plan against the tree before handing it over, counting the sites it claims and opening the files it describes
 - List a candidate's file set against every track in flight, and serialize when the sets are not disjoint
 - State what a wave costs in inbound turns beside the collision rule, and name the control that bounds it together with the reason it stays unset, since a lever recorded without its conclusion reads as available to set
-- Place every finding a merged pull request produced against the surface that owns it
+- Place every finding a merged pull request produced against the surface that owns it, and write the board so a row's readiness and disjointness claims stay checkable
 - Place what the return leg carries by what it changes, sending an answer that settles a finding onto the pull request and one that corrects this session's model of the world to the task owning that surface, since neither becomes a record by being read
 - Keep one planned, non-conflicting task in reserve beyond what is running
 - Refill the queue while a wave is still building, rather than on a merge and a thinning list alone, since neither of those fires across the window planning costs nothing
 - Carry a constraint naming each in-flight track's file set in every plan written from here, stating per set which of the two acts it forbids, since a bare path list leaves a broken citation in place
-- Write the priority file with an editing tool that errors on a non-match, since the board is where a silent failure costs a dispatch
-- Carry a plan pointer in the Plan column and a file set in the Touches column, so a row's readiness and disjointness claims stay checkable
-- Re-resolve the board's plan pointers after any archive, since the archiving skill rewrites the task file and knows nothing about the board
-- Carry a slot for this session's own workers mid-build, one row apiece naming the session, the branch, the model, and a progress reading taken from the worktree, since the two other slots cover what a human launches and what they review and nothing between
-- Withhold a plan from the launch slot once a row in flight names it, since the plan file sits in place for the whole build and listing it recommends handing off work already underway
+- Carry a slot for this session's own workers mid-build, and withhold their plans from the launch slot, since the two other slots cover what a human launches and what they review and nothing between
 - Start the review poll on an open pull request rather than on a dispatch, and keep the dispatch as a fallback for an announcement that never arrives, since the script reads pull requests and a building worker has none
 - Point at the worker's own skill for the announcement, the block message, and the board ban, rather than holding the only written copy of obligations this session does not perform
 - Ship the roster-and-pull-request watch as a script beside the poll, since the loop that covered the gap lived in one session's temporary directory against a hardcoded path and died with that session
 - Lead a sweep report, a board report, and an analysis with the state, the open decisions, and the next action, keeping the evidence below them
 - Write the pre-compact handoff with what no other file carries, and name the runbook that reads it back
 - Carry the resume invocation and the owed poll restart in the handoff file itself, not in the runbook that writes it alone, since the file is what survives a compaction and the runbook is what a session has to already be holding to read
-- State the invocation as a resume request to this skill with one client's command as the example, since the handoff ships to every target holding the plugin
-- Resolve every runbook path the handoff carries to an absolute path as it is written, since the reader holds no skill and the path variable does not expand in the turn that reads the file back
 - Distinguish this resume from the general-purpose `session-resume`, since the name an operator reaches for first reaches a skill that knows nothing about the board
 - Capture what the session learned at the handoff rather than in the merge sweep, and have the sweep report the debt dated from the last handoff, since a capture per batch of merges bills the operator a wait while nothing ships and an undated row reads the same however long the debt has run
 - Retire the sessions this wave delivered before the map is written and ahead of any reclaim run, reporting a hand-launched one rather than acting on it, since no verb decides a planner or an unmerged worker and a live session holding a worktree is what the reclaim reading refuses on
@@ -85,8 +79,7 @@ Dispatch parts from what it checked in three measured ways. The gate and the wor
 - Check a candidate branch is unclaimed by an existing worktree or a live session before dispatching a background worker for it, since the measured failure this closes is a worker colliding with someone else's work already sitting in the row
 - Dispatch only a candidate whose file set is disjoint from every track in flight, compared at the file path rather than a folder above it, since a count knows nothing about what two workers write
 - Hold a candidate whose sets are disjoint when a stated reason serializes it, and write that reason on the hold, since disjointness is necessary and not sufficient
-- Name each self-dispatched worker with the `worker-` prefix, since that is the role the name marks and no controlling session has ever carried it
-- Pass `-n` explicitly on every self-dispatch, since a launch that omits it leaves the client to derive a name and the fallback is a fragment of the session's own identifier
+- Name each self-dispatched worker explicitly with the `worker-` prefix, since that is the role the name marks and a client-derived name is a fragment of the session's identifier
 - Carry the dispatcher's `sessionId` in the launch prompt, since a worker owed two messages has no property on the roster that resolves a controller and a name goes stale inside the window it builds in
 - Report each self-dispatch and the row it fired against loudly enough to follow, since a person no longer watches the launch step happen
 - Stop dispatching once `## Run now` is empty or every row in it reads claimed, rather than waking again to fire on a board nobody is clearing

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

@@ -53,83 +53,18 @@ That routing lives in this body and this skill is user-invoked, so a session tha
 
 ## Output
 
-```plaintext
-Orchestrator ready.
-
-Ready to build (hand each to its own worker):
-
-<feature>
-  plan: .canon/plans/feature-<slug>.md
-  → /auto-ship
-
-<feature>
-  no plan yet. A handoff without a plan has no scope
-  → /plan-feature here first
-
-In flight (this session's workers, building now):
-
-<session name>  <branch>  <model>
-  task: <row>, <n> commits, <n> files changed
-
-In review (your turn):
-
-PR #<n> <title>
-  → /review-pr
-
-Merge order: #<a> before #<b> (shared seam: <files>).
-
-Next: <the single most useful action>
-```
-
-Omit any section with nothing in it. Recommend a handoff only for a plan whose file set is disjoint from every track already in flight, per Parallelism below.
-
-`In flight` covers the state between the other two, which lasts ten to thirty minutes and is most of what an operator sees once this session dispatches its own workers. Before it existed, a session holding running workers reported them under no section and invented a shape per report, which the block below forbids two paragraphs down while giving it no term to use. Read the progress figures off each worker's worktree rather than from the worker, since a busy status says a session is alive and nothing about whether it is moving, and name the model because a dispatcher now picks one per row.
-
-Leave a plan out of `Ready to build` once a row in flight names it. The plan file stays in `.canon/plans/` for the whole build, so listing it there recommends handing off work already underway, and the disjointness rule below withdraws the recommendation only for a reader who already knows what is running.
-
-The block opens on the board rather than on a version, because no committed file states one. Adding a version line here would restate what a reader can already see on the rows, dated by nothing, which is how the retired sequencing surface produced an unsourced claim on every run.
-
-### Every later turn
-
-The block above covers invocation alone. A sweep report, a board report, and an analysis each end in something the human decides, so each opens with the same three slots and puts its evidence underneath:
-
-```plaintext
-State: <what changed since they last looked>
-
-Decisions:
-  1. <one line each, or "none open">
-
-Next: <the single most useful action>
-```
-
-Keep the detail below the block and keep it skippable. A decision reached at the bottom of three paragraphs has been buried, which is the failure this shape exists to prevent. Reuse the vocabulary above rather than inventing a second one, and keep a file set on the row claiming it so the reader can check a disjointness claim instead of taking it.
-
-Write no shape for a correction. A correction is a sentence, and a format for admitting error invites ceremony where plainness is the whole value.
+Report the state of play in the invocation block, and open every later sweep report, board report, and analysis with its state, the open decisions, and the next action, keeping the evidence below them. Read `${CLAUDE_SKILL_DIR}/references/orchestrator-output.md` for both shapes before writing either.
 
 ## The loop
 
-1. Plan the next feature. The cross-feature call stays in this warm session, being which rows collide, what merges before what, and whether a row should run at all. Per-row planning runs either way: `plan-feature` here with that context, or a cold planner dispatched under `role-planner` through the planning shape in `${CLAUDE_SKILL_DIR}/references/orchestrator-dispatch.md`. Every plan written from here also carries a constraint per track in flight, which the paragraph below this list states.
+1. Plan the next feature. The cross-feature call stays in this warm session, being which rows collide, what merges before what, and whether a row should run at all. Per-row planning runs either way: `plan-feature` here with that context, or a cold planner dispatched under `role-planner` through the planning shape in `${CLAUDE_SKILL_DIR}/references/orchestrator-launch.md`. Every plan written from here also carries a constraint per track in flight, which the paragraph below this list states.
 2. Decide parallelism and merge order. Note which plans touch a shared wiring seam so their PRs merge in sequence, not at once.
 3. Verify the plan against the tree. Reading it is not enough, since a plan goes stale from whatever merged after it was written. Grep for each construct it names and count the sites against the count it claims. Check that every phase label it cites is still open. Open each file it describes rather than trusting its account of the contents. Correct the plan before handing it over.
 4. Hand off. Read `${CLAUDE_SKILL_DIR}/references/orchestrator-dispatch.md` and follow it: check the branch is unclaimed, check the row's file set against every track in flight, then dispatch a background worker with `claude --bg`. Fall back to the human-launch line it replaces when the check refuses, the sets overlap, or a stated reason serializes the row behind something already out.
 5. Review the PR. When a worker opens a PR, run `review-pr` to post findings to it. This is the deep, independent pass. The worker's autoship self-review was only the green gate.
    - Learning that a PR moved is the mechanical half, so read `${CLAUDE_SKILL_DIR}/references/orchestrator-poll.md` and run the poll under the condition it states rather than checking the board by hand. That runbook holds the routing and the trigger, and a summary of it here is a second source that drifts from it.
 6. Dispatch the handback. A pass posting anything owed, a finding at any severity or a testing question, tells the session holding that branch to run `review-address`, rather than waiting for a person to relay it. Re-review when the worker's own message says the address pass finished, per the channel `role-worker` states, rather than polling for an answer nothing else marks as landed. Once a pass posts `## Review closed`, lift the pull request's draft mark yourself, per Boundaries below. Then the human merges. Tell the trailing worker to rebase when its branch shares a seam with the merged one.
-   - Read the threshold off `review-pr`, which states it once and governs the heading with it, so an open heading and an owed dispatch answer the same question and either one is enough to send
-   - Resolve the target at the moment of sending with `canon sessions list --branch`, never from a mapping written down earlier, since names rotate as sessions end and one recorded earlier in a session has failed inside the hour. The runbook read at step 5 routes on the count and the confidence it answers with
-   - Open the message with the worktree and branch the sender believes the reader holds, asking to be corrected, whenever that mapping is inferred rather than confirmed
-   - 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 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. Every dispatch in the trial behind this step found a live session, so this branch stands on reasoning rather than on observation.
-
-The channel runs both ways and the return leg carries what the pull request cannot. A worker answering a posted finding by naming the plan question that had already declined it changes the outcome in the moment, where a thread comment waits on whoever reads it next. Read what a worker volunteers as part of the review rather than as an aside, and read a refusal the same way, since the corrections that landed on this session's model of the world arrived as a worker arguing back rather than complying.
-
-What the worker owes on its own side is stated in the `role-worker` skill that session loads, being the pull-request announcement, the message a block goes out as before it becomes a prompt, and the ban on writing the board. Do not restate any of it here. This half held the only written copy of a channel that runs both ways, which put every obligation on the side that does not perform it.
-
-What arrives there does not become a record by being read, so place it by what it changes. An answer that settles a finding goes onto the pull request through the next pass, which withdraws or regrades that finding and names the fact behind it, per `review-pr`. An answer that changes what this session believes about the world instead, which is a mapping correction or a constraint on what a worker can do, settles no finding and reaches no thread, so route it the way Boundaries below routes a change found while orchestrating, which lands it on the task owning the surface it describes. Writing a tracked file to hold either is forbidden here, which leaves the pull request and the board as the two surfaces this session writes.
-
-Step 1 splits a rule that used to hold every plan in this session, and the evidence narrows it rather than retiring it. Two trials put a cold planner on four rows, and it reported ten things the task files got wrong, corrected this session's own premise twice, and overturned one row's closing conclusion. What that measures is finding quality. The rule's own claim is that a warm plan front-loads reasoning a cold worker would otherwise re-derive, which is a statement about a plan's downstream value, and no plan from either trial has been built. So the per-row measurement goes cold on the evidence and the cross-feature call stays here on the boundary the same trials confirmed, which is that a planner reading the board sees blockers and file sets and can write a confident merge order off a partial picture.
+   - Read `${CLAUDE_SKILL_DIR}/references/orchestrator-handback.md` on reaching this step. It holds how the message is addressed and worded, what to do when no live session holds the branch, and where a worker's reply goes.
 
 A plan written here is written against a tree several branches are already changing, so it names the file set of every track in flight as a constraint, one set per track, read from the Touches column of that track's row. State for each set which of the two acts it forbids, per Constraints in `${CLAUDE_SKILL_DIR}/../../standards/plan.md`. A bare path list leaves the worker guessing, which is how a plan ends up forbidding the repair of a citation the change broke.
 
@@ -141,7 +76,7 @@ Stamp the block with the commit this session read the tree at, which the same se
 - Do not implement features in this session. Hand the plan to a worker.
 - Do not merge. Recommend merge or changes. The human merges.
 - Lift a pull request's draft mark once this session's own review of it closes, acting directly on the pull request rather than dispatching a worker to do it. `role-worker` states the mirroring refusal: a worker cannot verify who is asking or whether review actually closed, so the act stays with whoever closed the review.
-- Do not spawn a worker with the Agent tool. An in-process subagent shares this session's context and cannot be steered or reached independently, which breaks the property this boundary protects rather than the mechanism it names. The dispatch in `orchestrator-dispatch.md` is a separate `claude --bg` process with its own worktree and its own PR, so it preserves that property instead.
+- Do not spawn a worker with the Agent tool. An in-process subagent shares this session's context and cannot be steered or reached independently, which breaks the property this boundary protects rather than the mechanism it names. The launch in `orchestrator-launch.md` is a separate `claude --bg` process with its own worktree and its own PR, so it preserves that property instead.
 - Dispatch a background worker only once the collision check in `orchestrator-dispatch.md` clears and the row's file set is disjoint from every track in flight. Colliding with an existing worktree or session is what the check exists to catch rather than a judgment call this session makes case by case. No fixed count binds how many tracks run at once, and Parallelism below states what does.
 - Do not edit tracked files from this session, at any size. The boundary offers no proportionality exception and nothing enforces it.
 - Do not hand a worker anything but a plan, since scope lives there. A plan carries exact diffs only when they are already known, otherwise it states the scope and the open questions and lets the worker write the diff.
@@ -160,57 +95,9 @@ Both kinds read the same tree, and only a sizing count commits a plan to a scope
 
 ## Refilling the ready queue
 
-Keep enough planned, non-conflicting tasks available that a free worker never waits, and place the findings the last merge produced before promoting anything new. Run this after every merge, whenever the ready list thins, and whenever a wave is in flight with fewer unclaimed plans than there are workers building. `${CLAUDE_SKILL_DIR}/references/orchestrator-sweep.md` wraps this procedure for a batch of merges and adds the plan re-verification that a merge invalidates.
-
-The third trigger reaches a window the first two cannot. A session with three workers mid-build has merged nothing and has watched its ready list sit still, so both reactive triggers stay silent across the one stretch where planning costs the session nothing, and the wave finishes into an empty `## Run now`. Nothing starts this pass, in the way nothing starts the review poll, so it holds only while the session applies it.
-
-It counts unclaimed plans against workers rather than reading the reserve in step 4, which is sized for one worker finishing and falls short of a wave landing together. A plan a worker has already taken serves nobody who finishes next, so counting it is what lets the queue read full while it is about to empty. How many to write forward past that floor is the parallelism call rather than a count of free slots, and `## Parallelism` below states what binds it.
-
-### Running the refill
-
-1. Run `gh pr list --state open` and `git log --oneline -8`. Report any pull request whose review has not been posted and stop for that one first.
-2. For each pull request merged since the last sweep, place every finding it produced. Route a finding that changes a rule to the standard or rule that states it, one that changes another task to that task's Findings, and one that overturns a groundwork lean to that folder marked answered. Never leave a finding in a pull request thread alone.
-3. Archive what closed.
-   - A task whose outcomes are all `[x]` runs `docs-fold` for the plan sweep, then `task-board` to archive
-   - A task whose outcomes describe standing policy rather than a deliverable never closes on its own, so hand it to a worker to encode the policy where it is enforced, then cut the outcomes with the reason recorded and archive once that branch merges. Encoding it from this session would write a tracked file, which Boundaries forbids.
-4. Read `.canon/tasks/priority.md` and count entries under its `## Run now` heading that carry a written plan. Keep one in reserve beyond what is running.
-5. Promote from the top of `## Needs a plan`, which is where the last sweep recorded what to plan next. Depart from that order when something has changed under it and say what changed, since a position nobody honors is the ordering going stale on the surface built to hold it. What sets the order in the first place is whether a task establishes functionality rather than how old it is, so prefer a task that adds or proves a mechanism over one that trims, tidies, or audits an existing surface.
-   - Re-take the demotion half of the board-or-backlog call while the file is open. A row that has stopped being near-term moves to `backlog.md`, one line removed from `priority.md` and written there, per the standard's test. The promotion half is `references/orchestrator-parked.md`'s to run as a full walk over every backlog row, so this step does not repeat it. A row that pass clears already sits at the bottom of `## Needs a plan` before this sweep reads the heading.
-6. Before promoting a candidate, list the files it touches against every task already running, per Parallelism below. Name the overlap and serialize when the sets are not disjoint.
-   - A candidate held by something outside the tree stays where it is whatever those sets show. A collision is one of the reasons a task cannot start, so disjointness clears that reason alone and leaves an external condition standing.
-7. Write a plan for each newly promoted task with `plan-feature`, carrying the in-flight constraint that The loop above states, then report:
-
-```plaintext
-Capture: owed since <the last handoff, or session start when none has run>
-Findings placed: <finding> → <destination>
-Archived: <task>
-Promoted: <task>, touches <surfaces>, parallel with <task> because <disjoint sets>
-Serialized: <task> behind <task>, both write <file>
-Backlogged: <task>, because <what stopped being near-term>
-Ready now: <tasks with plans, and what each waits on>
-```
-
-The capture row states a standing debt rather than a per-run result. Running capture from here costs the operator a pass between merges while nothing ships, so the row leaves the timing to them and dates the debt, since a capture owed for twenty minutes and one owed all day want different answers and undated text reads the same either way. `${CLAUDE_SKILL_DIR}/references/orchestrator-handoff.md` holds the step that pays it.
-
-That block is the detail. Lead the reply with the three slots under Every later turn above, so the human reads what they own before the evidence for it.
-
-Treat a task that edits `canon/context/` entries wholesale as conflicting with every other task, because the root instruction file requires each task to update its own domain entry as it lands.
-
-Do not promote a task to fill the queue when nothing qualifies. A thin queue is a real answer and it beats a plan nobody needed.
-
-### Writing the board
-
-Promoting, demoting, and archiving a row all write `.canon/tasks/priority.md`, and this session is the only writer apart from `canon tasks archive`. Moving a task between the board and `.canon/tasks/backlog.md` writes both files, and this session is that file's only writer.
-
-- Edit the file with the file-editing tool. A shell stream editor and an inline string replace both exit clean on a non-match, so a promotion that matched nothing leaves the board wrong with nothing reporting it, and the file-editing tool errors instead.
-- Write both halves of a move before reporting it. A row removed from one surface and not written to the other leaves a task file nothing names, and the folder is gitignored with no history to recover the row from. `canon tasks validate` reports that state, so run it after any move.
-- Put the reason a row sits where it does in its Waiting on cell. Position is the ordering and the cell is where the ordering's rationale lives, so a row promoted with the cell left alone carries an order the next sweep cannot check.
-- Put a pointer in the Plan column, never prose. `## Run now` claims a written plan covers every open outcome, and `auto-ship` refuses at its guard when it follows the column and finds no plan, which spends a worker dispatch to learn what the row should have said.
-- Name the file set in the Touches column. The disjointness call in step 6 is only checkable later when the sets are written down rather than reasoned once and discarded.
-- Re-resolve every Plan pointer after anything archives a plan
-- Read the file back after writing it, since the row that lands is the row a worker acts on
+Keep enough planned, non-conflicting tasks available that a free worker never waits, and place the findings the last merge produced before promoting anything new. Run this after every merge, whenever the ready list thins, and whenever a wave is in flight with fewer unclaimed plans than there are workers building.
 
-A Plan pointer goes stale from a branch this board never sees. `docs-fold` moves a plan to `.canon/plans/archive/` and rewrites the citation in the task file alone, so a row for a task still on the board keeps pointing into `.canon/plans/` at a file that has moved. Workers running the ship chain on their own branches archive plans this board still cites, and the board reads as correct until a pointer is followed.
+Read `${CLAUDE_SKILL_DIR}/references/orchestrator-refill.md` on reaching any of the three. It holds the procedure, its report, and the rules for writing the board.
 
 ## Parallelism
 
@@ -255,37 +142,6 @@ hand only when two worktrees derive the same offset.
 
 Two conditions move the review itself out of this session rather than binding the
 track count. One is a diff too large for this session to hold. The other is three
-or more open pull requests awaiting a first pass. Either one makes review the
-bottleneck every track is waiting on, and both answer the same way: dispatch the
-narrow re-review and keep the first pass here.
-
-Three is the operator's number, set by hand and marked as such so a
-measurement replaces it rather than argues with it. It is calibrated against a
-session that ran five workers across two waves and reviewed five pull requests in
-one stretch, several of them twice, where a sixth track was declined on judgment
-and on nothing else. What counts toward it is a pull request awaiting a first
-pass rather than every open one, since a branch already closed out and waiting on
-a merge costs this session nothing and counting it would fire the switch on a
-queue that is clear.
-
-Only the narrow re-review dispatches. A first pass reads across branches, and the
-findings that pay for its cost are the ones no single pull request shows: two
-branches regenerating one binary asset for the same count, three writing one
-context entry, a merge order making one branch's figure true only after another
-lands. A re-review asks whether the prior findings landed and whether the fix
-regressed anything, which is bounded to a delta and carries none of that reading,
-so it is the half that leaves cleanly.
-
-What it dispatches has no role skill yet. `role-worker` and `role-planner`
-each state what their session may not do and no third body states a reviewer's,
-so a dispatched re-review would hold its obligations in whatever launch string
-this session types. That is the defect those two skills were written to close, so
-write the third after the first trial rather than before it, since nothing has
-ever dispatched a reviewer and a body written now encodes a shape nobody has
-driven. Until it exists, say in the launch itself that the pass is bounded to the
-delta and that the cross-branch reading stays here.
-
-Nothing counts the pull requests. This is prose this session applies to itself,
-on the same standing as the poll's own start condition, so a wave past three
-reviewed one at a time is a rule that went unread rather than a check that
-failed.
+or more open pull requests awaiting a first pass. Read
+`${CLAUDE_SKILL_DIR}/references/orchestrator-review-fallback.md` when either one
+trips.

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

@@ -1,6 +1,6 @@
 ---
 title: Orchestrator dispatch runbook
-description: The plan-answer gate, the collision check before a self-dispatch, the file-set disjointness gate, the branch and model the launch names, the planning and handback dispatch shapes, and the loop's stopping condition
+description: The plan-answer gate, the collision check before a self-dispatch, the file-set disjointness gate, the branch and model the launch names, the fallback to a human launch, and the loop's stopping condition
 ---
 
 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.
@@ -74,7 +74,7 @@ A declared set is what a branch sets out to write rather than a bound on it, so
 
 Disjointness is necessary and not sufficient, so hold a candidate whose sets do not touch when a stated reason serializes it, and write the reason on the hold. One row creating a skill and another auditing that catalog and counting it write nothing in common, and dispatching both still leaves the audit counting a denominator that moves underneath it. Nothing verifies that a reason was written, so the rule holds only while the dispatcher applies it.
 
-What binds past that is review attention rather than a count, and `## Parallelism` in the skill body states it along with the cap an operator can set for a session. The one number this skill carries is the review fallback's count of three in `## Parallelism`, which moves a review rather than binding a track, and this runbook carries none.
+What binds past that is review attention rather than a count, and `## Parallelism` in the skill body states it along with the cap an operator can set for a session. The one number this skill carries is the review fallback's count of three in `orchestrator-review-fallback.md`, which moves a review rather than binding a track, and this runbook carries none.
 
 ## Pick the model
 
@@ -84,196 +84,7 @@ Name `<model>` on the launch, and pick it against the task rather than copying w
 
 ## Dispatch
 
-```bash
-claude --bg --model <model> -n "worker-<project>-<slug>" "/canon:auto-ship <plan>
-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 pull request opens, carrying the number, the branch, the head sha, the CI state, and every point you departed from the plan on, and message it again if you stop on a question."
-```
-
-`--bg, --background` starts the session as a background agent and returns immediately, `-n, --name` sets the display name that tells a self-dispatched worker from an operator's own launch in `canon sessions list`, and `--model` overrides the inheritance the section above states. Pass `-n` on every dispatch rather than letting the client derive one. A launch that omits it leaves the session named for a fragment of its own identifier, which is both its address on the send channel and the whole of what the operator sees for it in agent view.
-
-The prefix reads `worker-` because that is the role it marks. A prefix naming a role the session does not hold sends a worker filtering the roster for that string to a sibling or itself on every row. Nothing matches the prefix programmatically, which keeps a rename down to three strings.
-
-`<project>` is the basename of the main worktree root, not of wherever the dispatcher happens to be running. Resolve the main root first, the way `session-worktree` Step 1 does, since a bare `git rev-parse --show-toplevel` inside a linked worktree returns the worktree path rather than the project's.
-
-`claude agents` lists every session on the machine with no path column and no per-project filter, so `<project>` in the name is the only thing left telling two fleets apart, and a session named off the worktree path instead would carry the branch folder rather than the project. Two projects each dispatching a bare `worker-page-driver` used to read as one row in that view.
-
-Read `<dispatcher-id>` with `canon sessions list --self --json` and interpolate the `sessionId` that row carries. Carry the id rather than the name. A name is derived from whatever the session turned out to be doing, and across the 181 records stamping both fields, nine were renamed after launch at a median of 5.4 minutes and a maximum of 509. Three landed more than ten minutes in, which is inside the window a worker announces its pull request in, so a name written into the prompt is aimed at a send that happens after it goes stale.
-
-Where the installed CLI answers `--self` with an unknown option, that flag is newer than the release the target holds. Read the `sessionId` from the record the client writes for this session under its configuration directory, and say which route answered so the reader knows whether the id was read or inferred.
-
-The worker resolves that id back to a name through `canon sessions list --json`, which carries `sessionId` per row, rather than through the agent listing, which prints a name and a short ref and no id at all. A worker reaching for the listing first therefore finds no lookup and can conclude there is none. That failure is silent in both directions: the session has nothing useful to do with the message it owes and goes idle holding it, and nothing on this side reports the quiet, so the loss surfaces as a missing worktree or a pull request that never opens rather than as anything watching for it.
-
-The template carries no worktree call. `auto-ship` Step 0 invokes `canon:role-worker` and then `canon:session-worktree` itself, and neither carries the flag, so both are reachable through the `Skill` tool regardless of where a call to them would sit in a prompt. The autoship call carries `<plan>`, the same file this runbook already read to derive the branch, so its Step 1 takes it as the caller-supplied plan rather than re-deriving one from the slug the worker's branch happens to carry.
-
-The template names no branch, and it does not need to. `auto-ship` Step 0 runs `canon tasks plan-branch <plan>` on the same file this runbook derived the candidate from, and hands the `<type>/<slug>` it reports to `session-worktree` as its tier 0 argument, so the two sides agree by calling one derivation rather than by a string copied between them.
-
-That retires the inference four workers took before the verb existed, which was to derive the name from `<plan>` by their own reading of it. Nothing has to reach `session-worktree`'s ladder now, which mattered because a worker launched onto `main` cannot match tier 1, a board carrying more than one plan puts tier 2 out of reach, and tier 3 tells it to ask a person who is not there. What still travels on judgment is the fallback: a worker whose installed binary carries no `plan-branch` derives by prose, which is where both live disagreements came from.
-
-### Expansion needs position zero and a clean delimiter, not leading order alone
-
-The client expands a slash command at position zero of a launch prompt as a
-user invocation, which is the route `disable-model-invocation: true` permits
-and gates. Everything that reaches the session as prose instead falls to the
-model, which invokes it through the `Skill` tool, and that route answers a
-flagged skill inconsistently. `auto-ship` has carried the flag since early in its life, and seven other
-shipped skills carry it too.
-
-Three launches bound what makes a command take
-that route. Observation A is the first refused worker, launched as `Run
-/canon:session-worktree ..., then /canon:auto-ship ...`, which expanded
-nothing. Observation B is a re-dispatch launched as `/canon:auto-ship
-<plan>` with a space before the path, which expanded and shipped.
-
-Observation C is a planning dispatch launched as `/canon:role-planner, then
-/canon:plan-feature <task>` with a comma glued to the command name at
-position zero, which expanded nothing and reached both bodies through the
-`Skill` tool instead. A rules out leading order alone, C rules out position
-zero on its own, and the only visible difference between B and C is the
-delimiter after the command token: a space in B, a comma in C.
-
-Read that delimiter reading as a candidate with a falsifier rather than as
-settled. The cheapest test is one dispatch leading with a bare command whose
-name is followed directly by a period, and the next real dispatch can carry it
-at no extra cost. Until it fails, the operational rule is the conjunction the
-three observations support: put the flagged command at position zero, followed
-by a space and its argument, with nothing before it.
-
-Four sessions made the same tool call against the same plugin cache on one
-day. Two were answered with the body and shipped, and two were refused
-with `Skill canon:auto-ship cannot be used with Skill tool due to
-disable-model-invocation`. Prefixing separated nothing, since three of the
-four carried the namespace and those three landed on both answers, so nothing
-a dispatcher writes predicts which answer a launch through the tool gets.
-
-Read that as a route a dispatch may not depend on rather than one that usually
-works. The refusal closes the fallback in the same message, telling the
-session not to replicate the workflow by other means, so a refused worker has
-no route left and stops with a clean worktree. Both failed dispatches produced
-nothing rather than a degraded run, which is the correct outcome and not a
-thing to soften.
-
-Recovery belongs to whoever writes the next prompt, since a blocked session
-cannot replay its own launch. The refusal is sticky inside a session rather
-than something a retry clears, measured when one refused worker repeated the
-identical prefixed call and got the byte-identical error back. Re-dispatch
-onto the same branch with the build template above, which already leads with
-the one command that needs the expansion route.
-
-The review shape and the planning shape below depend on no expansion at all.
-None of `role-worker`, `review-address`, `role-planner`, or
-`plan-feature` carries the flag, so both correctly keep their leading word
-regardless of the delimiter or the position it sits at.
-
-The same collapse reaches a human relay rather than a `claude --bg` string. A
-controller that hands an operator two chained blocks to paste as separate
-messages risks both landing as one, where everything after the first
-command's name is read as that command's own argument and the second command
-never fires, measured four times out of four.
-A slash command expands as a user invocation only at position zero of a
-prompt, and a later one in the same text reaches the session as prose instead.
-The fix is what the template above already takes: one message, one command,
-at position zero.
-
-### What the brief may carry
-
-The prompt carries pointers and standing context, and stops there. The branch and the plan stay arguments, because a skill resolves an argument through a documented ladder and reads no prose at all. What the prose reaches is the worker's judgment, so it holds only what a session has to weigh:
-
-- Name the addressee and what it is owed, which the two message clauses above already do.
-- Carry standing context this session holds that a cold one cannot derive, such as a constraint settled in conversation that never reached the plan.
-- Leave out anything scope-shaped. A file list, a naming convention, or a check to run belongs in the plan, where the review reads it back against the diff.
-
-The last bullet is the one under pressure, since the dispatch that first proved unattended work possible sent a prompt naming the task file, the likely files, the conventions, and the check to run. It shipped in 874 seconds and touched four files its task never named. Scope that arrives as prose is scope nothing verifies afterward.
-
-Report the dispatch as loudly as the human-launch line it replaces: name the branch, the model, the task, and the session name, so a person reading the transcript can follow what fired without watching it happen.
-
-## Dispatch to address a review
-
-`review-address` is a single pass, not a chain, so a launch naming it
-alone reaches no `role-worker` and takes no role, which owes no message
-either. A replacement session was launched that way once, onto the branch a
-review had already posted findings against, and it answered by posting a
-thread reply and telling its controller nothing. Reach the role directly on
-this launch instead of wrapping a second chain around one skill that has none
-of its own.
-
-The branch already exists here, opened by whatever built it, so this shape
-skips the plan-derived name the build shape resolves above. Take `<branch>`
-off the pull request's own head ref. Enter the worktree the original build
-left on disk, `.claude/worktrees/<slug>/`, with `EnterWorktree`'s `path` form
-when it is still there, or `git worktree add .claude/worktrees/<slug>/
-<branch>` when it was cleaned up, so `<slug>` is that directory name either
-way.
-
-`EnterWorktree` refuses that path in the ordinary case, because the original
-build session stays registered against its own worktree after going idle and
-holds a harness-level lock the roster does not report. Work in the folder
-directly with `Bash`, `Read`, and `Edit` instead of retrying the tool, which
-is the route two workers already took today on two different branches.
-
-```bash
-claude --bg --model <model> -n "worker-<project>-<slug>" "Enter the worktree for <branch> at .claude/worktrees/<slug>/, creating it from that branch if the folder is gone. Run /canon:role-worker, then /canon:review-address. 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 address pass finishes, carrying what was addressed and the PR's CI state, and message it again if you stop on a question."
-```
-
-`<dispatcher-id>`, `<model>`, and `<project>` resolve the same way the build
-shape resolves them above.
-
-Take this shape wherever a review needs answering and no live session already
-holds the branch. Where one does, message it to run `review-address`
-instead, per the loop's own step 6, since a session already there needs no
-second one dispatched onto the same branch.
-
-That check is blind to a session working through the direct-path fallback
-above, since a session that never runs `EnterWorktree` never moves its
-registered branch off `main`, so `canon sessions list --branch` reports nothing
-holding it. A dispatch landing on a branch worked that way collides with
-nothing the check can see.
-
-## Dispatch to plan a row
-
-`plan-feature` is a procedure rather than a role, so a launch naming it alone
-reaches no `role-planner` and takes no role, which owes no message either.
-Both trials of this shape ran on prose the controller retyped into each launch,
-which held every obligation those sessions took and is where the first one's
-in-flight read went wrong. Reach the role directly on this launch, the way the
-build shape above reaches `role-worker`.
-
-No branch and no worktree exist here and none is created. A planner writes one
-gitignored file at the main worktree root, so this shape names the row's task
-file rather than a branch and opens with the role instead of a worktree call.
-That write meets the isolation guard the same way a linked worktree's
-main-root write does, with no worktree here to redirect it to, so
-`role-planner` sends it as a `Bash` heredoc rather than through `Write`.
-
-```bash
-claude --bg --model <model> -n "planner-<project>-<slug>" "Run /canon:role-planner, then /canon:plan-feature <task>. 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 plan lands, carrying the path and what the task file got wrong, and message it again if you stop on a question."
-```
-
-`<task>` is the row's task file path and `<slug>` the slug its plan will take,
-resolved off the row the way the build shape resolves one off a plan.
-`<dispatcher-id>`, `<model>`, and `<project>` resolve the same way they do
-above. The prefix reads `planner-` for the reason the worker's reads `worker-`,
-which is that it marks the role of the session it names rather than the one
-that launched it.
-
-None of the three checks above binds this shape. The branch check has no
-candidate to read, and the disjointness gate has nothing to compare, since a
-planner writes one file no track in flight can hold. The plan-answer gate
-reaches no plan at all, because the planner is dispatched to write the file a
-build would later read, so running it here would refuse every planning dispatch
-over a plan nobody has written yet.
-
-What a planning dispatch owes instead is the reverse reading, because the plan
-it produces carries a constraint per track in flight and a row planned during a
-wave is planned against a tree that wave is changing. `role-planner` composes
-the session roster with the pull request list for that read rather than reading
-pull requests alone, which is why the brief carries no branch list for it: the
-planner takes this reading itself either way.
-
-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.
+Read `${CLAUDE_SKILL_DIR}/references/orchestrator-launch.md` once every check above clears, and launch from its build template. It also holds the review-address and planning shapes, which skip the checks above.
 
 ## Fall back to the human
 
@@ -281,7 +92,7 @@ Hand the row to the human-launch line in step 4 instead of dispatching when any
 
 The first of those five is the one that reaches a person rather than the board. A row held for a collision or for a serialize reason waits on the wave clearing, where a row held on its plan waits on an answer only the operator can give, so hand that one over with the question label and its stated reason attached rather than as a name and a refusal.
 
-Hand the person one command: `/canon:auto-ship <plan>`, naming the row, the plan path, and the branch together, with no worktree call ahead of it. A leading worktree call adds nothing beyond what `auto-ship` Step 0 already reaches for itself, by the same judgment the template above calls a residual risk rather than a settled contract. A second command also risks a client folding two commands into one message, which reads everything after the first command's name as its own argument and drops the second: that happened in four dispatches out of four before the fix became one message carrying the autoship call alone.
+Hand the person one command: `/canon:auto-ship <plan>`, naming the row, the plan path, and the branch together, with no worktree call ahead of it. A leading worktree call adds nothing beyond what `auto-ship` Step 0 already reaches for itself. A second command also risks a client folding two commands into one message, which reads everything after the first command's name as its own argument and drops the second, per `### Position zero` in `orchestrator-launch.md`.
 
 Suggest, as one line to the operator, that they rename their own session to the row's id, so a process listing shows what the session is for without a cross-reference to the board.
 

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

@@ -0,0 +1,22 @@
+---
+title: Orchestrator handback runbook
+description: Addressing the session that answers a posted review, what to report when none is live, and where a worker's reply is placed by what it changes
+---
+
+Read this at loop step 6, once a review pass has posted anything owed and the session holding that branch is to run `review-address`.
+
+## Sending the handback
+
+- Read the threshold off `review-pr`, which states it once and governs the heading with it, so an open heading and an owed dispatch answer the same question and either one is enough to send
+- Resolve the target at the moment of sending with `canon sessions list --branch`, never from a mapping written down earlier, since names rotate as sessions end and one recorded earlier in a session has failed inside the hour. `orchestrator-poll.md` routes on the count and the confidence it answers with
+- Open the message with the worktree and branch the sender believes the reader holds, asking to be corrected, whenever that mapping is inferred rather than confirmed
+- 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 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.
+
+The channel runs both ways and the return leg carries what the pull request cannot. A worker answering a posted finding by naming the plan question that had already declined it changes the outcome in the moment, where a thread comment waits on whoever reads it next. Read what a worker volunteers as part of the review rather than as an aside, and read a refusal the same way, since the corrections that landed on this session's model of the world arrived as a worker arguing back rather than complying.
+
+What the worker owes on its own side is stated in the `role-worker` skill that session loads, being the pull-request announcement, the message a block goes out as before it becomes a prompt, and the ban on writing the board. Do not restate any of it here.
+
+What arrives there does not become a record by being read, so place it by what it changes. An answer that settles a finding goes onto the pull request through the next pass, which withdraws or regrades that finding and names the fact behind it, per `review-pr`. An answer that changes what this session believes about the world instead, which is a mapping correction or a constraint on what a worker can do, settles no finding and reaches no thread, so route it the way `## Boundaries` in the skill body routes a change found while orchestrating, which lands it on the task owning the surface it describes. Writing a tracked file to hold either is forbidden here, which leaves the pull request and the board as the two surfaces this session writes.