@erclx/canon 5.43.0 → 5.45.0

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

@@ -7,113 +7,30 @@ description: What the one warm control session owns, why it plans and dispatches
 
 ## Gap
 
-Without this skill, the session holding the cross-feature picture starts building, and the picture goes with it. Two features land where one depends on the other or consumes a contract the other changes, because nobody read their plans against each other, and the second pull request rebases onto a tree it was never planned against. Findings from a merged pull request stay in a thread nobody re-reads, so the rule they should have changed never changes. Holding on one shared path costs as much, and ran six canvas rows one at a time on 2026-10-04 though no practitioner source serializes on a shared file.
+Without this skill, the control session builds or merges, and the cross-feature picture goes with it. Plans go out unread against each other and a moved tree, the queue empties or fills with whatever is oldest, a parked row's blocker is never re-tested, and a second orchestrator writes a board neither can read.
 
-The queue fails in both directions. It empties and a free worker waits, or it fills with whatever is oldest rather than with what establishes a mechanism. A plan handed over unverified is the quiet one, since it goes stale from whatever merged after it was written, and a worker that trusts its account of the tree builds against a shape that no longer exists. A second orchestrator makes all of this unrecoverable, because the board is gitignored and neither session can read the other's writes.
-
-Refilling on a merge and on a thinning ready list leaves the window between them unwatched. A wave mid-build has merged nothing and has moved no rows, so both conditions stay silent across the whole build and the wave finishes into an empty queue, which lands planning on the critical path directly after the stretch where it would have cost nothing.
-
-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, and a task conflicting 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. 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, 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.
-
-Naming that reader without naming the way in fails on the next axis, and it fails circularly. The command that routes a resume request lives in this body, which is the surface a long session is likeliest to have dropped, and dropping it is the condition the handoff exists to survive, so the session holding a complete handoff cannot reach the runbook that reads it back. The review poll is lost in the same moment and recovered by neither, since it is session-scoped and the resume performs no restart, which leaves a reader who follows the whole handoff with a board and no trigger.
-
-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 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: 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 conflict 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.
-
-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 declared file set does not hold, since a track crosses the set its plan named.
+The channel fails at every hand-off. A finding or a reply stays in a thread nobody re-reads, a dispatch launches a branch other than the one the check cleared, a wave's cost grows unweighed, a report buries the human's decision, and a compaction loses the way back in.
 
 ## Must
 
-- Read the priority file for execution order, since the index sorts by filename and states no order
-- Report the state of play so the human knows what to launch, what to review, and what to merge
-- Verify a plan against the tree before handing it over, counting the sites it claims and opening the files it describes
-- Hold a candidate only on a dependency, a contract, a relocation, a sweep, or a stated reason, since those predict a conflict a merge cannot settle and a shared file does not
-- State what a wave costs in inbound turns beside the conflict 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, and write the board so a row's readiness and hold 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
-- 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
-- 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
-- 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
-- Carry every runbook the session cannot run from memory inside the skill, so each citation resolves for a project holding the plugin and nothing else
-- State which rule wins where the tracked-file ban collides with the root instruction on small edits, and where a correction no open task owns goes
-- State the review trigger as a recurring prompt rather than as one client's command, since the runbook ships to targets running whatever client they run
-- Read the handoff or the resume runbook when the human asks for that side of a compaction, since the request is the only signal available for a moment the loop cannot detect
-- Re-test every parked row's blocker against the current tree on request, since every refill trigger looks forward and none of them re-reads a row already waiting
-- Measure a condition the way the code consuming it defines the shape, and settle which tree the condition is about before counting, since both errors return a number rather than a failure
-- Write each re-test into the row and its measurement into that task's Findings, since a result reported in chat is gone at the next compaction and the next pass measures the same thing
-- Plan a row the re-test clears, since a cleared row carrying no plan is one the next pass looks at again
-- Split a task that conflicts with every other by construction, rather than re-measuring a scoping defect that reads as a blocker
-- 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 a candidate sharing only files with a track in flight and name the shared paths, and have the branch merging second resolve after the first merges, since every source the gate cites tests at integration
-- Write a stated reason on the hold it makes, since two tracks interact in ways no plan reading shows
-- 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
-- Launch a planner or worker the operator will talk with from the talk shape, with the `-talk` suffix and the brief sentence that tells it so, since a cold launch retires the session the moment its delivery lands while the operator still wants the conversation
-- Retire a talk session only on the operator's word and report it as held open until then, since its delivery says nothing about whether the conversation is over
-- Dispatch every non-release pull request's review to `role-reviewer`, leave each round's messages to it and the worker, and keep one cross-branch pass per wave here, since any pass or relay run here bills the context the wave shares
+- Every plan is verified against the current tree and names each in-flight track's file set, and a candidate holds only on a dependency, a contract, a relocation, a sweep, or a stated reason
+- One planned, non-conflicting task stays in reserve, refilled while a wave builds, and every parked row's blocker is re-tested against the current tree with the result written to the board
+- A finding or a reply lands on the surface that owns it, the pull request or the task, rather than in chat
+- A dispatch launches the branch the check cleared under a `worker-` name carrying this session's `sessionId`, hands review to `role-reviewer`, and states what the wave costs in inbound turns
+- A report and the pre-compact handoff lead with state, open decisions, and next action, the handoff carries its own resume invocation and poll restart, and every runbook ships inside the skill
 
 ## Must not
 
