@erclx/canon 5.37.0 → 5.39.0

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

@@ -8,20 +8,9 @@ metadata:
 
 # Role orchestrator
 
-This session is the orchestrator: the one warm session that holds the
-cross-feature picture. It plans and dispatches every review.
+This session is the orchestrator, the one warm session holding the cross-feature picture. It plans and dispatches every review. Cold workers build, dispatched once the branch is unclaimed and no conflict holds the row or launched by the human otherwise, and the human merges.
 
-It does not build, and it does not merge. Building happens in cold worker
-sessions, dispatched by this skill once the branch is unclaimed and no conflict
-holds the row, or launched by the human when either fails. Merging is the human's gate.
-
-This skill holds the framing, the board procedure, and the dispatch. Every step
-that builds something runs an existing skill. The queue rules below decide which
-one runs and when.
-
-Run `canon docs operating-model` for the model this skill enacts: the two roles
-and what each owns, the loop end to end, why a dispatched reviewer's pass is
-the first one a change gets, and how a feature is sized.
+This skill holds the framing, the board procedure, and the dispatch, and every building step runs an existing skill. Run `canon docs operating-model` for the model it enacts, being the two roles, the loop end to end, why a dispatched review comes first, and how a feature is sized.
 
 ## On invocation
 
@@ -35,23 +24,38 @@ Read the board in parallel, resolving the paths at the main worktree root the wa
 
 Then output the state of play so the human knows what to launch, review, and merge.
 
-`priority.md` is the ordering source. `index.md` sorts by filename and says nothing about order, so read the sequence from the first and never infer it from the second. When `priority.md` is absent, report the queue and say the order is unrecorded.
+### Reading the order
+
+`priority.md` is the ordering source. `index.md` sorts by filename and says nothing about order, so never infer the sequence from it. When `priority.md` is absent, report the queue and say the order is unrecorded.
+
+- Row position under `## Needs a plan` is what gets planned next, top first, per `${CLAUDE_SKILL_DIR}/../task-board/references/board.md`
+- `backlog.md` is explicitly unordered, so read it for what exists and never as a queue. Report a count rather than its rows, which would put the length back in front of the reader.
+- That count says nothing about whether each row still belongs. `references/orchestrator-parked.md` re-tests a backlog row's currency, on its own trigger below.
+
+### What the board does not say
 
-Row position under `## Needs a plan` is what gets planned next, top first, per `${CLAUDE_SKILL_DIR}/../task-board/references/board.md`. `backlog.md` carries what nobody is scheduling and is explicitly unordered, so read it for what exists and never as a queue. Report a backlog count rather than its rows, since listing them puts the length back in front of the reader the cut took it away from. This read reports how many rows exist and nothing about whether each still belongs there. `references/orchestrator-parked.md` is what re-tests a backlog row's currency, on its own trigger below.
+No surface carries cross-version sequencing, so report none, since reasoning spanning several rows reaches this session only through whoever remembers it. Say nothing about an active version, which nothing in the tree states.
 
-No surface carries cross-version sequencing, so report none. A row's `Waiting on` cell states why that row sits where it does, and reasoning spanning several rows reaches this session only through whoever remembers it. Say nothing about an active version, since nothing in the tree states one and a version asserted from the board is the unsourced claim this omission exists against.
+## Runbooks on request
 
-A compaction is a moment this skill cannot detect, so the human asks for each side of it and this skill reads the matching runbook when they do.
+A compaction is a moment this skill cannot detect, so the human asks for each side of it and this skill reads the matching runbook.
 
-On a request to write the handoff or save the session, read `${CLAUDE_SKILL_DIR}/references/orchestrator-handoff.md` and follow it. It sends the generic half to `canon:session-map`, which writes a session map per `${CLAUDE_SKILL_DIR}/../session-map/references/session.md`, then adds the decisions taken under delegated authority as this role's extension. A lesson about how to work goes to the owning task's Findings. Write nothing to the handoff that the board, a task file, or a groundwork folder already carries.
+- On a request to write the handoff, follow `${CLAUDE_SKILL_DIR}/references/orchestrator-handoff.md`. It sends the generic half to `canon:session-map` and adds decisions taken under delegated authority.
+- That map follows `${CLAUDE_SKILL_DIR}/../session-map/references/session.md`. Write nothing to the handoff that the board, a task file, or a groundwork folder already carries.
+- A lesson about how to work goes to the owning task's Findings, as a bold-labeled line per `${CLAUDE_SKILL_DIR}/../task-board/references/tasks.md`
+- On a request to resume after a compaction, read `${CLAUDE_SKILL_DIR}/references/orchestrator-resume.md`, which reads that file back with the board and the groundwork behind the live work
 
-On a request to resume after a compaction, read `${CLAUDE_SKILL_DIR}/references/orchestrator-resume.md`, which reads that file back with the board and the groundwork behind the live work.
+### The poll and the parked rows
 
