@erclx/canon 4.1.0 → 4.2.0

package/README.md

@@ -80,7 +80,7 @@ Each domain has a canonical source in this repo and a thin install or sync CLI o
 Scaffolding your first project? Start with target projects, then the AI workflow loop. Everything else answers questions that arrive later.
 
 - [AI workflow](docs/ai-workflow.md): feature-development loop inside a toolkit-managed project
-- [Operating model](docs/operating-model.md): orchestrator and worker roles for building across parallel sessions
+- [Operating model](docs/operating-model.md): orchestrator, planner, and worker roles for building across parallel sessions
 - [Visual design workflow](docs/visual-design-workflow.md): tiered guide for design and wireframe authoring
 - [Target projects](docs/target-projects.md): scaffold, add a domain later, sync upstream drift
 - [Agents](docs/agents/index.md): CLI flags, exit codes, and JSON output shapes

package/claude/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "canon",
   "description": "Automated governance, versioning, and discovery tools for Claude Code.",
-  "version": "4.1.0",
+  "version": "4.2.0",
   "author": {
     "name": "Eric Le",
     "url": "https://github.com/erclx"

package/claude/skills/claude-feature/SKILL.md

@@ -89,6 +89,8 @@ The file follows the template in `${CLAUDE_SKILL_DIR}/../../standards/plan.md`.
 
 Run `canon records validate plans` after writing the file when the CLI is on PATH. It reports a section, a filename, or an answer slot that does not hold, and it writes nothing.
 
+Run `canon markdown audit .claude/plans/feature-<slug>.md` beside it, naming the file. `.claude/plans/` is gitignored and the audit's default path set is what git lists, so no other gate ever opens a plan, and six ban hits landed across four plans written without this call. Rewrite the sentence carrying a hit rather than swapping the token for a near-synonym.
+
 Then output in chat:
 
 ```markdown

package/claude/skills/claude-orchestrate/SKILL.md

@@ -108,7 +108,7 @@ Write no shape for a correction. A correction is a sentence, and a format for ad
 
 ## The loop
 
-1. Plan the next feature. Run `claude-feature` here, with the cross-feature context, to write a plan to `.claude/plans/`. Planning stays in this warm session so the plan front-loads reasoning a cold worker would otherwise re-derive. Every plan written from here also carries a constraint per track in flight, which the paragraph below this list states.
+1. Plan the next feature. The cross-feature call stays in this warm session, being which rows collide, what merges before what, and whether a row should run at all. Per-row planning runs either way: `claude-feature` here with that context, or a cold planner dispatched under `claude-planner` through the planning shape in `${CLAUDE_SKILL_DIR}/references/orchestrator-dispatch.md`. Every plan written from here also carries a constraint per track in flight, which the paragraph below this list states.
 2. Decide parallelism and merge order. Note which plans touch a shared wiring seam so their PRs merge in sequence, not at once.
 3. Verify the plan against the tree. Reading it is not enough, since a plan goes stale from whatever merged after it was written. Grep for each construct it names and count the sites against the count it claims. Check that every phase label it cites is still open. Open each file it describes rather than trusting its account of the contents. Correct the plan before handing it over.
 4. Hand off. Read `${CLAUDE_SKILL_DIR}/references/orchestrator-dispatch.md` and follow it: check the branch is unclaimed, check the row's file set against every track in flight, then dispatch a background worker with `claude --bg`. Fall back to the human-launch line it replaces when the check refuses, the sets overlap, or a stated reason serializes the row behind something already out.
@@ -129,6 +129,8 @@ What the worker owes on its own side is stated in the `claude-worker` skill that
 
 What arrives there does not become a record by being read, so place it by what it changes. An answer that settles a finding goes onto the pull request through the next pass, which withdraws or regrades that finding and names the fact behind it, per `claude-pr-review`. An answer that changes what this session believes about the world instead, which is a mapping correction or a constraint on what a worker can do, settles no finding and reaches no thread, so route it the way Boundaries below routes a change found while orchestrating, which lands it on the task owning the surface it describes. Writing a tracked file to hold either is forbidden here, which leaves the pull request and the board as the two surfaces this session writes.
 
+Step 1 splits a rule that used to hold every plan in this session, and the evidence narrows it rather than retiring it. Two trials on 2026-08-31 put a cold planner on four rows, and it reported ten things the task files got wrong, corrected this session's own premise twice, and overturned one row's closing conclusion. What that measures is finding quality. The rule's own claim is that a warm plan front-loads reasoning a cold worker would otherwise re-derive, which is a statement about a plan's downstream value, and no plan from either trial has been built. So the per-row measurement goes cold on the evidence and the cross-feature call stays here on the boundary the same trials confirmed, which is that a planner reading the board sees blockers and file sets and can write a confident merge order off a partial picture.
+
 A plan written here is written against a tree several branches are already changing, so it names the file set of every track in flight as a constraint, one set per track, read from the Touches column of that track's row. State for each set which of the two acts it forbids, per Constraints in `${CLAUDE_SKILL_DIR}/../../standards/plan.md`. A bare path list leaves the worker guessing, which is how a plan ends up forbidding the repair of a citation the change broke.
 
 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.

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

@@ -1,6 +1,6 @@
 ---
 title: Orchestrator dispatch runbook
-description: The collision check before a self-dispatch, the file-set disjointness gate, the branch and model the launch names, and the loop's stopping condition
+description: The collision check before a self-dispatch, the file-set disjointness gate, the branch and model the launch names, the planning and handback dispatch shapes, and the loop's stopping condition
 ---
 
 Run this at loop step 4, for a `## Run now` row whose plan is verified, in place of handing the worktree to a human. The disjointness gate below is where that row's file set is tested against every track in flight.
@@ -65,10 +65,50 @@ Read `<dispatcher-id>` with `canon sessions list --self --json` and interpolate
 
 Where the installed CLI answers `--self` with an unknown option, that flag is newer than the release the target holds. Read the `sessionId` from the record the client writes for this session under its configuration directory, and say which route answered so the reader knows whether the id was read or inferred.
 
+The worker resolves that id back to a name through `canon sessions list --json`, which carries `sessionId` per row, rather than through the agent listing, which prints a name and a short ref and no id at all. A worker reaching for the listing first therefore finds no lookup and can conclude there is none. That failure is silent in both directions: the session has nothing useful to do with the message it owes and goes idle holding it, and nothing on this side reports the quiet, so the loss surfaces as a missing worktree or a pull request that never opens rather than as anything watching for it.
+
 The worktree call comes first and carries the branch as its argument, which is tier 0 of `claude-worktree` Step 2 and the only tier a caller can reach. `claude-autoship` Step 0 then finds the session already in a linked worktree and continues, which is a path it already documents. The autoship call carries `<plan>`, the same file this runbook already read to derive the branch, so its Step 1 takes it as the caller-supplied plan rather than re-deriving one from the slug the worker's branch happens to carry.
 
 Naming the branch in prose instead was tried and closes nothing, because no tier of that ladder reads the prompt. A worker launched onto `main` cannot match tier 1, a board carrying more than one plan puts tier 2 out of reach, and tier 3 tells it to ask a person who is not there. Four workers took the right branch that way, by inference rather than by contract, which is the same judgment both live disagreements came from.
 
+### The prompt expands its leading slash command and nothing after it
+
+The client expands the first slash command in a launch prompt as a user
+invocation, which is the route `disable-model-invocation: true` permits. Every
+later command in the same prompt reaches the session as prose, leaving the model
+to invoke it through the `Skill` tool, and that route answers a flagged skill
+inconsistently. `claude-autoship` has carried the flag since `#365` and seven
+other shipped skills carry it too.
+
+The block above therefore leads with the call that does not need the user route
+and leaves the one that does to the tool. Four sessions made the same tool call
+against the same plugin cache on 2026-08-31. Two were answered with the body and
+shipped, and two were refused with `Skill canon:claude-autoship cannot be used
+with Skill tool due to disable-model-invocation`. Prefixing separated nothing,
+since three of the four carried the namespace and those three landed on both
+answers, so nothing a dispatcher writes predicts which answer a launch gets.
+
+Read that as a route a dispatch may not depend on rather than one that usually
+works. The refusal closes the fallback in the same message, telling the session
+not to replicate the workflow by other means, so a refused worker has no route
+left and stops with a clean worktree. Both failed dispatches produced nothing
+rather than a degraded run, which is the correct outcome and not a thing to
+soften.
+
+Recovery belongs to whoever writes the next prompt, since a blocked session
+cannot replay its own launch. The refusal is sticky inside a session rather than
+something a retry clears, measured when one refused worker repeated the identical
+prefixed call and got the byte-identical error back. So re-dispatch onto the same
+branch with the autoship call leading the prompt, which puts the one command the
+first launch left as prose in the position the client expands.
+
+A launch that leads with `/canon:claude-autoship <plan>` and names no worktree
+call is the candidate for closing this on the first dispatch, since that chain's
+Step 0 enters the worktree itself and `claude-worktree` carries no flag to
+refuse the tool route. Nobody has run it. Treat it as untested rather than as the
+shape to switch to, because a launch expansion cannot be read from inside the
+session it launched.
+
 ### What the brief may carry
 
 The prompt carries pointers and standing context, and stops there. The branch and the plan stay arguments, because a skill resolves an argument through a documented ladder and reads no prose at all. What the prose reaches is the worker's judgment, so it holds only what a session has to weigh:
@@ -123,6 +163,43 @@ registered branch off `main`, so `canon sessions list --branch` reports nothing
 holding it. A dispatch landing on a branch worked that way collides with
 nothing the check can see.
 
+## Dispatch to plan a row
+
+`claude-feature` is a procedure rather than a role, so a launch naming it alone
+reaches no `claude-planner` and takes no role, which owes no message either.
+Both trials on 2026-08-31 ran on prose the controller retyped into each launch,
+which held every obligation those sessions took and is where the first one's
+in-flight read went wrong. Reach the role directly on this launch, the way the
+build shape above reaches `claude-worker`.
+
+No branch and no worktree exist here and none is created. A planner writes one
+gitignored file at the main worktree root, so this shape names the row's task
+file rather than a branch and opens with the role instead of a worktree call.
+
+```bash
+claude --bg --model <model> -n "planner-<slug>" "Run /canon:claude-planner, then /canon:claude-feature <task>. Your controller is the session whose sessionId is <dispatcher-id>. Resolve its current name from that id at the moment you send, and never resolve an addressee by name prefix. Message it when the plan lands, carrying the path and what the task file got wrong, and message it again if you stop on a question."
+```
+
+`<task>` is the row's task file path and `<slug>` the slug its plan will take,
+resolved off the row the way the build shape resolves one off a plan.
+`<dispatcher-id>` and `<model>` resolve the same way they do above. The prefix
+reads `planner-` for the reason the worker's reads `worker-`, which is that it
+marks the role of the session it names rather than the one that launched it.
+
+Neither check above binds this shape. The branch check has no candidate to read,
+and the disjointness gate has nothing to compare, since a planner writes one file
+no track in flight can hold. What a planning dispatch owes instead is the
+reverse reading, because the plan it produces carries a constraint per track in
+flight and a row planned during a wave is planned against a tree that wave is
+changing. `claude-planner` states that read as a command over open pull
+requests, which is why the brief carries no branch list for it.
+
+One row per dispatch. A session reused across a batch pays the context load once
+and ages its picture of the tree while it works, which is what puts the in-flight
+read on the task rather than on the batch, and one that compacts mid-batch loses
+the reasoning behind its earlier plans with nothing reporting it. Cap a reused
+session where the saving is worth it and say what the cap was.
+
 ## 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: the collision check refused, the row's file set overlaps a track already out, or a stated reason holds the row behind one.

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

@@ -0,0 +1,85 @@
+---
+name: claude-planner
+description: What a planning session is, how it reads what is in flight, the surfaces it may not write, and what it hands back to whoever dispatched it
+---
+
+# Claude planner requirement
+
+## Gap
+
+Without this skill, a planning session is told what to plan and never what it
+is. `claude-worker` states the building role and `claude-autoship` 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
+`claude-orchestrate` already bans on the building side, where one half held the
+only written copy of obligations the other half performs.
+
+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 banned words either. `.gitignore` ignores
+`.claude/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.
+
+## Must
+
+- Assert what a planning session is, what it may not write, and how long the role lasts, since `claude-feature` carries the procedure and no body carries the role
+- State the in-flight read as a command over 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 plan 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
+- Point at `claude-feature` for the plan's shape and the steps that write it
+
+## Must not
+
+- Restate the plan's sections, its suggested-and-answer contract, or the steps `claude-feature` carries, since thinness is what keeps one body correct for a dispatched planner reading it as its whole contract
+- Restate a boundary `claude-orchestrate` or `claude-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
+- 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, the backlog, or the task file, at any size
+- Be a skill nothing invokes but its author typing the name. `orchestrator-dispatch.md` names it on the planning launch the way it names `claude-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 rather than falling back to a 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
+
+## Out of scope
+
+- The plan's sections and its answer contract, which `standards/plan.md` fixes, and the steps that write the file, which `claude-feature` owns
+- The branch, the build, and the pull request, which `claude-worker` and `claude-autoship` own
+- Deciding which rows run and in what order, which is the controlling session's call and stated in `claude-orchestrate`
+- The dispatch itself, its collision check, and its disjointness gate, which `orchestrator-dispatch.md` holds

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

@@ -0,0 +1,97 @@
+---
+name: claude-planner
+description: Asserts the planner role for a session writing one plan under one task, holding what it reads before deciding, the surfaces it may not write, and what it hands back. Use when asked to "be the planner", "you are a planner session", at the start of a dispatched or hand-launched planning run, or when a planning session needs to know what it may not write. Do NOT use to write the plan itself, which is `claude-feature`, to make the cross-feature merge call, or to implement.
+---
+
+# Claude planner
+
+This session is a planner: one session writing one plan for one task. It reads
+the row, measures what the row claims against the tree, writes the plan, 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.
+
+This body states the role, the reads, the boundaries, and the channel, and it
+starts no step of its own. `claude-feature` owns the steps that write the plan
+and cites the standard fixing its sections and its suggested-and-answer
+contract, so read the procedure there and reach it from the launch rather than
+from here.
+
+## Where the session stands
+
+- Write one file, the plan, at `.claude/plans/feature-<slug>.md` on the main worktree root. Everything else this session touches is a read.
+- Never enter a worktree, never create a branch, and never write a tracked file. A planner that builds has stopped being one, and the row loses the independent read the worker's own session was going to bring to it.
+- Resolve `.claude/plans/`, `.claude/tasks/`, and `.claude/review/` at the main worktree root. Those folders are gitignored, so a copy beside a linked worktree is absent rather than empty.
+- Plan the row the launch named. Report a second row met while reading rather than planning it, since which rows run is the controller's call.
+
+## What to read before deciding
+
+Each item below is something a plan 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 `.claude/ARCHITECTURE.md`, for the decision and the alternative it was taken against rather than for the decision alone.
+- The plan of any row this one is sequenced behind, including one already moved to `.claude/plans/archive/`. Reading a shipped plan produced the strongest constraint in the first trial and no brief asked for it.
+- `.claude/tasks/priority.md` for the row's Touches column and its stated blocker. That column is the file set the dispatch disjointness gate already reads.
+- `${CLAUDE_SKILL_DIR}/../../standards/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 `.claude/plans/` is gitignored and the audit's default path set is what git lists.
+
+## Read what is in flight rather than inferring it
+
+- Run `gh pr list --json number,headRefName`, then `git diff --name-only main...<headRefName>` per open pull request, and take every in-flight file set from that pair.
+- A branch is not evidence and neither is a worktree. This repository squash-merges and leaves both behind, so a count of either reports merged work as live. One trial named four branches as in flight and all four had merged.
+- Run the read once per task rather than once per batch. A session planning several rows ages its picture of the tree while it works, and this read is what dates it.
+- Name each in-flight set as a constraint, say which act it forbids, and stamp the block with the commit the tree was read at, per Constraints in the plan standard. A bare path list leaves the worker guessing.
+
+## The board is read-only
+
+- Never write `.claude/tasks/priority.md` or `.claude/tasks/backlog.md`. Both are gitignored, so an overwrite drops a row with no history to recover it from.
+- Never write the task file either. The plan is the whole output, and a row edited from here changes what the controller reads back as the state of the board.
+- 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 plan 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.
+
+## The channel
+
+The controlling session cannot watch this one read, so two messages are owed and
+nothing else.
+
+- Announce the plan as the file lands, carrying its path and what the task file got wrong. Write no summary of the plan 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. A session already waiting on input never reaches the tool round that drains an inbound message, so a relayed answer arrives under the open question and changes nothing.
+- Send nothing on progress. A planner reporting progress rebuilds, on this side of the channel, the poll the announcement retires on the other.
+
+Address the session the launch named. It names a `sessionId` rather than a name,
+so read `canon sessions list --json`, find the row carrying that id, and send to
+the `name` on it. Resolve that name at the moment of sending rather than at
+launch, since a name is derived from what a session turned out to be doing and
+goes stale inside the window a plan takes to write.
+
+Check that name against the agent listing before sending it. A name is not
+unique and the roster carries no field separating two live sessions holding one,
+so send it bare where the listing shows a single row under it and complete it
+with the `[ref]` that listing prints beside each row where it shows more.
+
+Ask the operator when the launch named nobody and a person is there to answer,
+putting the candidate rows through the structured question surface so they pick a
+row rather than recall a name. Never filter that roster by name prefix, which
+returns a sibling or this session itself.
+
+Inferring is the last rung and it discriminates less here than it does for a
+worker. That read takes the sessions holding no feature branch, which separates a
+controller from a worker because a worker holds one, and a planner holds none
+either, so every sibling planner 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.
+
+## 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 plan at all, and send that out as a message before it becomes a prompt.
+
+## Lifetime
+
+- The role runs from the launch to the plan landing, and one plan closes it. A planner handed a second row plans 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 task, and it accumulates toward a compaction that drops the reasoning behind its earlier plans with nothing reporting it. 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.

package/docs/agents/targets.md

@@ -13,15 +13,17 @@ description: The projects this toolkit installed into, the record the install wr
 canon targets list
 canon targets list --json
 canon targets list --sweep ~/repos --json
+canon targets list --sweep ~/repos --record
 ```
 
-| Option            | Behavior                                                |
-| ----------------- | ------------------------------------------------------- |
-| `--json`          | Add a machine-readable record on stdout                 |
-| `--sweep <path…>` | Also walk these roots for targets the record never held |
-| `--depth <n>`     | How deep below each swept root to walk, defaulting to 4 |
+| Option            | Behavior                                                                         |
+| ----------------- | -------------------------------------------------------------------------------- |
+| `--json`          | Add a machine-readable record on stdout                                          |
+| `--sweep <path…>` | Also walk these roots for targets the record never held                          |
+| `--depth <n>`     | How deep below each swept root to walk, defaulting to 4                          |
+| `--record`        | Seed the index from every swept checkout's own stamp, refusing without `--sweep` |
 
-Exit codes: `0` the population was read, `1` refused. A refusal carries a `reason` of `bad-depth`, and an absent index reports as unknown rather than as no targets.
+Exit codes: `0` the population was read, `1` refused. A refusal carries a `reason` of `bad-depth` or, for `--record` given with no `--sweep`, `record-without-sweep`. An absent index reports as unknown rather than as no targets.
 
 An exit code says nothing about a call made from a session, since a shell profile may wrap the binary in a function taking its status from a later command. Read the record's fields rather than the exit when a skill consumes this.
 
@@ -49,6 +51,12 @@ The row leads with the clone the record knows, because the record only names one
 
 Nothing removes a row. A project deleted, moved, or that dropped the toolkit stays in the index, so a count drifts upward over time. It surfaces on use rather than silently, since the read below refuses a path it cannot open.
 
+## The retired stamp path
+
+Each row names the subset of its checkouts still carrying the install stamp at the retired path: `legacyPaths` in the JSON, a subset of `paths` in the same order. The render says `legacy stamp` plain when every checkout carries it and `legacy stamp (1 of 2 checkouts)` when only some do, which is the common case rather than the rare one.
+
+`--record` backfills the index from a sweep rather than from a sync, for a target the record never held. It seeds one row per checkout from that checkout's own installed stamp, taking `stampedAt` from the stamp itself rather than from the moment the backfill ran, so a backfilled row never claims a sync that did not happen. A checkout whose stamp cannot be read is skipped rather than dated by the backfill. It refuses without `--sweep` naming what to walk.
+
 ## Pulls
 
 `canon targets pulls` reports, per target, every open pull request with its checks and the heading its newest review pass carries.

package/docs/ai-workflow.md

@@ -75,7 +75,7 @@ When features are independent, run them in parallel instead of sequentially. Use
 - Ship each worktree separately with `canon:git-ship`
 - For full autonomy per worktree, invoke `canon:claude-autoship` instead of the manual chain. Approve the plan, walk away, come back to draft PRs.
 
-To run several worktrees as a coordinated flow rather than ad hoc, assert the orchestrator role in one warm session with `canon:claude-orchestrate`. It plans each feature, refills the ready queue so a free worker never waits, and reviews each worker's PR with `canon:claude-pr-review`, then tells the session holding that branch to run `canon:claude-address-review` whenever the pass posted a finding at any severity, which is the same threshold `canon:claude-pr-review` states and posts its open heading under. The human launches workers and merges. See [operating model](operating-model.md) for the full loop.
+To run several worktrees as a coordinated flow rather than ad hoc, assert the orchestrator role in one warm session with `canon:claude-orchestrate`. It holds the cross-feature call, plans each feature itself or dispatches a cold planner under `canon:claude-planner` to write the plan, refills the ready queue so a free worker never waits, and reviews each worker's PR with `canon:claude-pr-review`, then tells the session holding that branch to run `canon:claude-address-review` whenever the pass posted a finding at any severity, which is the same threshold `canon:claude-pr-review` states and posts its open heading under. The human launches workers and merges. See [operating model](operating-model.md) for the full loop.
 
 Execution order comes off `.claude/tasks/priority.md` and nothing sequences work into versions. Scope stays in `.claude/REQUIREMENTS.md` as a statement of what is wanted, and it reaches the board as discrete tasks the orchestrator orders by readiness.
 

package/docs/index.md

@@ -14,7 +14,7 @@ One-line reference for each doc in this folder.
 
 ## Workflow
 
-- [Operating model](operating-model.md): Orchestrator and worker roles for building across parallel sessions
+- [Operating model](operating-model.md): Orchestrator, planner, and worker roles for building across parallel sessions
 - [Visual design workflow](visual-design-workflow.md): Tiered guide for design and wireframe authoring with Claude Code
 - [Zshrc aliases for Claude Code](zshrc-aliases.md): Shell aliases that shorten common Claude Code invocations
 

package/docs/operating-model.md

@@ -1,33 +1,53 @@
 ---
 title: Operating model
-description: Orchestrator and worker roles for building across parallel sessions
+description: Orchestrator, planner, and worker roles for building across parallel sessions
 category: Workflow
 ---
 
 # Operating model
 
 A way to build fast and reliably across parallel Claude Code sessions without a
-loop and without losing the human review gate. One warm session plans and
-reviews. Cold worker sessions build. The human launches workers and merges.
+loop and without losing the human review gate. One warm session holds the
+cross-feature call and reviews. Planning runs there or in a session of its own.
+Cold worker sessions build. The human launches workers and merges.
 
 This page covers the roles and the loop. For the worktree mechanism (isolation, merge
 order, port collisions), see [Claude Code and git worktrees](../wiki/claude/claude-worktrees.md).
 
-## Two roles
+## Three roles
 
-The split is by vantage, not by capability. Both are Claude Code sessions.
+The split is by vantage, not by capability. All three are Claude Code sessions.
 
-| Role         | Session                               | Owns                                                    | Does not                      |
-| ------------ | ------------------------------------- | ------------------------------------------------------- | ----------------------------- |
-| Orchestrator | One warm, long-lived session          | Planning, deep PR review, merge order                   | Edit tracked files, merge PRs |
-| Worker       | One cold worktree session per feature | Implement, self-check, open PR, answer the orchestrator | Write the shared board, merge |
+| Role         | Session                               | Owns                                                    | Does not                          |
+| ------------ | ------------------------------------- | ------------------------------------------------------- | --------------------------------- |
+| Orchestrator | One warm, long-lived session          | The cross-feature call, deep PR review, merge order     | Edit tracked files, merge PRs     |
+| Planner      | One session per row, warm or cold     | Measure the row against the tree, write one plan        | Enter a worktree, write the board |
+| Worker       | One cold worktree session per feature | Implement, self-check, open PR, answer the orchestrator | Write the shared board, merge     |
 
 Each role is asserted explicitly rather than inferred. The orchestrator loads
-`claude-orchestrate` at the start of its session, and a worker loads
-`claude-worker`, which `claude-autoship` invokes at Step 0 so a dispatched build
-and a hand-launched one reach it on the same path. Both are framing and
+`claude-orchestrate` at the start of its session, a worker loads `claude-worker`,
+which `claude-autoship` invokes at Step 0 so a dispatched build and a
+hand-launched one reach it on the same path, and a planner loads
+`claude-planner` from the launch that dispatches it. All three are framing and
 boundaries rather than logic.
 
+The planner is the one role the orchestrator also performs. Per-row planning
+runs warm inside the orchestrator's own session or cold in a dispatched one, and
+the boundary between them is the cross-feature call: which rows collide, what
+merges before what, and whether a row should run at all stay with the
+orchestrator, because a session reading the board sees blockers and file sets
+and can write a confident merge order off a partial picture. Two trials on
+2026-08-31 measured a cold planner against four rows and it reported ten things
+the task files got wrong, which is why the per-row measurement is free to go
+cold. No plan from either trial has been built, so a cold plan's value to the
+worker reading it is still unmeasured.
+
+A dispatched planner owes two messages: the plan's path as the file lands, with
+what the task file got wrong beside it, and a block before that block becomes an
+interactive prompt. The plan file is its only write. A stale count, a moved line,
+or a path that no longer resolves is reported rather than repaired, since the
+task file and the board stay the orchestrator's to write.
+
 Refusing is part of the worker's job rather than a failure of it. A worker that
 halts on a plan question it may not answer, or argues back against an
 instruction the tree contradicts, is working correctly. The four measured halts
@@ -49,7 +69,7 @@ and no later session recovers that vantage.
 
 One feature travels this path end to end.
 
-1. Orchestrator plans the next feature with `claude-feature`, writing a plan to `.claude/plans/`. Planning stays in the warm session because good planning is cross-feature. It needs the contract other features consume and the shared wiring seam. A cold session would re-derive or guess.
+1. The next feature is planned with `claude-feature`, writing a plan to `.claude/plans/`. The orchestrator runs it warm when the row turns on a contract other features consume or a shared wiring seam, and dispatches a planner under `claude-planner` otherwise. A cold planner measures the row against the tree rather than trusting what the row claims, and it reads what is in flight from open pull requests rather than from branches and worktrees, which this repository leaves behind after a squash merge.
 2. Orchestrator checks the branch is unclaimed and the plan's file set is disjoint from every track in flight, then dispatches a background worker with `claude --bg` against the plan, naming the branch and the model on the launch rather than leaving the worker to derive either. No count caps how many run at once. The branch travels as the argument to the worker's own worktree call, which is the one place the name is read rather than inferred. It falls back to naming the invocation for a human to run through `claude-worktree` and `claude-autoship` when the check refuses, the sets overlap, or a stated reason serializes the plan behind a track already in flight. Either way, the worker enters its own worktree, builds, self-checks, opens a PR, and stops at the PR boundary.
 3. Orchestrator reviews the PR with `claude-pr-review` and posts findings to it.
 4. Orchestrator tells the session holding that branch to run `claude-address-review` once the pass posted a finding at any severity, resolving the target then with `canon sessions list --branch` and reporting the invocation for the human when no live session holds it. The worker addresses the findings, rebases onto `origin/main` when a sibling landed first and left the branch unable to merge, then pushes a follow-up. A pass carrying only minor findings dispatches too, since the grade runs low often enough that a floor at should-fix loses fixes a worker would have made. `claude-pr-review` states that threshold and the heading follows it, so an open heading is itself the signal to send.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@erclx/canon",
   "type": "module",
-  "version": "4.1.0",
+  "version": "4.2.0",
   "description": "Infrastructure and quality tooling for developer workflows",
   "license": "MIT",
   "bin": {

package/src/claude/cases/claude-workflow.ts

@@ -70,6 +70,11 @@ export const CLAUDE_WORKFLOW_CASES: readonly SkillCase[] = [
       'Take on the orchestrator role and coordinate the parallel feature builds.',
     expect: 'claude-orchestrate',
   },
+  {
+    prompt:
+      'I am writing the plan for a row another session will build. What may I write, and where do I read what is already in flight?',
+    expect: 'claude-planner',
+  },
   {
     prompt: 'Post a formal review with findings on that open pull request.',
     expect: 'claude-pr-review',

package/src/commands/targets.ts

@@ -1,13 +1,16 @@
 import type { Command } from 'commander'
+import { readStamp } from '@/sync/stamp'
 import { readPullsAcross, type TargetPulls } from '@/targets/pulls'
+import { backfillTarget } from '@/targets/registry'
 import {
   type KnownTarget,
   type ResolvedTargets,
   resolveTargets,
 } from '@/targets/resolve'
-import { DEFAULT_DEPTH, type SweepBound } from '@/targets/sweep'
+import { DEFAULT_DEPTH, type SweepBound, sweepTargets } from '@/targets/sweep'
 import {
   intro,
+  logError,
   logInfo,
   logStep,
   logWarn,
@@ -20,6 +23,7 @@ interface ListOptions {
   readonly json?: boolean
   readonly sweep?: string[]
   readonly depth?: string
+  readonly record?: boolean
 }
 
 interface PullsOptions extends ListOptions {}
@@ -65,6 +69,10 @@ export function register(program: Command): void {
       'How deep below each swept root to walk',
       String(DEFAULT_DEPTH),
     )
+    .option(
+      '--record',
+      "Seed the index from every swept checkout's own stamp, refusing without --sweep",
+    )
     .addHelpText('after', LIST_HELP)
     .action(async (opts: ListOptions) => {
       process.exitCode = await runList(opts)
@@ -111,6 +119,15 @@ const LIST_HELP = [
   'see another machine or a clone under a path nobody named, so read the bound',
   'before treating the count as the population.',
   '',
+  'A group reports how many of its checkouts still carry the install stamp',
+  'at the retired path, staying quiet when none do and plain when every one',
+  'does.',
+  '',
+  '--record backfills the index from a sweep rather than a sync. It seeds one',
+  "row per checkout from that checkout's own installed stamp, so a backfilled",
+  'row never claims a sync that did not run, and it refuses without --sweep',
+  'naming what to walk.',
+  '',
   'An exit code says nothing about a call made from a session, since a shell',
   'profile may wrap the binary in a function taking its status from a later',
   'command. Read the record rather than the exit when a skill consumes this.',
@@ -119,6 +136,7 @@ const LIST_HELP = [
   '  canon targets list',
   '  canon targets list --json',
   '  canon targets list --sweep ~/repos --json',
+  '  canon targets list --sweep ~/repos --record',
   '',
 ].join('\n')
 
@@ -155,6 +173,18 @@ async function runList(opts: ListOptions): Promise<number> {
 
   if (depth === null) return refuseDepth(opts)
 
+  let backfillFailed = false
+
+  if (opts.record === true) {
+    if (opts.sweep === undefined || opts.sweep.length === 0) {
+      return refuseRecordWithoutSweep(opts)
+    }
+
+    const backfill = await runBackfill(opts.sweep, depth)
+    reportBackfill(backfill)
+    backfillFailed = backfill.failed > 0
+  }
+
   const resolved = await resolveTargets({ sweep: opts.sweep, depth })
 
   const unknown = reportTargets(resolved)
@@ -172,7 +202,7 @@ async function runList(opts: ListOptions): Promise<number> {
     )
   }
 
-  return unknown ? 1 : 0
+  return unknown || backfillFailed ? 1 : 0
 }
 
 async function runPulls(paths: string[], opts: PullsOptions): Promise<number> {
@@ -234,6 +264,89 @@ function refuseDepth(opts: ListOptions): number {
   return 1
 }
 
+interface BackfillSummary {
+  readonly recorded: number
+  readonly skipped: number
+  readonly failed: number
+}
+
+/**
+ * Seeds the index from every checkout the sweep finds. `resolveTargets` walks
+ * the same roots again right after this returns, which costs a second walk
+ * rather than a restructure, since --record is a deliberate one-off rather
+ * than a path any routine run takes.
+ */
+async function runBackfill(
+  roots: readonly string[],
+  depth: number,
+): Promise<BackfillSummary> {
+  const swept = await sweepTargets(roots, { depth })
+  const paths = swept.targets.flatMap((target) => target.paths)
+
+  let recorded = 0
+  let skipped = 0
+  let failed = 0
+
+  for (const path of paths) {
+    const outcome = backfillTarget({ path, stampedAt: stampedAtOf(path) })
+    if (outcome === 'recorded') recorded++
+    else if (outcome === 'no-stamp') skipped++
+    else failed++
+  }
+
+  return { recorded, skipped, failed }
+}
+
+/**
+ * The most recent syncedAt across a checkout's stamped domains, so a
+ * backfilled row dates itself by the sync that actually touched the checkout
+ * rather than by the moment the backfill happened to run.
+ */
+function stampedAtOf(path: string): string | null {
+  const stamp = readStamp(path)
+  if (stamp === undefined) return null
+
+  const syncedAt = Object.values(stamp.domains)
+    .map((domain) => domain?.syncedAt)
+    .filter((value): value is string => value !== undefined)
+    .sort()
+
+  return syncedAt.at(-1) ?? null
+}
+
+function refuseRecordWithoutSweep(opts: ListOptions): number {
+  logStep('Refused')
+  logWarn(
+    '--record backfills from a walk, so it needs --sweep naming the roots to walk.',
+  )
+  outro()
+
+  if (opts.json) {
+    process.stdout.write(
+      `${JSON.stringify({ reason: 'record-without-sweep', targets: [] })}\n`,
+    )
+  }
+
+  return 1
+}
+
+function reportBackfill(summary: BackfillSummary): void {
+  logStep('Backfill')
+  logInfo(`${plural(summary.recorded, 'target')} recorded from its own stamp.`)
+
+  if (summary.skipped > 0) {
+    logWarn(
+      `${plural(summary.skipped, 'target')} skipped, carrying no readable stamp to date the row by.`,
+    )
+  }
+
+  if (summary.failed > 0) {
+    logError(
+      `${plural(summary.failed, 'target')} failed to write, so its row is unchanged.`,
+    )
+  }
+}
+
 /** Returns whether the population is unknown, which is the one refusal this read has. */
 function reportTargets(resolved: ResolvedTargets): boolean {
   logStep('Targets')
@@ -256,13 +369,27 @@ function reportTargets(resolved: ResolvedTargets): boolean {
 }
 
 function describe(target: KnownTarget): string {
-  const flags = [target.source, ...(target.legacy ? ['legacy stamp'] : [])]
+  const flags = [target.source, ...legacyFlag(target)]
   const clones =
     target.paths.length > 1 ? `\n  ${target.paths.slice(1).join('\n  ')}` : ''
 
   return `${target.paths[0]}  ${flags.join(', ')}${clones}`
 }
 
+/**
+ * "legacy stamp" plain when every checkout carries the retired stamp, the
+ * count appended when only some do, and nothing when none do. The mixed case
+ * is the one a bare flag could not say, and it is the common one: three of
+ * the four affected groups measured on this machine were mixed rather than
+ * uniform.
+ */
+function legacyFlag(target: KnownTarget): readonly string[] {
+  const count = target.legacyPaths.length
+  if (count === 0) return []
+  if (count === target.paths.length) return ['legacy stamp']
+  return [`legacy stamp (${count} of ${target.paths.length} checkouts)`]
+}
+
 function reportBound(bound: SweepBound): void {
   logStep('Bound')
   logInfo(

package/src/targets/registry.ts

@@ -201,3 +201,26 @@ export function recordTarget(
     return 'unwritten'
   }
 }
+
+/** One checkout a backfill is seeding, dated by its own on-disk stamp. */
+export interface BackfillTarget {
+  readonly path: string
+  /** From that checkout's `readStamp`. Null skips the row rather than dating it by the backfill itself. */
+  readonly stampedAt: string | null
+}
+
+export type BackfillOutcome = RecordOutcome | 'no-stamp'
+
+/**
+ * Seeds one row from a checkout's own stamp rather than from a sync, for a
+ * target a sweep found that the record never held. Loops `recordTarget`,
+ * which already replaces a row by resolved path, so this is a caller of it
+ * rather than a second file format.
+ */
+export function backfillTarget(
+  target: BackfillTarget,
+  path: string = registryPath(),
+): BackfillOutcome {
+  if (target.stampedAt === null) return 'no-stamp'
+  return recordTarget(target.path, new Date(target.stampedAt), path)
+}

package/src/targets/resolve.ts

@@ -27,8 +27,8 @@ export interface KnownTarget {
   readonly source: TargetSource
   /** When a sync last recorded this target, or null for a row only a sweep found. */
   readonly stampedAt: string | null
-  /** True while the install stamp still sits at the retired path. */
-  readonly legacy: boolean
+  /** The subset of `paths` still carrying their stamp at the retired location, in `paths` order. */
+  readonly legacyPaths: readonly string[]
 }
 
 export interface ResolvedTargets {
@@ -80,7 +80,7 @@ export async function resolveTargets(
           origin: null,
           source: 'record' as const,
           stampedAt: row.stampedAt,
-          legacy: isLegacyStamped(row.path),
+          legacyPaths: isLegacyStamped(row.path) ? [row.path] : [],
         }))
       : []
 
@@ -110,14 +110,22 @@ export async function resolveTargets(
     // Every caller reading a single path takes the first, and picking that by
     // sort order is how a repair ran in one clone while the count was taken
     // against another and the target read as untouched.
+    const paths = [
+      ...overlap,
+      ...target.paths.filter((path) => !known.has(path)),
+    ]
+
+    // Re-derived against this row's own order rather than carried from
+    // `target.legacyPaths`, which is ordered by the sweep's sort and mismatches
+    // `paths` the moment the recorded clone is not the one that sorts first.
     added.push({
-      paths: [...overlap, ...target.paths.filter((path) => !known.has(path))],
+      paths,
       origin: target.origin,
       source: overlap.length > 0 ? 'record' : 'sweep',
       stampedAt:
         recorded.find((row) => overlap.includes(row.paths[0] ?? ''))
           ?.stampedAt ?? null,
-      legacy: target.legacy,
+      legacyPaths: paths.filter((path) => isLegacyStamped(path)),
     })
   }
 
@@ -140,6 +148,6 @@ function given(path: string): KnownTarget {
     origin: null,
     source: 'given',
     stampedAt: null,
-    legacy: isLegacyStamped(path),
+    legacyPaths: isLegacyStamped(path) ? [path] : [],
   }
 }

package/src/targets/sweep.ts

@@ -2,7 +2,12 @@ import { readdirSync } from 'node:fs'
 import { join, resolve } from 'node:path'
 import { $ } from 'bun'
 import { gitEnv } from '@/git-env'
-import { isLegacyStamped, legacyStampPath, stampPath } from '@/sync/stamp'
+import {
+  isLegacyStamped,
+  legacyStampPath,
+  retiredNameStampPath,
+  stampPath,
+} from '@/sync/stamp'
 import { isDirectory } from '@/target'
 
 /**
@@ -44,8 +49,8 @@ export interface SweptTarget {
   readonly paths: readonly string[]
   /** The origin every path agrees on, or null when git resolved none. */
   readonly origin: string | null
-  /** True while every path still carries its stamp at the retired location. */
-  readonly legacy: boolean
+  /** The subset of `paths` still carrying their stamp at the retired location, in `paths` order. */
+  readonly legacyPaths: readonly string[]
 }
 
 /**
@@ -85,10 +90,17 @@ export interface SweepOptions {
   readonly originOf?: (path: string) => Promise<string | null>
 }
 
-/** Whether a folder carries an install stamp at either the current or the retired path. */
+/**
+ * Whether a folder carries an install stamp at the current path or either
+ * retired one. `aitk@3.57.0` still writes the folder form,
+ * `retiredNameStampPath`, as its current path, so a target a pre-rename
+ * binary syncs after this check drops the folder form would otherwise vanish
+ * from the walk with nothing saying so.
+ */
 function isStamped(path: string): boolean {
   return (
     Bun.file(stampPath(path)).size > 0 ||
+    Bun.file(retiredNameStampPath(path)).size > 0 ||
     Bun.file(legacyStampPath(path)).size > 0
   )
 }
@@ -225,7 +237,11 @@ async function group(
     const origin = origins[index]
 
     if (origin === null || origin === undefined) {
-      alone.push({ paths: [path], origin: null, legacy: isLegacyStamped(path) })
+      alone.push({
+        paths: [path],
+        origin: null,
+        legacyPaths: isLegacyStamped(path) ? [path] : [],
+      })
       return
     }
 
@@ -237,7 +253,7 @@ async function group(
   const merged = [...byOrigin.entries()].map(([origin, group]) => ({
     paths: group,
     origin,
-    legacy: group.every((path) => isLegacyStamped(path)),
+    legacyPaths: group.filter((path) => isLegacyStamped(path)),
   }))
 
   return [...merged, ...alone].sort((a, b) =>