-- Implement a feature or edit any tracked file from this session, at any size, since the ban offers no proportionality exception
-- Merge. Recommend merge or changes and leave the gate to the human.
-- Spawn a worker with the Agent tool, since an in-process subagent shares this session's context and cannot be steered or reached independently. A dispatched `claude --bg` process is not this: it is a separate session with its own worktree and its own PR, gated by the branch check and the conflict check.
-- Hand a worker anything but a plan, because scope lives there
-- Name a count of the defect's extent or the mechanism behind it while filing a row, since this seat measures a defect from where it stands and the planner is the reader who commits to that scope. A blocker re-test, a branch check, and a conflict check decide whether a row can start rather than how big it is, and they stay.
+- Implement, edit any tracked file at any size, or merge
+- Spawn a worker with the Agent tool, or hand a worker anything but a plan
 - Run a second orchestrator against the same board
-- Promote a task to fill the queue when nothing qualifies. A thin queue is a real answer.
-- Promote a parked row on how long it has waited, since age is not a measurement of the blocker
-- Schedule the parked-row pass on a recurring loop, since the review poll owns the one recurring trigger this skill has and a second loop fires into a static board
-- Rewrite the board with a shell stream editor or an inline string replace, both of which exit clean when they match nothing
-- Restate the board, a task file, or a groundwork folder in the pre-compact handoff, which is the padding that makes a handoff stop being read
-- Specify a shape for a correction, since a format for admitting error invites ceremony where plainness is the whole value
-
-## Guards
-
-- Priority file absent: report the queue and say the order is unrecorded rather than inferring it from the index
-- Cross-version sequencing asked for: say no surface carries it, rather than asserting an active version the tree does not state
-- This body dropped from a long session approaching a compaction: name the re-invocation and the runbook paths, since the routing lives in the body and a user-invoked skill routes nothing once it is gone
-- Blocker only an operator can clear: record the row as untestable this pass and name the action owed, rather than re-measuring what no session can move
-- Branch check refuses, with no session registry or no repository resolved: treat the candidate as unverified and fall back to the human-launch line, rather than reading a check that could not run as a clear one
-- Candidate holds under the conflict check: leave the row ready and name the hold, rather than dispatching onto a contract still moving
-- Talk session the client renamed after launch: find it by the `sessionId` recorded in the map, since the `-talk` suffix is display only and a rename can drop it
-- Operator states a cap for the session: honor it for that session alone, rather than treating it as a standing rule or writing the number into a file
+- Promote a row to fill the queue when nothing qualifies, or on how long it has waited
+- Rewrite the board with a stream editor or a string replace that exits clean on no match
 
 ## Out of scope
 
-- Writing the plan itself, which `plan-feature` owns and this session runs rather than reimplements
-- Reviewing a worker's pull request, which `review-pr` owns, and the bounds of a reviewer dispatched to run it, which `role-reviewer` owns
-- Entering the worktree a build runs in, which the worker opens for itself whether a human launched it or this session dispatched it
-- The worker's half of the channel and the boundaries a building session holds, which `role-worker` states where that session reads them
-- The operating model this enacts, which the toolkit's own docs hold
+- Writing the plan itself, which `plan-feature` owns
+- Reviewing a worker's pull request, which `review-pr` and `role-reviewer` own
+- Entering the worktree a build runs in, which `session-worktree` owns
+- The worker's half of the channel and its boundaries, which `role-worker` owns
+- Resuming a session with no board behind it, which `session-resume` owns

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

@@ -3,7 +3,7 @@ title: Orchestrator dispatch runbook
 description: The plan-answer gate, the collision check before a self-dispatch, the conflict check against the tracks in flight and the evidence it rests on, the branch the launch names, the one model test applied to each role, 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 conflict check below is where that row is tested against every track in flight, and it is the one statement of what holds a row there.