-The review trigger takes the same shape. `references/orchestrator-poll.md` holds the loop prompt and the condition under which the poll runs, and `scripts/poll.ts` is what the prompt invokes. A session holding a recurring-prompt scheduler starts and cancels that loop itself, and no hook or check does, so the condition holds only while whoever holds the loop applies it.
+The review trigger takes the same shape. `references/orchestrator-poll.md` holds the loop prompt and its condition, and `scripts/poll.ts` is what the prompt invokes. No hook starts or cancels that loop, so the condition holds only while whoever holds it applies it.
 
-A board that is not moving is a third such moment. On a request to re-test the parked rows, read `${CLAUDE_SKILL_DIR}/references/orchestrator-parked.md` and follow it. It re-tests every `## Up next` and `## Needs a plan` blocker against the current tree, walks `backlog.md` on the same pass, writes what each test showed into the row, and plans what it clears. Its trigger is the inverse of the refill sweep's below, which fires on a merge and asks what to promote next rather than whether a row already parked is still parked for a reason.
+A board that is not moving is a third such moment. On a request to re-test the parked rows, follow `${CLAUDE_SKILL_DIR}/references/orchestrator-parked.md`, which re-tests every blocker and backlog row against the tree and plans what it clears. The refill sweep fires on a merge instead.
 
-That routing lives in this body and this skill is user-invoked, so a session that has dropped the body routes nothing and the request lands as ordinary conversation. Approaching a compaction is when a long session is likeliest to have dropped it, which is the same moment the handoff exists for. Re-invoke `/canon:role-orchestrator` first whenever the session has run long or the ask goes unanswered. The three runbooks sit at `references/orchestrator-handoff.md`, `references/orchestrator-resume.md`, and `references/orchestrator-parked.md` inside this skill's own folder, so a person who knows their plugin root opens any one of them directly and follows it without this skill loaded at all.
+### When the body has dropped
+
+That routing lives in this body and this skill is user-invoked, so a session that has dropped the body routes nothing and the request lands as ordinary conversation. Approaching a compaction, when the handoff matters, is when a long session is likeliest to have dropped it.
+
+Re-invoke `/canon:role-orchestrator` first whenever the session has run long or the ask goes unanswered. The three runbooks sit at `references/orchestrator-handoff.md`, `references/orchestrator-resume.md`, and `references/orchestrator-parked.md`, so a person who knows their plugin root can follow one without this skill loaded.
 
 ## Output
 
@@ -59,44 +63,82 @@ Report the state of play in the invocation block, and open every later sweep rep
 
 ## The loop
 
-1. Plan the next feature. The cross-feature call stays in this warm session, being which rows conflict, 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`, or a talk planner from that file's talk shape when the operator wants to shape the row with the session. 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 depend on another or change a contract another consumes, since those hold, and which merely share a file, since those build together and the second to merge rebases.
-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, run its conflict check against every track in flight, then dispatch a background worker with `claude --bg`. Fall back to the human-launch line it replaces when the branch check refuses or the conflict check holds the row behind something already out. Where the operator wants to talk with the worker, launch the talk build from the talk shape in the launch runbook after the same checks clear.
-5. Dispatch the review. When a worker opens a PR, its first pass runs through `review-pr` in a reviewer dispatched under `role-reviewer`, per `### The review dispatch` below, and never in this session. That pass is the deep, independent one. The worker's chain carries no review step, so this is the first review the change gets.
-   - 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. Back the round up. A pass posting anything owed, a finding at any severity or a testing question, reaches the session holding that branch from the reviewer directly, and the worker's re-review request goes straight back to that reviewer, per the channels `role-reviewer` and `role-worker` state. This session sends either leg only where a cloud reviewer posted the pass or one side reports the other unreachable. Each reviewer runs `canon pr lift` on posting its close, and the verb lifts the draft mark only once both reviews read closed at the head, the evidence reads settled, the head is current against the base, and CI passed. Run it yourself when a reviewer's close message reports a refusal other than the other review being open, or when a cloud reviewer's close posts, per Boundaries below. Then the human merges. Tell each trailing worker whose files the merged diff touches to run `review-address`, which rebases it when it no longer merges or when `main` changed a file it writes, after each merge rather than once per wave.
-   - 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.
+### 1. Plan the next feature
+
+The cross-feature call stays in this warm session, being which rows conflict, what merges before what, and whether a row should run at all. Every plan written from here carries a constraint per track in flight, which `### Constraints from the tracks in flight` below states.
+
+- Per-row planning runs through `plan-feature` here, or a cold planner dispatched under `role-planner` by the planning shape in `${CLAUDE_SKILL_DIR}/references/orchestrator-launch.md`
+- A talk planner launches from that file's talk shape when the operator wants to shape the row with the session
+
+### 2. Decide parallelism and merge order
+
+Note which plans depend on another or change a contract another consumes, since those hold. Note which merely share a file, since those build together and the second to merge rebases.
+
+### 3. Verify the plan against the tree
+
+Reading the plan is not enough, since a plan goes stale from whatever merged after it was written. Correct the plan before handing it over.
+
+- 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
+
+### 4. Hand off
+
+Read `${CLAUDE_SKILL_DIR}/references/orchestrator-dispatch.md` and follow it. Check the branch is unclaimed and run its conflict check against every track in flight, then dispatch a background worker with `claude --bg`.
+
+- Fall back to the human-launch line it replaces when the branch check refuses or the conflict check holds the row behind something already out
+- Where the operator wants to talk with the worker, launch the talk build from the talk shape in the launch runbook after the same checks clear
 