+Run this at loop step 4, for a `## Up next` row whose plan is verified, in place of handing the worktree to a human. The conflict check below is where that row is tested against every track in flight, and it is the one statement of what holds a row there.
 
 ## Contents
 
@@ -40,6 +40,7 @@ Never shorten a non-conforming slug here, since a rename parts the branch from t
 
 Run `canon tasks plan-answers <plan> --json` and read `launchable` off the record. Branch on `launchable` rather than on the exit code, which a wrapping shell function can flatten to zero and so read a held row as clear.
 
+- Hold a row whose `Waiting on` has not cleared, which no other check reads
 - `launchable: true`: the plan answers itself, so proceed to the branch check.
 - `launchable: false`: report every entry in `open`, each with its question label and stated reason, and hand the row to the human-launch line below
 - Never fill the slot on the operator's behalf, the one move the plan standard forbids outright
@@ -152,6 +153,8 @@ A row qualifies for that pick when its plan carries no open question and touches
 
 Read `${CLAUDE_SKILL_DIR}/references/orchestrator-launch.md` once every check above clears, and launch from its build template, which sits beside the review-address and planning shapes that skip these checks. A cloud row launches from `${CLAUDE_SKILL_DIR}/references/orchestrator-cloud-launch.md`, since the VM shares no plugin or board.
 
+Once the launch succeeds, run `canon tasks promote <stem>`.
+
 ## Fall back to the human
 
 Hand the row to the human-launch line in step 4 instead of dispatching when any of these hold, and name which one. A shared file alone is not listed.
@@ -171,4 +174,4 @@ Hand the person one command, `/canon:auto-ship <plan>`, naming the row, the plan
 
 ## Stop the loop
 
-Wrapped in `/loop`, re-run the check against `## Run now` on each wake, and stop once the group is empty or every row reads `claimed: true`. Report that once, on the wake that finds it, rather than polling a board nobody is clearing, the reasoning `orchestrator-poll.md` carries for the review trigger.
+Wrapped in `/loop`, re-run the check against `## Up next` on each wake, and stop once the group is empty or every row left in it is held. Report that once, on the wake that finds it, rather than polling a board nobody is clearing, the reasoning `orchestrator-poll.md` carries for the review trigger.

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

@@ -55,7 +55,7 @@ Every measurement this pass takes decides whether a row can start rather than ho
 
 Write the result into the row, since a re-test reported in chat is lost at the next compaction and measured again.
 
-- Rewrite a blocker cell whose test no longer holds, and move the row to the group its new state puts it in
+- Rewrite a blocker cell whose test no longer holds through `canon tasks block <stem> "<blocker>"`, and move the row to the group its new state puts it in through `canon tasks place`
 - Record the measurement in the task's `## Findings` as a line labeled with this session and the date, per `${CLAUDE_SKILL_DIR}/../task-board/references/tasks.md`
 - `### Writing the board` in `role-orchestrator` owns the method, and `canon tasks validate` runs once the board is rewritten and before the report
 
@@ -69,7 +69,7 @@ A backlog row carries no blocker cell, since `${CLAUDE_SKILL_DIR}/../task-board/
 
 ### Moving a cleared row
 
-A cleared row moves out of `backlog.md` onto the bottom of `## Needs a plan`, with a `Waiting on` cell stating what changed and ending with the word `last`.
+A cleared row moves out of `backlog.md` onto the bottom of `## Needs a plan` in one call, `canon tasks place <stem> --group needs-a-plan --bottom --waiting "<what changed>. Last"`.
 
 - `canon tasks validate`'s ordering check reads `last` as the ordinal the bottom placement claims
 - A cell stating only what changed matches neither the ordinal nor the rank reading, raising a finding against the pass's own row

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

@@ -25,7 +25,7 @@ The third trigger reaches a window the first two cannot. A session with three wo
    - Run `task-complete` to archive one the hook left in place
    - A task whose outcomes are standing policy never closes, so hand it to a worker to encode the policy where it is enforced, then cut the outcomes with the reason and archive once that branch merges
    - Encoding it from this session would write a tracked file, which `## Boundaries` in the skill body 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.
+4. Read `.canon/tasks/priority.md` and count the `## Up next` rows whose `Waiting on` has cleared, since a blocked row is no reserve. `## Run now` is what is running, so keep one in reserve beyond it.
 5. Promote from the top of `## Needs a plan`, where the last sweep recorded what to plan next.
    - Depart from that order when something changed under it and say what, since a position nobody honors is the ordering going stale
    - The order is set by whether a task establishes functionality, so prefer one that adds or proves a mechanism over one that trims, tidies, or audits
@@ -53,27 +53,32 @@ That block is the detail. Lead the reply with the three slots under `## Every la
 
 ## 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.
+Write `.canon/tasks/priority.md` through the `canon tasks` verbs alone, each reading the file once, rendering every table, and writing it once. Beside this session, `canon tasks archive` drops a shipped row and `plan-link` promotes a parked one.
 
-- Edit with the file-editing tool, which errors on a non-match, where a shell stream editor or an inline replace exits clean and leaves the board wrong
-- Write both halves of a move before reporting it, since a row on neither surface leaves a task file nothing names in a gitignored folder with no history
-- `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, since a row promoted with the cell left alone carries an order the next sweep cannot check
+| Move                                      | Verb                                                       |
+| ----------------------------------------- | ---------------------------------------------------------- |
+| A backlog row onto the board, or across   | `canon tasks place <stem> --group <group> --waiting "..."` |
+| A planned row to `## Run now` on dispatch | `canon tasks promote <stem>`                               |
+| A row up or down inside its group         | `canon tasks move <stem> --before <stem>`                  |
+| What a row waits on, or why it sits there | `canon tasks block <stem> "<reason>"`                      |
+
+- `place` removes the task's backlog line in the same call, so a row never sits on both surfaces or on neither
+- Demoting a row to `backlog.md` has no verb yet. Add the backlog line first, then delete the row with the file-editing tool, which errors on a non-match.
+- Put the reason a row sits where it does in its Waiting on cell through `block`, since a row promoted with the cell left alone carries an order the next sweep cannot check
+- Run `canon tasks validate` after any move, which reports a hand edit the verbs would have refused
 
 ### Columns and read-back
 
-Each column carries a fact a later reader checks rather than reasons again.
+The verbs derive the Task, Touches, and Plan cells from the task file and its live plans, so a later reader checks them rather than reasoning again.
 
-- Put a pointer in the Plan column, never prose, since `auto-ship` refuses at its guard when the column leads to no plan, spending a dispatch
-- `## Run now` claims a written plan covers every open outcome, which is what the pointer backs
-- Name the file set in the Touches column, which feeds the merge order and the shared paths a dispatch names, so step 6's hold call stays checkable later
-- 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
+- `place` and `promote` refuse a row the target group's test fails, so a Plan cell never leads `auto-ship` to no plan and spends a dispatch
+- A Touches cell differing from its plan's list is `touches-stale`. Change the plan's list rather than the cell, and step 6's hold call reads the result.
+- Read the board back after a write, since the row that lands is the row a worker acts on
 
 ### Stale plan pointers
 
 A Plan pointer goes stale from a merge this board never sees. The `post-merge` hook moves a plan to `.canon/plans/archive/` through `canon tasks archive` and rewrites the citation in the archived task file alone.
 
-- A row for a task still on the board keeps pointing into `.canon/plans/` at a file that has moved
+- A row for a task still on the board keeps pointing into `.canon/plans/` at a file that has moved, until the next verb call re-derives every Plan cell from the live plans
 - `task-complete` marks outcomes on each worker's branch and moves nothing, so the move lands at the merge
 - The board then reads as correct until a pointer is followed

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

@@ -7,87 +7,29 @@ description: What a thinking session is across planning, groundwork, and intake,
 
 ## Gap
 
-Without this skill, a planning session is told what to plan and never what it
-is. `role-worker` states the building role and `auto-ship` Step 0 reaches
-it on every build, so a builder takes a role whether a person launched it or a
-dispatcher did. Planning has no equivalent, and two trials on 2026-08-31 ran
-entirely on prose the controller retyped into each launch. That is the shape
-`role-orchestrator` already bans on the building side, where one half held the
-only written copy of obligations the other half performs.
+Without this skill, a planning, groundwork, or intake session is told what to plan and never what it is. Every launch retypes the role's rules, and the forgotten one fails. The session counts worktrees and branches as in flight though a squash merge leaves both behind, and it quotes a row's stale count instead of opening the source.
 