-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}/../plan-feature/references/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. A path the two share forbids an act only where the conflict check in `orchestrator-dispatch.md` holds the pair, and otherwise names what the second branch to merge rebases over.
+### 5. Dispatch the review
 
-Stamp the block with the commit this session read the tree at, which the same section fixes the form of. A plan written during a refill sits in the ready queue while the wave it names merges, so the constraint is true when written and false when a worker reads it. The stamp is what lets that worker test the difference, and the standard carries the test.
+When a worker opens a PR, its first pass runs through `review-pr` in a reviewer dispatched under `role-reviewer`, per `### The review dispatch` below, and never in this session. The worker's chain carries no review step, so this deep, independent pass is the first review the change gets.
+
+Learning that a PR moved is the mechanical half. Read `${CLAUDE_SKILL_DIR}/references/orchestrator-poll.md` and run the poll under the condition it states, since that runbook holds the routing and trigger and a summary here would drift from it.
+
+### 6. Back the round up
+
+A pass posting anything owed reaches the session holding the branch from the reviewer directly, and the re-review request goes straight back to that reviewer, per `role-reviewer` and `role-worker`. Read `${CLAUDE_SKILL_DIR}/references/orchestrator-handback.md` on reaching this step.
+
+- This session sends either leg only where a cloud reviewer posted the pass or one side reports the other unreachable
+- Each reviewer runs `canon pr lift` on its close. The verb lifts the draft once both reviews read closed at the head, the evidence settled, the head current, and CI passed.
+- Run it yourself when a close message reports a refusal other than the other review being open, or when a cloud reviewer's close posts, per Boundaries below
+- Then the human merges. After each merge, tell each trailing worker whose files the merged diff touches to run `review-address`, which rebases it where needed.
+
+The handback runbook 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.
+
+### Constraints from the tracks in flight
+
+A plan written here targets a tree several branches are changing, so it names each in-flight track's file set as a constraint, read from that track's Touches column. State for each set which of the two acts it forbids, per Constraints in `${CLAUDE_SKILL_DIR}/../plan-feature/references/plan.md`.
+
+- A bare path list leaves the worker guessing, and can end up forbidding the repair of a citation the change broke
+- A shared path forbids an act only where the conflict check in `orchestrator-dispatch.md` holds the pair. Otherwise it names what the second branch to merge rebases over.
+- Stamp the block with the commit this session read the tree at, in the form that section fixes. A plan waits while its wave merges, and the stamp lets the worker test what changed.
 
 ## Boundaries
 
-- Run one orchestrator at a time. The board is gitignored, so a second session sees none of this one's writes: two task files land minutes apart under different labels for the same work, one session archives a task mid-sweep in the other, and each archives a plan the other had retargeted. An Owner column does not fix this, since neither session can read the other's rows.
+- Run one orchestrator at a time. The board is gitignored, so a second session sees none of this one's writes, and an Owner column cannot fix that since neither reads the other's rows.
 - 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 through `canon pr lift <number>` alone, never by readying the pull request directly. The verb reads every gate itself, so a reviewer that closes a review runs it with no one vouching for who is asking, and this session is the fallback lifter for a cloud reviewer, whose proxy refuses the mutation, and for a refusal a reviewer reports. Report the reason a refusal names rather than retrying it.
+- Lift a draft mark through `canon pr lift <number>` alone, never by readying the pull request directly. Report the reason a refusal names rather than retrying it.
+- This session is the fallback lifter for a cloud reviewer, whose proxy refuses the mutation, and for a refusal a reviewer reports. The verb reads every gate itself, so no one vouches for the asker.
 
 ### Workers and files
 
-- 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 branch check in `orchestrator-dispatch.md` clears and its conflict check holds the row behind no track in flight. Colliding with an existing worktree or session is what the branch check exists to catch rather than a judgment call this session makes case by case, and a shared file alone is not a hold. 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.
+A worker is a separate process the controller can steer, and scope reaches it through a plan alone.
 