-Six rules went into each of those launches by hand: no worktree, no branch, no
-tracked file, no board write, report the path alone, and re-measure rather than
-trusting the task file. A seventh was added only after a trial got it wrong.
-Every one of them is a property of the role rather than of the row, so each
-dispatch reproduced them from memory and the one nobody remembered was the one
-that failed.
-
-The in-flight read is that failure. The first trial counted worktrees and local
-branches and named four branches as in flight, all four of which had merged,
-because this repository squash-merges and leaves both behind. A corrected brief
-naming `gh pr list` as the source closed it and no constraint in the second
-batch was wrong, which puts the fix in a launch string that the next dispatch
-has to remember to carry.
-
-Measuring rather than trusting the row is the other half and it is what the
-trials were strongest on. Across four plans the planner reported ten things the
-task files got wrong, and one plan overturned its own row's closing conclusion.
-Nothing in any skill body tells a planner to open the source rather than quote
-the row, so a session that skips that read produces a plan built on the same
-stale count the row already carried.
-
-A planner reading the board sees blockers and file sets and can write a
-confident merge order off a partial picture. Which rows collide, what merges
-before what, and whether a row should run at all stay with the controlling
-session, and no body states that boundary for the planning side.
-
-Nothing scans a plan for ban hits either. `.gitignore` ignores
-`.canon/plans/`, and the audit's default path set is what git lists, so no gate
-ever opens one. Six ban hits landed across the four trial plans and three of the
-four carried at least one, caught only because the planner ran
-`canon markdown audit` unprompted.
+It also reaches past its seat. A planner reading blockers and file sets writes a merge order off a partial picture. Its plans land in a gitignored folder no gate audits, and the controller learns nothing of what the row got wrong unless the planner says so.
 
 ## Must
 
-- Assert what a thinking session is, what it may not write, and how long the role lasts, since `plan-feature`, `plan-groundwork`, and `plan-intake` each carry their own procedure and no body carries the role the three share
-- Cover all three of those skills rather than `plan-feature` alone, since a groundwork or intake session took no role at all while the body was written for one plan under one task
-- State the writes-records-never-source boundary once, and name the three folders in one line while deferring each scope's exceptions to the skill that owns it, so a change to one scope edits one body
-- Carry `plan-groundwork`'s close-time task file as an exception to the board ban, since widening the role without it makes the role forbid what that skill requires
-- State the in-flight read as a command composing the session roster with open pull requests, and say that a branch and a worktree are not evidence, since a count of either reported merged work as live
-- Run that read once per task rather than once per batch, since a reused session ages its picture of the tree while it works
-- Name every read a plan needed and a launch string did not carry, the task file's findings and the source files among them, since a count quoted from a row was wrong or stale in ten places across four plans
-- Name the validate and audit calls the written plan passes through, since nothing else opens a plan and the audit caught ban hits in three of four trial plans
-- State the shared board as read-only and name the cross-feature call as the controller's, since a planner reading blockers and file sets can write a merge order off a partial picture and will not notice that it has
-- Owe an announcement when the record lands, carrying the path and what the row got wrong, since the controller cannot watch the read happen
-- Owe a message before a block becomes an interactive prompt, since a session already waiting on input never reaches the tool round an inbound message drains at
-- Keep correcting the dispatcher a first-class move carrying its evidence, since a trial corrected a brief's premise, planned every row anyway, and carried the consequence into a plan question
-- Carry a talk clause for a launch whose operator is in the session, putting each open question to them, recording a settled pick in place, sending an ask about a row now building to the controller rather than the worker, and owing a close message when they end the conversation, since a cold planner's halting rules contradict a brief that asks it to talk
-- Point at each of the three skills for its record's shape and the steps that write it
-- Defer the addressee resolution to `session-relay` and keep only the last-rung inference, which discriminates differently here than it does for a worker because a session in this role holds no feature branch either
+- One role covers `plan-feature`, `plan-groundwork`, and `plan-intake`, writing records and never source, with each scope's exceptions left to its own skill
+- The in-flight read composes the session roster with open pull requests once per task, and never counts a branch or a worktree as evidence
+- A plan rests on the task file's findings and the source files rather than on counts quoted from the row
+- Every record passes the validate and audit calls before it is announced, and the announcement carries the path and what the row got wrong
+- A block goes out as a message before it becomes a prompt, a correction to the dispatcher carries its evidence, and a talk launch puts each open question to the operator
 
 ## Must not
 
-- Restate a record's sections, its suggested-and-answer contract, or the steps the running skill carries, since thinness is what keeps one body correct for a dispatched session reading it as its whole contract
-- Restate the write-scope exceptions each of the three skills states about its own folder
-- Restate a boundary `role-orchestrator` or `role-worker` states about itself
-- Tell a planner to halt on a plan question, which the suggested line already answers, rather than on what blocks writing the plan at all. A talk launch is the exception, since putting the question to the operator in the session is its job.
-- Tell a planner to report the path with no account of what the row got wrong. That instruction came from a trial condition holding a blind comparison intact, and it is not a durable obligation.
-- Report progress through the channel, which rebuilds on the sender's side the poll the announcement exists to retire
-- Write the priority board or the backlog, at any size, or the task file outside `plan-groundwork`'s close-time exception
-- Be a skill nothing invokes but its author typing the name. `orchestrator-launch.md` names it on the planning launch the way it names `role-worker` on a build, so a stretch where only a typed invocation reaches it is the signal that the role never took.
-
-## Guards
-
-- Task file does not resolve from where the session stands: report it unreadable and name the main-root path, rather than reporting the row as absent
-- A read of what is in flight returns nothing: report that no pull request is open and no live session holds another branch, rather than falling back to a raw branch or worktree count
-- Launch named no controlling session and an operator is present: ask which row to address rather than inferring
-- Launch named no controlling session and nobody is present: infer from the sessions holding no feature branch, never from a name prefix, and say the addressee was inferred
+- Write the priority board or the backlog, or a task file outside the close-time exception `plan-groundwork` states
+- Decide which rows run or in what order
+- Restate a record's sections, its answer contract, or the steps the running skill carries
+- Halt on a plan question the suggested line already answers, outside a talk launch
+- Report progress through the channel
 
 ## Out of scope
 