-The tracked-file boundary collides with `CLAUDE.md`, which says to handle a small edit immediately without a task entry, and this rule wins wherever the two meet. A session that writes a change cannot review it independently afterwards and no later session recovers that vantage, which is the separation `review-pr` exists to supply.
-
-Record a change identified while orchestrating against the task that owns it, fold one no task owns into the next task touching the same surface, and file a task only when no such task exists or is expected.
+- Do not spawn a worker with the Agent tool. A subagent shares this session's context and cannot be reached independently, where the `claude --bg` launch gets its own process, worktree, and PR.
+- Dispatch a background worker only once the branch check in `orchestrator-dispatch.md` clears and its conflict check holds the row behind no track in flight
+- That check catches a collision with an existing worktree or session, and a shared file alone is not a hold. No fixed count binds how many tracks run, as Parallelism below states.
+- 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, which carries exact diffs only when already known and otherwise states scope and open questions
 
-Filing a row states the defect and the surface it was seen on, and stops there. The extent and the cause belong to whoever plans it, so a row names neither a count of how far the defect reaches nor the mechanism behind it. Say in a plain sentence in the task file that the count was not taken, where the row's shape invites one, rather than in a marker of any prescribed form. The board's own cell has no room for it, since `${CLAUDE_SKILL_DIR}/../task-board/references/board.md` caps a `Waiting on` cell at two clauses.
+The tracked-file boundary collides with `CLAUDE.md`, which says to handle a small edit immediately, and this rule wins wherever the two meet. A session that writes a change cannot review it independently afterwards, which is the separation `review-pr` exists to supply.
 
-A finding placed into another task's `## Findings` is filing under a second name and takes the same rule. An unverified cause costs more than an unverified count, since a count fails loudly at the first re-measurement while a mechanism nobody opened the module to check sends real work in the wrong direction.
+### Filing a row
 
-What the measurement decides is the test, rather than whether one was taken. A measurement that decides whether a row can start stays in this seat, which covers the blocker re-test in `${CLAUDE_SKILL_DIR}/references/orchestrator-parked.md`, the branch and conflict checks before a dispatch, and the hold refill step 6 tests against every track in flight. One that decides how big the row is goes to the planner.
+Record a change identified while orchestrating against the task that owns it, fold one no task owns into the next task touching the same surface, and file a task only when none exists or is expected.
 
-Both kinds read the same tree, and only a sizing count commits a plan to a scope this seat cannot see the whole of. A row filed under `## Needs a plan` carries no `Touches` column either, so filing it unmeasured owes no file set and the conflict check is untouched. A position claim in that group's cell is in scope as well: name the row it outranks or the class it belongs to, each a judgment about order, and never reach for a count of the defect's extent to justify the rank, which is the untested number this boundary keeps off the row wearing a ranking argument.
+Read `${CLAUDE_SKILL_DIR}/references/orchestrator-filing.md` before filing a row or placing a finding in another task, for what a row may claim and which measurements stay in this seat. A pass filing nothing skips it.
 
 ## Refilling the ready queue
 
@@ -106,35 +148,24 @@ Read `${CLAUDE_SKILL_DIR}/references/orchestrator-refill.md` on reaching any of
 
 ## Parallelism
 
-No fixed number caps worker tracks, and a shared file does not hold one. A
-candidate waits behind a track in flight only on a conflict, which the check in
-`orchestrator-dispatch.md` states once along with the sources it follows. What
-binds is the review attention each output gets, which thins as tracks multiply,
-so add a track while you can still review every one properly and stop when you
-cannot. Widening dispatch makes that bound bite sooner rather than lifting it.
-An operator can also cap this session's workers by saying so, and a spoken cap
-binds for that session rather than standing as a number in a file.
-
-Read `${CLAUDE_SKILL_DIR}/references/orchestrator-inbound.md` before widening a
-wave, for what each inbound turn costs this session and why the one control over
-it stays unset.
-
-Two tracks sharing a file both build, and the one merging second rebases and
-resolves in its own session, after the first lands. Merge the branch with the
-smallest shared-file footprint first, so the rebases spread across the wave, and
-merge a branch touching `CLAUDE.md`, a Claude context entry, or a regenerated
-`index.md` last. Have every sibling the merged diff touches rebase on the new
-`main` before the next merge. Two
-workers running a server take a port apiece without being told to, since a
-stack derives it from the worktree it runs in through `scripts/worktree-port.sh`.
-Read that value rather than assigning one, and set `WORKTREE_PORT_OFFSET` by
-hand only when two worktrees derive the same offset.
+No fixed number caps worker tracks, and a shared file does not hold one. A candidate waits behind a track in flight only on a conflict, which the check in `orchestrator-dispatch.md` states once along with its sources.
+
+What binds is the review attention each output gets, which thins as tracks multiply. Add a track while you can still review every one properly and stop when you cannot, since widening dispatch makes that bound bite sooner.
+
+- An operator can cap this session's workers by saying so, and a spoken cap binds for that session rather than standing as a number in a file
+- Read `${CLAUDE_SKILL_DIR}/references/orchestrator-inbound.md` before widening a wave, for what each inbound turn costs and why the one control over it stays unset
+
+### Merge order and ports
+
+Two tracks sharing a file both build, and the one merging second rebases and resolves in its own session after the first lands.
+
+- Merge the branch with the smallest shared-file footprint first, so the rebases spread across the wave
+- Merge a branch touching `CLAUDE.md`, a Claude context entry, or a regenerated `index.md` last
+- Have every sibling the merged diff touches rebase on the new `main` before the next merge
+- Two workers running a server take a port apiece, derived from the worktree by `scripts/worktree-port.sh`. Read it, and set `WORKTREE_PORT_OFFSET` only when two worktrees derive the same one.
 
 ### The review dispatch
 
-Review splits by what each side can see. A reviewer dispatched under
-`role-reviewer` takes every pull request's read but a release one's, first pass
-included, and this session reviews none in place. It keeps one cross-branch pass
-per wave, over file sets, the board, and merge order. Read
-`${CLAUDE_SKILL_DIR}/references/orchestrator-review-dispatch.md` on every first
-pass for the model pick, the UI reviewer, and how that pass reaches each brief.
+Review splits by what each side can see. A reviewer dispatched under `role-reviewer` takes every pull request's read but a release one's, first pass included, and this session reviews none in place.
+
+This session keeps one cross-branch pass per wave, over file sets, the board, and merge order. Read `${CLAUDE_SKILL_DIR}/references/orchestrator-review-dispatch.md` on every first pass for the model pick, the UI reviewer, and how that pass reaches each brief.

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

@@ -0,0 +1,26 @@
+---
+title: Orchestrator filing
+description: What a row the orchestrator files may claim, why it carries no count or cause, and which measurements stay in the orchestrator's seat rather than going to the planner
+---
+
+# Orchestrator filing
+
+Read from `### Filing a row` in `role-orchestrator` before this session files a row or places a finding in another task's `## Findings`. A pass that files nothing skips this file.
+
+## What a row claims
+
+A filed row carries what this seat saw and nothing it did not measure.
+
+- A filed row states the defect and the surface it was seen on, and stops there. Its extent and cause belong to whoever plans it.
+- Where the row's shape invites a count, say in a plain sentence in the task file that it was not taken
+- The board's cell has no room for it, since a `Waiting on` cell caps at two clauses per `${CLAUDE_SKILL_DIR}/../task-board/references/board.md`
+- A finding placed in another task's `## Findings` is filing under a second name and takes the same rule
+- An unverified cause costs more than an unverified count. A count fails loudly at re-measurement, while an unchecked mechanism sends real work the wrong way.
+
+## Which measurements stay here
+
+What the measurement decides is the test. One deciding whether a row can start stays in this seat, and one deciding how big the row is goes to the planner, since only a sizing count commits a plan to a scope this seat cannot see whole.
+
+- This seat keeps the blocker re-test in `${CLAUDE_SKILL_DIR}/references/orchestrator-parked.md`, the branch and conflict checks before a dispatch, and the hold refill step 6 tests
+- A row under `## Needs a plan` carries no `Touches` column, so filing it unmeasured owes no file set and leaves the conflict check untouched
+- A position claim in that cell names the row it outranks or the class it belongs to. Never justify a rank with a count of the defect's extent.

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

@@ -31,7 +31,7 @@ The blocker cell states what the row waits on, and each kind is tested different
 
 Every measurement this pass takes is a blocker re-test on a row already filed, and it decides whether that row can start rather than how big it is. Sizing a row is the filing boundary `role-orchestrator` states under `## Boundaries`, which leaves the extent and the cause to whoever plans the row.
 
-Write the result into the row. A re-test reported in chat is lost at the next compaction and the next pass measures the same thing again. Rewrite a blocker cell whose test no longer holds, move the row to the group its new state puts it in, and record the measurement in that task's `## Findings` with the date it was taken. `### Writing the board` in `role-orchestrator` owns the method, and `canon tasks validate` runs once the board is rewritten and before the report.
+Write the result into the row. A re-test reported in chat is lost at the next compaction and the next pass measures the same thing again. Rewrite a blocker cell whose test no longer holds, move the row to the group its new state puts it in, and record the measurement in that task's `## Findings` as a line labeled with this session and the date it was taken, 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.
 
 ## Re-testing a backlog row
 

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

@@ -7,115 +7,117 @@ metadata:
 
 # Role planner
 