-- Each record's sections and its answer contract, which the standard behind it fixes, and the steps that write the file, which `plan-feature`, `plan-groundwork`, and `plan-intake` each own for their own
-- The write-scope exceptions, which stay in the three skills: groundwork's close-time task file, its fixture and evidence paths, and intake's statement that it has none
-- The mechanical addressee resolution, which `session-relay` owns for every session with or without a role
+- Each record's sections, answer contract, write-scope exceptions, and writing steps, which `plan-feature`, `plan-groundwork`, and `plan-intake` own
+- Resolving an addressee, which `session-relay` owns
 - The branch, the build, and the pull request, which `role-worker` and `auto-ship` own
-- Deciding which rows run and in what order, which is the controlling session's call and stated in `role-orchestrator`
-- The dispatch itself, its collision check, and its conflict check, which `orchestrator-dispatch.md` holds
+- Choosing which rows run, their order, and the dispatch with its collision and conflict checks, which `role-orchestrator` owns

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

@@ -72,7 +72,8 @@ The plan standard fixes that block for a feature plan, and a groundwork or intak
 
 ## The board is read-only
 
-- Never write `.canon/tasks/priority.md` or `.canon/tasks/backlog.md`. Both are gitignored, so an overwrite drops a row with no history to recover it from.
+- Never write `.canon/tasks/priority.md` or `.canon/tasks/backlog.md` by hand. Both are gitignored, so an overwrite drops a row with no history to recover it from.
+- `canon tasks plan-link` is the one board write this role makes. It moves the row out of `## Needs a plan` once the plan is linked, in one read and one write a hand edit cannot match.
 - Never write the task file. The record is the whole output, and a row edited from here changes what the controller reads back as the board's state.
 - Report what the row got wrong rather than repairing it, such as a stale count or a dead path, in the record and the handback. The controller decides which carries the correction.
 - Leave the cross-feature call alone. `priority.md` shows enough to write a confident merge order off a partial picture, which is the failure this boundary prevents.

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

@@ -7,58 +7,30 @@ description: What a building session is, the shared surfaces it may not write, a
 
 ## Gap
 
-Without this skill, a building session is told what to do and never what it is. One shipped body asserts a session role and it is the orchestrator, so worker behavior spreads across three skills that each own a step and none of them names the role or the channel it runs on. The handback works because a session reading plain text tends to follow it rather than because anything says it should, which held while a person launched every worker and stopped holding the first time one ran with nobody watching.
+Without this skill, a building session is told what to do and never what it is. It writes shared surfaces, hand-writing the board from a stale copy, filing a task with no row, or re-drafting a readied pull request. From a linked worktree it finds no plan folder and reports the task has no plan.
 