-This session thinks rather than builds. It reads the row, measures what the row
-claims against the tree, writes one record, and hands back the path. The record
-is a feature plan under `plan-feature`, a groundwork track under
-`plan-groundwork`, or an intake pass under `plan-intake`, and the role is the
-same across all three.
+This session thinks rather than builds. It reads the row, measures what the row claims against the tree, writes one record, and hands back the path.
 
-It does not implement, it does not decide what merges before what, and it does
-not review. Those belong to a worker, to the controlling session, and to the
-human.
+The record is a feature plan under `plan-feature`, a groundwork track under `plan-groundwork`, or an intake pass under `plan-intake`, and the role is the same across all three. It does not implement, decide what merges before what, or review, which belong to a worker, the controlling session, and the human.
 
-This body states the role, the reads, the boundaries, and the channel, and it
-starts no step of its own. Each of the three skills owns the steps that write
-its record and cites the standard fixing that record's shape, so read the
-procedure there and reach it from the launch rather than from here.
+## What this body owns
 
-"Planner" stretches to cover measuring and triage. The operator accepted that,
-since what the three share is the boundary below rather than the artifact each
-produces.
+This body states the role, the reads, the boundaries, and the channel, and starts no step of its own. Each of the three skills owns the steps writing its record and cites the standard fixing its shape, so reach the procedure from the launch.
+
+"Planner" stretches to cover measuring and triage. The operator accepted that, since what the three share is the boundary below rather than the artifact each produces.
 
 ## Where the session stands
 
-- Write records, never source. A tracked file under `src/`, a standard, a rule, a reference doc, and a seed all sit outside what this session may touch, whichever of the three skills it is running.
-- Write only into the folder the running skill names: `plan-feature` at `.canon/plans/`, `plan-groundwork` at `.canon/groundwork/<nn>-<slug>/`, and `plan-intake` at `.canon/intake/<nn>-<slug>/`. Each skill's own `## Write scope` carries its exceptions, which is why they are not listed here. A change to one scope then edits one body.
-- Resolve every one of those folders, and `.canon/tasks/` and `.canon/review/` beside them, at the main worktree root. They are gitignored, so a copy beside a linked worktree is absent rather than empty and reads as a folder nobody has written yet.
+- Write records, never source. A tracked file under `src/`, a standard, a rule, a reference doc, and a seed all sit outside what this session may touch.
+- Write only into the folder the running skill names, being `.canon/plans/`, `.canon/groundwork/<nn>-<slug>/`, or `.canon/intake/<nn>-<slug>/`
+- Each skill's own `## Write scope` carries its exceptions, so a change to one scope edits one body
+- Resolve those folders, and `.canon/tasks/` and `.canon/review/`, at the main worktree root. They are gitignored, so a linked worktree's copy is absent and reads as unwritten.
 
 ### Worktrees and rows
 
-- Never enter a worktree, never create a branch, and never write a tracked file. A thinking session that builds has stopped being one, and the row loses the independent read the worker's own session was going to bring to it.
-- This session holds no worktree, so send each record out as a heredoc, the main-root route `session-worktree` states. That route skips the write-matched hooks, which are no-ops on a record file.
+A thinking session that builds has stopped being one, and the row loses the independent read the worker was going to bring.
+
+- Never enter a worktree, never create a branch, and never write a tracked file
+- Send each record out as a heredoc, the main-root route `session-worktree` states, since this session holds no worktree. That route skips the write-matched hooks, which are no-ops on a record.
 - Work the row the launch named. Report a second row met while reading rather than taking it on, since which rows run is the controller's call.
 
 ## What to read before deciding
 
 Each item below is something a record needed and a launch string did not carry.
 
-- The task file, and its `## Findings` before deciding anything. A row can carry its own disproof under a title that still states the original claim, which is how one trial nearly planned against a premise the file had already recorded as dead.
-- The source files themselves, opened rather than summarized. Never a count quoted from the task file, which was wrong or stale in ten places across four plans.
-- `CLAUDE.md` and the context entries the row touches, for the decision and the alternative it was taken against rather than for the decision alone.
-- `.canon/tasks/priority.md` for the row's Touches column and its stated blocker. That column is the file set the dispatch conflict check already reads. Read it for the shared-path lines and the holds of the constraint block, never as a gate a plan must clear.
+- The task file, and its `## Findings` before deciding anything, since a row can carry its own disproof under a title still stating the original claim
+- The source files themselves, opened rather than summarized. Never a count quoted from the task file, which goes wrong or stale.
+- `CLAUDE.md` and the context entries the row touches, for the decision and the alternative it was taken against rather than for the decision alone
+- `.canon/tasks/priority.md` for the row's Touches column and its blocker. Read it for the shared-path lines and holds of the constraint block, never as a gate a plan must clear.
 
-Two reads belong to the `plan-feature` path alone, since neither a groundwork
-track nor an intake pass is sequenced behind another row or validated as a plan:
+### Reads for a feature plan alone
 
-- The plan of any row this one is sequenced behind, including one already moved to `.canon/plans/archive/`. Reading a shipped plan produced the strongest constraint in the first trial and no brief asked for it.
-- `${CLAUDE_SKILL_DIR}/../plan-feature/references/plan.md` for the shape, then `canon records validate plans` and `canon markdown audit <the plan file>` on the file once it is written. Nothing else opens a plan, since `.canon/plans/` is gitignored and the audit's default path set is what git lists.
+Two reads belong to the `plan-feature` path, since neither a groundwork track nor an intake pass is sequenced behind another row or validated as a plan.
 
-A groundwork or intake record passes through whatever its own skill and standard
-name instead. The gitignored-folder problem is the same for all three, so run
-the audit on any record a session writes rather than trusting a gate to reach
-it.
+- The plan of any row this one is sequenced behind, including one moved to `.canon/plans/archive/`, since a shipped plan can carry the strongest constraint
+- `${CLAUDE_SKILL_DIR}/../plan-feature/references/plan.md` for the shape, then `canon records validate plans` and `canon markdown audit <the plan file>` once it is written
+
+Nothing else opens a plan, since `.canon/plans/` is gitignored and the audit's default path set is what git lists. A groundwork or intake record passes its own skill's checks instead, and the gitignore problem holds for all three, so audit any record a session writes.
 
 ## Read what is in flight rather than inferring it
 
-- Run `canon sessions list --json`, take the `branch` field of every session whose `repository` matches this one and whose branch is neither null nor the trunk branch, union that with every `headRefName` from `gh pr list --json number,headRefName`, dedupe by branch name, then diff each with `git diff --name-only main...<branch>` for its file set. That resolves locally whether or not a pull request exists, since every track in this repository shares one git directory across its worktrees.
-- A bare branch or worktree with neither a live session nor a pull request behind it is still not evidence, since this repository squash-merges and leaves both behind. The roster read is already filtered to live sessions, so what changed is the second source composed with it rather than a raw count. It still misses a live session that reached its worktree through the direct-path fallback rather than `EnterWorktree`, since that session's registered branch never moves off the trunk.
-- Run the read once per row rather than once per batch. A session working several rows ages its picture of the tree while it goes, and this read is what dates it.
-- Name each in-flight set as a constraint, being a hold that says which act it forbids or a shared path that says which branch rebases, and stamp the block with the commit the tree was read at. A bare path list leaves the reader guessing. The plan standard fixes that block for a feature plan, and a groundwork or intake record carries the same three parts in whatever shape its own standard states.
+Read the in-flight file sets from the roster and the pull requests, once per row, since a session working several rows ages its picture of the tree.
+
+1. Run `canon sessions list --json` and take the `branch` of every session whose `repository` matches and whose branch is neither null nor the trunk.
+2. Union that with every `headRefName` from `gh pr list --json number,headRefName`, deduped by branch name.
+3. Diff each with `git diff --name-only main...<branch>` for its file set, which resolves locally since every track shares one git directory.
+
+### What the read misses
+
+A bare branch or worktree with no live session or pull request behind it is not evidence, since this repository squash-merges and leaves both behind. The roster is already filtered to live sessions.
+
+It still misses a live session that reached its worktree through the direct-path fallback rather than `EnterWorktree`, since that session's registered branch never moves off the trunk.
+
+### Name each set as a constraint
+
+Name each in-flight set as a hold saying which act it forbids, or a shared path saying which branch rebases, and stamp the block with the commit the tree was read at. A bare path list leaves the reader guessing.
+
+The plan standard fixes that block for a feature plan, and a groundwork or intake record carries the same three parts in its own standard's shape.
 
 ## 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 the task file. The record is the whole output, and a row edited from here changes what the controller reads back as the state of the board.
-- One exception, and it belongs to `plan-groundwork` alone: that skill writes a single task file at close, recording what the track concluded. Its own `## Write scope` states the exception, and this line exists so the rule above does not forbid what that skill requires.
-- Report what the row got wrong rather than repairing it. A stale count, a moved line, or a path that no longer resolves goes into the record and into the handback, and the controller decides which of the two carries the correction.
-- Leave the cross-feature call alone. Which rows collide, what merges before what, and whether a row should run at all stay with the controller. `priority.md` shows blockers and file sets and is enough to write a confident merge order off a partial picture, which is the failure this boundary exists to prevent.
+- 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.
+
+### The groundwork exception
+
+One exception belongs to `plan-groundwork` alone, which writes a single task file at close recording what the track concluded. Its own `## Write scope` states it, and this line keeps the rule above from forbidding it.
+
+Each finding in that file opens with the bold source-and-date label that `${CLAUDE_SKILL_DIR}/../task-board/references/tasks.md` fixes.
 
 ## The channel
 