-The session then writes surfaces nothing told it were shared. One worker split a concern its own run could not reach, hand-wrote the priority board from a copy taken minutes earlier, and reverted a promotion with nothing reporting it, on a board that still validated afterwards because a reverted row is a well-formed board. A second added a row and labelled it with an identifier another row already held. The rule against both sits inside the controlling session's own body, which no worker loads.
-
-Standing in a linked worktree fails one step earlier and reports confidently while it does. The plan folder is gitignored, so `git worktree add` never creates it, and a worker reading it from the build tree reports that the task has no plan. That is true from where the session stands and wrong about the world, and a reader holding no second tree cannot tell those apart. Three workers hit it in one day and an absolute path unblocked all three.
-
-A blocked worker reaches nobody at all. Two dispatched sessions opened an interactive prompt inside a background session no operator was attached to, and the roster read both as alive throughout. An answer relayed afterwards arrives and does not land, since a queued message drains at the next tool round and a session waiting on input never reaches one, so the channel closes the gap only when it is used before the prompt opens. One of the two held uncommitted work across three files, which made stopping and relaunching a destructive recovery rather than a free one.
-
-Finishing is invisible from the other side. A worker that opens a pull request goes idle rather than exiting, so the one push signal available fired for a worker that was stopped and never fired for the one that finished, which then sat unnoticed for eighteen minutes. Polling covers that interval by spending a fixed cost against a worker with no pull request to report, measured as five consecutive runs reporting no movement across roughly fifteen minutes while one worker built.
-
-Nothing tells the session that refusing is allowed either. Four occasions across two days had a worker halt correctly with the cost falling on the dispatcher, and the correction that mattered most reached the right place because a worker argued back with evidence rather than complying. A role written only as report-upward suppresses exactly that.
-
-The draft mark fails from both ends. On 2026-08-31 four sessions re-drafted a pull request someone had readied, acting on a belief no surface in the tree stated. On 2026-09-07 a controlling session told a worker to lift the mark rather than lifting it itself, and the worker complied and reported against the surface rather than the outcome. From 2026-10-12 `canon pr lift` reads the gates itself, so the reviewers run it on a close and the controlling session runs it as the fallback. A worker leaves the verb to them and readies a pull request directly for nobody, since a direct ready skips every gate the verb reads.
+The channel fails on the worker's side. Blocks open prompts nobody is attached to, and a finished pull request goes idle unannounced or stalls silently on its reviews. Painted ones ship with no address for the UI reviewer. Late asks widen the reviewed scope, and a worker told only to report upward never argues back.
 
 ## Must
 