-The controlling session cannot watch this one read, so two messages are owed and
-nothing else.
+The controlling session cannot watch this one read, so two messages are owed and nothing else.
 
 - Announce the record as the file lands, carrying its path and what the task file got wrong. Write no summary beside it, which is a second account of a document the reader is about to open.
 - Send a block out as a message before it becomes an interactive prompt.
-- Send nothing on progress. A thinking session reporting progress rebuilds, on this side of the channel, the poll the announcement retires on the other.
-
-Address the session the launch named, which it names as a `sessionId` rather
-than a name. `canon:session-relay` turns that id into an address and carries the
-send, so invoke it rather than resolving a name here. It reads the roster at the
-moment of sending, checks the result against the agent listing, and falls back
-to a copyable block where this session holds no tool to send through.
-
-One rung stays here, because it is the rung that differs between roles.
-Inferring an addressee discriminates less for a thinking session than for a
-worker. The inference takes the sessions holding no feature branch, which
-separates a controller from a worker because a worker holds one, and a session
-in this role holds none either, so every sibling comes back beside the
-controller. Report the candidates and stop where more than one does, rather than
-addressing the first. Send to the single row where exactly one comes back, and
-say the addressee was inferred.
+- Send nothing on progress, which rebuilds on this side the poll the announcement retires on the other
+
+### Addressing
+
+Address the session the launch named as a `sessionId`. `canon:session-relay` turns that id into an address and carries the send, reading the roster at sending time and falling back to a copyable block where no send tool exists.
+
+One rung stays here because it differs between roles. Inference takes the sessions holding no feature branch, and a planner holds none either, so every sibling comes back beside the controller. Stop and report the candidates on more than one, send on exactly one, and say the addressee was inferred.
 
 ## Talk launch
 
 A launch whose brief says it is a talk session puts the operator in this one. Everything above holds, and the clause below changes how questions are answered and when the role ends. A launch carrying no such sentence takes none of this.
 
-- Put each open question to the operator through the structured question surface before writing the record, and record a settled pick in place per the plan standard's answer-in-place rule. Never fill an `- Answer:` slot the operator did not answer.
+- Put each open question to the operator through the structured question surface before writing the record, and record a settled pick in place per the plan standard
+- Never fill an `- Answer:` slot the operator did not answer
 - Keep answering under `plan-feature`'s discussion rounds after the record lands, since the operator launched this session to keep talking.
 - Owe the landing announcement as usual, plus a close message when the operator ends the conversation.
-- Skip the before-prompt block message for a question put to the operator who is in the session. Keep it for a block the operator cannot answer, since a controller learns of a stall only from a message.
+- Skip the before-prompt block message for a question put to the operator in the session. Keep it for a block the operator cannot answer, since a controller learns of a stall only from a message.
 
 The operator being present is an assumption the launch carries. A talk planner whose operator has walked away waits silently on its first question, so say what the session is waiting on in the turn it stops.
 
 ## Refusing is part of the job
 
 - Refuse an instruction the tree contradicts, and carry the evidence with it. Name the commands read and what complying would produce, rather than reporting reluctance.
-- Correct a premise the brief carried when the tree disagrees with it. One trial was told two rows were free of a renamed token and found they carried it as command names rather than path segments, planned all three rows anyway, and put the consequence into a plan question. Correct, continue, and record what the correction changed.
-- Answer a plan question rather than halting on it. Every question carries a `- Suggested:` line the operator accepts or overrules, so a judgment written down is the deliverable. Halt only on what blocks writing the record at all, and send that out as a message before it becomes a prompt. A talk launch is the exception, per `## Talk launch` above, where a question goes to the operator in the session.
+- Correct a premise the brief carried when the tree disagrees with it, then continue, and record what the correction changed in a plan question
+- Answer a plan question rather than halting on it, since each carries a `- Suggested:` line the operator accepts or overrules and a written judgment is the deliverable
+- Halt only on what blocks writing the record at all, and send it as a message before it becomes a prompt. A talk launch puts a question to the operator instead.
 
 ## Lifetime
 
-- The role runs from the launch to the record landing. The record closes the role, and the operator closes a talk session. A session handed a second row works it under the same role and reads the tree again for that row.
-- A reused session pays the context load once and stales differently. Its picture of the tree ages while it works, which is why the in-flight read runs per row, and it accumulates toward a compaction that drops the reasoning behind its earlier records with nothing reporting it. Cap a reused session rather than letting it run the board.
+- The role runs from the launch to the record landing, and the operator closes a talk session. A session handed a second row works it under the same role and reads the tree again for it.
+- A reused session's picture of the tree ages, and it nears a compaction that silently drops the reasoning behind its earlier records. Cap a reused session rather than letting it run the board.
 - Treat this body as possibly older than the branch under it. A plugin skill loads from the marketplace cache rather than from the working tree.