-- Assert what a building session is, what it may not do, and how long the role lasts, since the three step-owning skills each carry a procedure and none carries a role
-- State that session scratch resolves at the main worktree root, since a linked worktree holds none of those folders and their absence reads as a missing artifact rather than as a wrong vantage
-- State the shared board as read-only for a building session and name what it does instead when a row is owed, since a task file with no row is a dropped task and placing the row is the controlling session's call
-- Owe an announcement the moment the pull request opens, carrying the number, the branch, and the task, since that transition is the one interval only the worker can observe
-- Carry a row the build turned up in the pull request announcement, and send it alone only when the session ends before a pull request opens, since the worker files no task file of its own and the channel is the row's only route
-- Carry a fan-in member's branch and head commit in its done message in place of a pull request number, and end its role at the push, since a member opens no pull request and its integrator fixes what the merge surfaces
-- Send the controller the `canon pr review-state` record when a wait for the reviews times out, rather than waiting on, since a worker improvising that read stalled silently with both reviewers idle behind it
-- Owe a message before a block becomes an interactive prompt, since a session already waiting on input never reaches the tool round an inbound message drains at
-- Defer the addressee resolution to `session-relay` and keep only the operator ask and the last-rung inference, which discriminates here because a worker holds a feature branch and a controller does not, and which falls back to the roster and says so, since an operator's own launch names nobody
-- Keep refusing a dispatcher a first-class move carrying its evidence, since the halts measured so far were correct and the cost of each fell where it belonged
-- State that a held body may be older than the branch under it, since a plugin skill loads from the marketplace cache rather than from the working tree
-- Carry a talk clause for a launch whose operator is in the session, asking them at a judgment call and sending a close message when they end the conversation, since a cold worker's halt-toward-the-controller and merge-ends-the-role rules contradict a brief that asks it to talk
-- Freeze the plan's scope at dispatch, sorting a late ask into a defect to fix, a follow-up row to report, or an addition the operator's word admits with its re-review cost stated, since intake 155 measured about four UI review rounds on one pull request from late asks, each re-running both reviews
-- Own the local preview server for a painted diff, started as a tracked background command before the pull request opens, since a `no-server` read leaves the evidence comment and the UI reviewer without an address on the one path nobody watched being built (erclx/frameboard#1 and erclx/frameboard#4)
-- Point at `session-worktree`, `auto-ship`, and `review-address` for the steps each already owns
+- Session scratch resolves at the main worktree root, and a plan that fails to resolve is reported unreadable from there rather than absent
+- The pull request announcement carries the number, the branch, the task, the reach, and any row the build turned up, and a painted diff has its preview server running before the pull request opens
+- A block goes out as a message before it becomes a prompt, a fan-in member's done message carries its branch and head commit, and a review wait that times out reaches the controller
+- The plan's scope freezes at dispatch, and a late ask is sorted into a defect, a follow-up row, or an addition on the operator's word
+- A refusal of an instruction the tree contradicts carries its evidence, and a talk launch puts its judgment calls to the operator in the session
 
 ## Must not
 
-- Restate a procedure any of the three step-owning skills carries, since thinness is what keeps one body correct for a dispatched worker reading it as its whole contract and for a hand-launched one reading it beside a person
-- Restate a boundary the orchestrator already states about itself
-- Report progress through the channel, which rebuilds on the sender's side the poll the announcement exists to retire
 - Write the priority board or the backlog, at any size
-- Create a task file for work the build turns up, through `task-board` or by hand, since the file lands with no row and the placement is not the worker's to make
-- Be a skill nothing invokes but its author typing the name. `auto-ship` Step 0 invokes it on every build, dispatched or hand-launched, so a stretch where only a typed invocation reaches it is the signal that the role never took.
-
-## Guards
-
-- Plan path does not resolve from inside the worktree: report it unreadable from here and name the main-root path, rather than reporting the task as having no plan
-- Plan carries a suggestion written as needing the operator's call: halt and message, rather than answering it
-- Launch named no controlling session: resolve from the roster, address the match, and say the addressee was inferred
-- No live session holds the other end: report what would have been sent and stop, rather than retrying or waiting
+- Create a task file for work the build turns up
+- Ready the pull request directly, or re-draft one someone readied
+- Report progress through the channel
+- Restate a procedure `session-worktree`, `auto-ship`, or `review-address` carries
 
 ## Out of scope
 
 - Entering the worktree, which `session-worktree` owns
 - The chain from implement through pull request, which `auto-ship` owns
-- How the build moves through the plan, slice by slice with a commit each, which `build-in-slices` owns
+- Moving through the plan slice by slice, which `build-in-slices` owns
 - Answering a posted review, which `review-address` owns
-- The controlling session's half of the channel, the review poll, and the watch beside it, which `role-orchestrator` and its runbooks hold
+- The controlling session's half of the channel and the review poll, which `role-orchestrator` owns

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

@@ -51,6 +51,15 @@ A painted pull request needs a server in this worktree for `canon pr local` to f
 
 A hand-run `git-ship` or `git-pr` starts no server, since only a worker has a lifetime to own one.
 
+### Building against a design reference
+
+A plan carrying a `**Design references:**` section names the accepted design for the surface it changes. Open it before building, since the build matches it and a worker that reads the dark image alone ships a light theme nobody saw.
+
+- Open each cited folder's light and dark images and its frame HTML before the first edit to that surface
+- Take sizes, spacing, and colors from the frame HTML rather than from the image
+- Report a reference that does not resolve in the working tree, naming the path, rather than building without it
+- Leave `None identified.` as it stands and build without a reference
+
 ## Scope after dispatch
 
 The plan is the scope from the dispatch on. A late ask restarts both reviews, and one pull request took about four UI review rounds from asks that arrived mid-build.

package/claude/skills/script-screencast/REQUIREMENT.md

@@ -0,0 +1,40 @@
+---
+name: script-screencast
+description: Why a recording script ships pre-seeded rather than blank, what the four discovery questions buy, and why the draft stays stack-agnostic
+---
+
+# Script screencast requirement
+
+## Gap
+
+Without this skill, a recording plan arrives as a wall of blank fields, so the user fills a template instead of editing a draft and the work the skill was meant to do lands back on them. The opposite failure costs more. A session that skips discovery guesses the audience, the length, and the hero moment, then writes five beats for a video nobody asked for, and every one of them has to be thrown away rather than edited.
+
+A draft that names the recording software, the editing software, or the window manager pins the script to one machine and one person's setup, so it stops being reusable the moment anyone else records. And re-invoking to refine silently overwrites the edits the user made in the file, which is the one failure that destroys work rather than wasting it.
+
+## Must
+
+- Read project context and recent commits before proposing, since what shipped recently is usually the subject
+- Ask exactly four discovery questions, each carrying a default derived from that context
+- Wait for answers rather than reading silence as acceptance
+- Pre-seed every section with concrete content so the draft is shippable as written and the user edits down
+- Derive the slug from the topic and the discovery answers
+- Write to `demos/<slug>/beats.md` at the project root, the committed folder the rest of the demo lives in, and print that path on its own line
+- Seed a wrap section naming intro, outro, and music with a default each, so the choice of what surrounds the take is made at draft time rather than discovered at compose time
+
+## Must not
+
+- Name recording software, editing software, fonts, or window managers
+- Record, edit video, or generate captions
+- Re-run against an existing draft to refine it, since re-running overwrites
+- Infer the hero moment without asking, which is the beat the whole script is built around
+
+## Guards
+
+- No topic provided: stop rather than guessing what is being recorded
+
+## Out of scope
+
+- Producing the recording, which `record-screencast` owns
+- Refining an existing draft, which is a direct edit of the file
+- Slide decks, which `make-deck` owns
+- Where the recording ships, which the draft lists and the user decides