@erclx/canon 5.26.0 → 5.28.0

package/docs/agents/tasks-validate.md

@@ -1,6 +1,6 @@
 ---
 title: Tasks validate
-description: Validating the board against the tree, the seven checks, the untested, claims, wide, and unplaced arrays, the exit codes, and the refusal reasons
+description: Validating the board against the tree, the seven checks, the five report arrays, the exit codes, and the refusal reasons
 ---
 
 # Tasks validate
@@ -12,17 +12,17 @@ canon tasks validate
 canon tasks validate --json
 ```
 
-Seven checks run. Collisions reaches one half of the `## Run now` test the board standard states, and Plan reaches every group, reading the Plan column under `## Run now` and the task file's own line under the other two. Mapping and Grouping test the folder contract and hold for every group, and Shape holds for every group too, ahead of the four. Ordering reaches only the `## Needs a plan` rows, and Blockers reaches every row outside `## Run now`:
+Seven checks run. Touches reaches only the `## Run now` rows, asking each to name its files, and Plan reaches every group, reading the Plan column under `## Run now` and the task file's own line under the other two. Mapping and Grouping test the folder contract and hold for every group, and Shape holds for every group too, ahead of the four. Ordering reaches only the `## Needs a plan` rows, and Blockers reaches every row outside `## Run now`:
 
-| Check      | What it reports                                                                                                         |
-| ---------- | ----------------------------------------------------------------------------------------------------------------------- |
-| Shape      | A row whose cell count disagrees with its table's header, or one stranded behind a table a blank line already closed    |
-| Plan       | A row whose plan citation disagrees with its group or its task file, or a task whose `Plan:` line lists one plan twice  |
-| Mapping    | A row or backlog line naming no task file                                                                               |
-| Grouping   | A task carrying a row in more than one readiness group, or on both surfaces                                             |
-| Ordering   | A `## Needs a plan` row whose stated position disagrees with where it actually sits, or which states no position at all |
-| Collisions | Two `## Run now` rows whose Touches columns name a path in common                                                       |
-| Blockers   | A parked row whose blocker has stopped holding, whose cited task resolves nowhere, or whose cited task was declined     |
+| Check    | What it reports                                                                                                         |
+| -------- | ----------------------------------------------------------------------------------------------------------------------- |
+| Shape    | A row whose cell count disagrees with its table's header, or one stranded behind a table a blank line already closed    |
+| Plan     | A row whose plan citation disagrees with its group or its task file, or a task whose `Plan:` line lists one plan twice  |
+| Mapping  | A row or backlog line naming no task file                                                                               |
+| Grouping | A task carrying a row in more than one readiness group, or on both surfaces                                             |
+| Ordering | A `## Needs a plan` row whose stated position disagrees with where it actually sits, or which states no position at all |
+| Touches  | A `## Run now` row whose Touches column names no file                                                                   |
+| Blockers | A parked row whose blocker has stopped holding, whose cited task resolves nowhere, or whose cited task was declined     |
 
 Shape runs before any other check reads a row, since a row failing it carries no dependable fields for the rest to check. A blank or prose line closes the table above it, so the walk treats the next pipe line as a fresh header candidate rather than as a continuation. That candidate counts as a header only when the line behind it is a separator carrying the same cell count, and one that fails is `row-untabled`, stranded behind a table that already closed. Cell count still has to match the header on every row that clears that test, and a row whose count disagrees is `row-misshapen`, the shape a dropped pipe or a merged column produces.
 
@@ -42,9 +42,9 @@ The ordinal phrase is prose rather than data, searched for anywhere in the cell
 
 The comparative phrase is bounded the same way and for the same reason. A closed verb list of `leads`, `heads`, `opens`, `closes`, `trails`, `precedes`, `follows`, `outranks`, and `sits under`, `above`, or `below` has to sit in one clause with a positional object, which is a `vNN.N` phase label, the word `group`, or `row` or `rows`. Both halves are needed, since a cell reading `it closes a gap the reference gate leaves open` carries the verb and claims no position, and the clause bound is what stops a verb in one half of the cell pairing with an object in the other. An ordinal exempts the row, being a comparative claim already. An unusual comparative phrasing reports as unranked, the safe direction for a check over prose, and a vocabulary verb reaching a positional object non-positionally reports as ranked, which only grading prose could separate.
 
-The collision check is the one a person cannot run by eye. Paths come from the backticked spans in the Touches column, a span naming no file is dropped, and a directory collides with any file beneath it. A `## Run now` row whose column parses to nothing is reported rather than skipped, since a row stating no file set makes a claim nothing can check.
+The Touches check is the one a person cannot run by eye. Paths come from the backticked spans in the Touches column, a span naming no file is dropped, and a directory shares any file beneath it. A `## Run now` row whose column parses to nothing is `touches-unstated`, since a row stating no file set makes a claim nothing can check.
 
-Where a directory holds the other row's file, the finding names the row that claimed it, reading `both touch src/tasks, which v2.0-second claims as a folder.` The shared strings alone leave an over-broad cell and a genuine overlap identical. <!-- canon-allow-reference: illustrates the finding's own sentence shape, not a citation of a real task -->
+Two `## Run now` rows naming a path in common land in a second array, `shared`, which moves no exit code since the branch merging second rebases. Merge order reads it, as does a dispatcher weighing a contract, relocation, or sweep hold. Where a directory holds the other row's file, the entry names the row that claimed it, reading `both touch src/tasks, which v2.0-second claims as a folder.` The shared strings alone leave an over-broad cell and a genuine overlap identical. <!-- canon-allow-reference: illustrates the entry's own sentence shape, not a citation of a real task -->
 
 The blocker check re-takes a measurement the board records once and never repeats. Two of the five blocker kinds put a fact on disk: a dependency is settled by the cited task being archived or by its work reaching the trunk, and a collision is settled by nothing under `## Run now` still holding the file the cell cites. A cited task resolving under `.canon/tasks/declined/` instead reports separately as `blocker-declined`, since a decided-against task is neither the shipped work `blocker-settled` reports nor the dangling pointer `blocker-unresolved` reports.
 
@@ -69,7 +69,7 @@ Both halves gate on a citation inside the `Waiting on` cell, never on the column
 
 A citation resolving in none of the board, the archive, or the declined folder is `blocker-unresolved` rather than a settled row. Reading an absent file as archived or declined states a specific fact about a file nobody ever wrote, which is what a renamed task or a typo produces, and only a task that genuinely closed or was genuinely declined releases the row waiting on it.
 
-The other three kinds rest on a person's judgment, so a row neither half reached lands in a second array rather than in the findings:
+The other three kinds rest on a person's judgment, so a row neither half reached lands in a third array rather than in the findings:
 
 ```json
 {
@@ -85,7 +85,7 @@ The other three kinds rest on a person's judgment, so a row neither half reached
 
 An untested row is not a finding and moves no exit code. Reading a clean findings list as a clean board is the failure the array exists to prevent, and `orchestrator-parked.md` is the pass that takes those rows by hand.
 
-A `## Run now` row whose Touches column names a bare folder lands in a third array on the same reasoning:
+A `## Run now` row whose Touches column names a bare folder lands in a fourth array on the same reasoning:
 
 ```json
 {
@@ -101,11 +101,11 @@ A `## Run now` row whose Touches column names a bare folder lands in a third arr
 
 That claim collides with every row a later session writes under the folder, and it is legitimate whenever the row does rewrite the directory, so the array states the reach and moves no exit code. A measure failing on a cell that is right teaches a reader to skip it. Folder against file is decided by asking the tree for a path that resolves, and by the extension only for a path the row has yet to create, since the name alone reads a file carrying no extension as a folder.
 
-The scan reaches `## Run now` and stops, where the collision check stops. A cell in another group describes work nobody has planned, written as a sentence and rewritten once a plan exists, so a claim read off one reports on prose rather than on a file set. A parked folder claim surfaces when its row is promoted, which is when the cell becomes something a dispatcher can act on.
+The scan reaches `## Run now` and stops, where the Touches check stops. A cell in another group describes work nobody has planned, written as a sentence and rewritten once a plan exists, so a claim read off one reports on prose rather than on a file set. A parked folder claim surfaces when its row is promoted, which is when the cell becomes something a dispatcher can act on.
 
-A code span in any cell that the preview cannot break lands in a fourth array, `wide`, with the same `group`, `subject`, and `message` fields. The scan measures a span's longest whitespace-free run and flags one past 60 characters, or a brace-glob at any width. A 57-character span fit the pane and a 78-character one did not, so the limit is a heuristic and the array moves no exit code. A link target is skipped, since only its label renders, and the scan reaches every group, since the overflow it exists for sat under `## Up next`.
+A code span in any cell that the preview cannot break lands in a fifth array, `wide`, with the same `group`, `subject`, and `message` fields. The scan measures a span's longest whitespace-free run and flags one past 60 characters, or a brace-glob at any width. A 57-character span fit the pane and a 78-character one did not, so the limit is a heuristic and the array moves no exit code. A link target is skipped, since only its label renders, and the scan reaches every group, since the overflow it exists for sat under `## Up next`.
 
-A task file neither surface names lands in a fifth array, on the same reasoning:
+A task file neither surface names lands in a sixth array, on the same reasoning:
 
 ```json
 {

package/docs/agents/tasks.md

@@ -118,6 +118,6 @@ canon tasks list --json | jq -r '.tasks[] | select(.readiness == "backlog") | .s
 
 ## Validate
 
-`canon tasks validate` reports what each row of `priority.md` and each line of `backlog.md` claims against what the tree holds. Its seven checks, the four arrays that move no exit code, and the refusals are in `tasks-validate.md`.
+`canon tasks validate` reports what each row of `priority.md` and each line of `backlog.md` claims against what the tree holds. Its seven checks, the five arrays that move no exit code, and the refusals are in `tasks-validate.md`.
 
 For the board format, see `standards/board.md`. For the `Pull request:` line and the archive rules, see `standards/tasks.md`.

package/docs/workflow/operating-model.md

@@ -11,8 +11,8 @@ 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/worktrees.md).
+This page covers the roles and the loop. For merge order and fan-out rules, see
+[Parallel features](parallel-features.md), and for worktree gotchas, [Claude Code and git worktrees](../../wiki/claude/worktrees.md).
 
 ## Four roles
 
@@ -34,7 +34,7 @@ it. All four 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
+the boundary between them is the cross-feature call: which rows conflict, 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. The per-row
@@ -62,20 +62,20 @@ Filing that row stops at the defect and the surface it was seen on. How far the
 defect reaches and what causes it belong to whoever plans the row, so it arrives
 carrying neither a count nor an asserted mechanism, and the seat that found it
 says as much in a plain sentence rather than supplying either. What separates the
-two is what a measurement decides: the blocker re-test, the collision check, and
-the file set compared against every track in flight all decide whether a row can
+two is what a measurement decides: the blocker re-test, the branch check, and
+the conflict check against every track in flight all decide whether a row can
 start, and only a count of the defect's extent decides how big it is.
 
 ## The loop
 
 One feature travels this path end to end.
 
-1. The next feature is planned with `plan-feature`, writing a plan to `.canon/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 `role-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 by composing the live session roster with open pull requests. A bare branch or worktree is not evidence on its own, since this repository leaves both behind after a squash merge.
-2. Orchestrator checks the plan waits on nobody, checks the branch is unclaimed, and checks 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 `session-worktree` and `auto-ship` when the plan still waits on an answer only the operator can give, 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.
+1. The next feature is planned with `plan-feature`, writing a plan to `.canon/plans/`. The orchestrator runs it warm when the row turns on a contract other features consume or a dependency on another row, and dispatches a planner under `role-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 by composing the live session roster with open pull requests. A bare branch or worktree is not evidence on its own, since this repository leaves both behind after a squash merge.
+2. Orchestrator checks the plan waits on nobody, checks the branch is unclaimed, and checks no conflict holds the plan behind a 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 `session-worktree` and `auto-ship` when the plan still waits on an answer only the operator can give, the branch check refuses, or a conflict holds 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. A reviewer under `role-reviewer`, or the orchestrator, posts `review-pr` findings, and `review-ui` drives any visual checklist beside it.
-4. Orchestrator tells the session holding that branch to run `review-address` 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. `review-pr` states that threshold and the heading follows it, so an open heading is itself the signal to send.
+4. Orchestrator tells the session holding that branch to run `review-address` 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 on a file it writes, 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. `review-pr` states that threshold and the heading follows it, so an open heading is itself the signal to send.
 5. Orchestrator closes the review out with `review-pr` again. The second pass reads only the commits the follow-up added, or the worker's response alone when the follow-up added none, and posts under `## Review` when it finds anything and under `## Review closed` when it finds nothing, so a reader learns from the heading whether work is still owed and takes the merge decision from the counts on the line under it. A pass finding nothing where a close-out already stands rewrites that comment to cover what it read rather than posting a second one, so the thread carries one live verdict. Repeat from step 4 until a pass closes the review.
-6. The human reads the result and merges. The orchestrator tells any trailing worker whose branch shares a seam with the merged one to run `review-address`, which rebases whether or not the review left anything open.
+6. The human reads the result and merges. After each merge, the orchestrator tells any trailing worker whose files the merged diff touches to run `review-address`, which rebases whether or not the review left anything open.
 
 There is no loop construct here. Each worker is a single build that halts at the
 PR. The merge stays a manual human gate. Reliability comes from the plan being
@@ -148,8 +148,8 @@ whether the branch is blocked, so the pass reads the worker's response rather th
 a delta and names its body from that response instead of from a tree that did not
 change.
 
-A branch that stopped merging while the review was open is the worker's problem
-to close. `review-address` rebases onto `origin/main` between the fixes
+A branch `main` moved under during review, conflicting or not, is the worker's
+problem to close. `review-address` rebases onto `origin/main` between the fixes
 and the push, so one force-push carries both and the reviewer reads one delta.
 The staleness test sits ahead of the no-findings guard, so a branch whose review
 closed clean and then went stale still rebases when the skill is invoked. The
@@ -200,12 +200,7 @@ before another is carried nowhere at all.
 
 ## Parallelism
 
-The binding constraint is the human and the shared files rather than the board.
-No number caps worker tracks. Open one whenever its file set is disjoint from
-every track already in flight, compared at the file path rather than at a folder
-above it, and stop adding once you can no longer review every output properly.
-Serialize a track sharing a wiring seam with another, and serialize one whose
-sets are disjoint when a stated reason still puts it behind another.
+Review attention binds, and no number caps worker tracks, so stop adding once you cannot review every output. A row waits only on a conflict a merge cannot settle, which the `role-orchestrator` dispatch runbook states once. A shared file is not one: both rows build, and the branch merging second resolves any conflict in its own session after the first lands, since no practice source serializes on a file. [Fowler](https://martinfowler.com/articles/branching-patterns.html) has whoever integrates second check health "even if it's a clean merge", and [DORA](https://dora.dev/capabilities/trunk-based-development/) keeps branches to hours with no integration phase.
 
 Review splits by vantage. A reviewer under `role-reviewer` takes a pull
 request's read, first pass included, when three await one (a number set by
@@ -225,12 +220,11 @@ Unit checks run freely in many worktrees at once.
 A dev server, an end-to-end run, and a screenshot run alongside each other on a
 web stack, since every worktree derives its own port. Singleton resources (one
 local model server, one GPU) still serialize, as does any port a stack fixes by
-hand. See
-[Claude Code and git worktrees](../../wiki/claude/worktrees.md) for merge order and the
-port-collision detail.
+hand. See [Parallel features](parallel-features.md) for merge order and
+[Claude Code and git worktrees](../../wiki/claude/worktrees.md) for port collisions.
 
 ## Related
 
-- [Claude Code and git worktrees](../../wiki/claude/worktrees.md) for the isolation and fan-out mechanics
+- [Claude Code and git worktrees](../../wiki/claude/worktrees.md) for the worktree mechanism and its gotchas
 - [Claude Code subagents](../../wiki/claude/subagents.md) for in-session parallelism without worktrees, and [blocking subagents](../../wiki/claude/permissions.md#blocking-subagents) for the `permissions.deny` rule that stops every spawn
 - `canon/context/claude-plugin/skill-strategy/overview.md` for how the skills in the loop are categorized

package/docs/workflow/parallel-features.md

@@ -24,7 +24,7 @@ Execution order comes off `.canon/tasks/priority.md` and nothing sequences work
 
 Run one orchestrator at a time. The board is gitignored, so a second session reads none of the first one's writes and the two collide on labels and archives.
 
-See [operating model](operating-model.md) for what caps the worker tracks under it and when a disjoint one still waits. An operator caps a session's workers by saying so, and that cap binds for the session rather than standing as a number in a file.
+See [operating model](operating-model.md) for what caps the worker tracks under it and what conflict holds one behind another. An operator caps a session's workers by saying so, and that cap binds for the session rather than standing as a number in a file.
 
 Before a handoff, the orchestrator checks the plan against the tree rather than reading it: grep each construct it names and count the sites, confirm every phase label it cites is still open, and open each file it describes. A plan goes stale from whatever merged after it was written, and reading cannot catch that.
 
@@ -32,7 +32,7 @@ A constraint naming a track in flight carries the same problem past the handoff,
 
 ## Records at the main root
 
-`.canon/plans/`, `.canon/review/`, and `.canon/memory/` all resolve at the main worktree root, so artifacts created in any session are visible from any sibling worktree. A session inside a worktree reads them directly, since the file-editing tools refuse a main-root path but `Read` resolves normally. It writes a whole file through the shell and makes a change inside an existing file through a `canon` verb, which resolves the main root in-process. See [Claude Code and git worktrees](../../wiki/claude/worktrees.md) for the full rule and the domain-level fan-out guidance.
+`.canon/plans/`, `.canon/review/`, and `.canon/memory/` all resolve at the main worktree root, so artifacts created in any session are visible from any sibling worktree. A session inside a worktree reads them directly, since the file-editing tools refuse a main-root path but `Read` resolves normally. It writes a whole file through the shell and makes a change inside an existing file through a `canon` verb, which resolves the main root in-process. See [Claude Code and git worktrees](../../wiki/claude/worktrees.md) for why the tool refuses the write, and the fan-out section below for the domain-level guidance.
 
 The plan's shape is fixed by `standards/plan.md`: the section list, the filename, and the contract its questions keep. Its lifecycle, from the session that writes it to the archive, is `standards/plan-lifecycle.md`. Every question carries a `- Suggested:` line and an empty `- Answer:` slot, and a blank answer accepts the suggestion at execution time. That default is what makes a plan decision-ready in one pass, and it is the opposite of the contract an intake folder keeps, where an empty slot means nobody reached the item.
 
@@ -56,6 +56,27 @@ A branch review report takes the other route and is swept rather than archived.
 
 `canon:context-fold` decides which task closed by reading the diff rather than the conversation. It resolves a merge base against `origin/main`, unions the committed diff with the working tree and untracked files, then matches unchecked outcomes on the board against what shipped. A task that shipped without ever being discussed still gets marked. Architecture and design stay session-sourced, because a diff cannot carry a judgment, and an architecture write further needs a folded plan naming the slot decision. The requirements record is never folded. A direction change gets one report line naming `canon:document-health`, which reviews that record only when asked.
 
+## Shipping a fan-out
+
+A fan-out of N worktrees produces N pull requests. The order they merge in matters only when two branches touch the same file.
+
+**Rebase profile.** Work confined to one domain directory, such as a new skill under its own folder or independent fixes in different subtrees of `scripts/`, rarely touches a sibling's files. A shared file does not hold a branch back, per the conflict test in [operating model](operating-model.md). These paths are shared hotspots, the ones a second branch should expect to rebase over and resolve:
+
+- `CLAUDE.md`, since cross-domain behavior lives there
+- `tooling/**`, since stack manifests, golden configs, and seeds are tightly coupled
+- `canon/context/context-model/overview.md` and `docs/agents/`, which several domains cross-reference
+- Any folder's `index.md`, since `canon indexes regen` rewrites it and two worktrees adding files to a regen-covered folder race on it. Resolve its conflict by running the regen over the rebased tree rather than by hand.
+
+Land any in-flight edit to a hotspot on `main` before fanning out where you can. A worktree on a stale `CLAUDE.md` costs more to rebase than it saved.
+
+**Merge order.** Merge the branch with the smallest hotspot footprint first. A branch touching `CLAUDE.md`, a context entry, or a regenerated `index.md` merges last, and its siblings rebase on the new `main` once it lands.
+
+**Rebase before the next merge.** After one squash-merge, each sibling is behind `main` and may carry a stale copy of a shared file. The branch merging second resolves, in the session that built it and after the first lands, never against a sibling still building: run `/review-address` there, which trial-merges against `origin/main` and rebases a branch that no longer merges or whose files `main` changed. Push, then merge. Never force-merge a stale branch.
+
+**Clean up after merge.** Run `/git-worktree cleanup` to remove worktrees whose branches merged on GitHub and prune the local branches. The skill reads merge state through `gh pr view`. To start a fresh feature from a stale worktree, `ExitWorktree(action: "keep")` back to main, then `/session-worktree <new-name>`.
+
+**When fan-out was the wrong call.** Sharing a file was never the reason. If every rebase needs a decision the tree does not carry, because one branch depended on another, changed a contract the other consumed, moved a path the other wrote, or swept a folder the other wrote inside, the branches should have serialized. Land one, wait, then start the next. The cleanup skill only tidies a flow that already worked.
+
 ## The task board
 
 `.canon/tasks/` is gitignored and resolves at the main worktree root, so every session shares one board. One file per task is what keeps concurrent sessions from overwriting each other, since a gitignored board has no history to recover a lost write from. Its `index.md` is generated by a hook rather than by `bun run check`, because the whole-repo index walk skips gitignored folders.
@@ -64,7 +85,7 @@ A branch review report takes the other route and is swept rather than archived.
 
 `canon tasks validate` reads a row against its own table before it reads anything the row claims. A blank or prose line closes the table above it, so a row stranded there is checked against the line behind it rather than parsed as a continuation, and a row that clears that test still has its cell count checked against its header. A `## Needs a plan` row that states its own position, searched for `<ordinal> here` or the bare word `last` anywhere in the cell rather than at its start, is checked against where it actually sits, which is what catches a gap, a duplicate, and a sequence starting somewhere other than first alike.
 
-Past that shape, it checks what a surviving row claims against what the tree holds: every plan pointer resolves, every task file is named by a board row or a backlog line and never by both, no task sits in two groups, and no two rows marked ready touch the same file. One check across both surfaces is what lets a task move between the board and the backlog without the move reading as a dropped file. The collision check is the half a reader cannot run by eye, and it is what keeps two workers from being handed colliding work. Blockers re-takes what a parked row waits on, reporting one whose cited task reached the trunk and one whose cited file nothing running still holds. A cited task settles the row by being archived, or by closing every outcome and naming a pull request the trunk carries, since the checkbox alone is marked while the branch is still in review. Both halves read a citation out of the blocker cell, so a row citing neither is reported as untested rather than counted clean, and so is a cited task the trunk could not answer for. It reports and never writes, because a row is the orchestrator's claim and a validator repairing one would assert the claim it exists to test. Nothing fires it automatically, since the board is gitignored per-machine scratch with no shared moment to hang a hook on, so the orchestrator's sweep calls it at the point the readiness claim is made and follows it with the parked re-test.
+Past that shape, it checks what a surviving row claims against what the tree holds: every plan pointer resolves, every task file is named by a board row or a backlog line and never by both, no task sits in two groups, and every row marked ready names its files. One check across both surfaces is what lets a task move between the board and the backlog without the move reading as a dropped file. Paths two ready rows share go to a `shared` array moving no exit code, the candidate list the orchestrator's conflict check reads. Blockers re-takes what a parked row waits on, reporting one whose cited task reached the trunk and one whose cited file nothing running still holds. A cited task settles the row by being archived, or by closing every outcome and naming a pull request the trunk carries, since the checkbox alone is marked while the branch is still in review. Both halves read a citation out of the blocker cell, so a row citing neither is reported as untested rather than counted clean, and so is a cited task the trunk could not answer for. It reports and never writes, because a row is the orchestrator's claim and a validator repairing one would assert the claim it exists to test. Nothing fires it automatically, since the board is gitignored per-machine scratch with no shared moment to hang a hook on, so the orchestrator's sweep calls it at the point the readiness claim is made and follows it with the parked re-test.
 
 `canon:task-board` owns the two operations that bracket a task's life. It creates the file, holding the filename convention and the frontmatter contract so a malformed write cannot break the index for every sibling, and it moves a shipped task to `.canon/tasks/archive/`. Creation is where the origin invariant is enforced: every task names a plan, a groundwork folder, an intake folder, or an issue, since a task with no origin is either lost context or work nobody decided to do.
 

package/docs/workflow/skill-map.md

@@ -8,7 +8,9 @@ category: Workflow
 
 Groups run in the order a project meets them. They reconcile the scenarios in [AI workflow](ai-workflow.md) with the lifecycle [target projects](../target/projects.md) describes, so every moment either one names has a group. Each row says when to reach for a skill, and its description says what it does.
 
-This page and [skill map on request](skill-map-on-request.md) are the corpus the coverage claim is measured against: every name `canon claude skills list --names` reports takes exactly one row across the two. A skill serving two moments sits at the earlier one, this page counting as earlier than the sibling, and a mention on any other page is prose rather than routing. The sibling holds the groups that answer a request rather than mark a moment. The landing page's skills field renders from both pages, so its build refuses a skill with no row and a row naming no skill.
+This page and [skill map on request](skill-map-on-request.md) are the corpus the coverage claim is measured against: every name `canon claude skills list --names` reports takes exactly one row across the two. A skill serving two moments sits at the earlier one, this page counting as earlier than the sibling, and a mention on any other page is prose rather than routing. The sibling holds the groups that answer a request rather than mark a moment.
+
+Each row sits under the group its skill's `metadata.family` names. The landing page's skills field groups by that field and reads each row's text from both pages, so its build refuses a skill with no row, a row naming no skill, a row filed under another group, and a heading on either page naming no family group, even one with no rows under it. A new group takes its vocabulary entry in `src/claude/skills-families.ts` before its heading lands here.
 
 ## Set up a project
 

package/docs/workflow/zshrc-aliases.md

@@ -68,7 +68,7 @@ Use `clp` in any other repository where you want the toolkit skills available. W
 
 Use `cls` or `clps` to save Opus usage on routine sessions. Switch mid-session with `/model` to avoid restarting.
 
-Use `clw <name>` for features that will take more than one session. A worktree isolates the branch, the transcripts, and the `/resume` history. See [Claude Code and git worktrees](../../wiki/claude/worktrees.md) for fan-out rules.
+Use `clw <name>` for features that will take more than one session. A worktree isolates the branch, the transcripts, and the `/resume` history. See [Claude Code and git worktrees](../../wiki/claude/worktrees.md) for the worktree mechanism, and [Parallel features](parallel-features.md) for fan-out rules.
 
 Use `clc` to resume the last session without a picker. Use `clr` when you have several sessions and need to pick by name or recency. Reach for `clpc` over `clc` wherever the resumed session needs the plugin, inside the toolkit repository as well as outside it, since neither resume re-runs discovery.
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@erclx/canon",
   "type": "module",
-  "version": "5.26.0",
+  "version": "5.28.0",
   "description": "Runs your agent's work and keeps its code good, on one setup for every repo.",
   "license": "MIT",
   "bin": {

package/scripts/core/regen-hero.ts

@@ -20,7 +20,7 @@
  *
  * Only the HTML regenerates here. The PNG beside it is a chromium render whose
  * bytes move with the browser version. Rebuild the images with
- * `canon capture assets/captures --selector .window --out assets/evidence`
+ * `canon capture assets/captures --selector .window --out assets/frames`
  * after this script reports a change. That capture writes a .stamp beside each
  * PNG, which records the digest of the markup it rendered and is what the Hero
  * stage compares, so a frame's three files commit together. The frame carries

package/scripts/lib/sandbox-path.sh

@@ -1,6 +1,6 @@
 #!/usr/bin/env bash
 
-# The sandbox tree lives outside the toolkit worktree. `sandbox/run.sh`
+# The sandbox tree lives outside the toolkit worktree. `canon sandbox run`
 # sets cwd to it for `claude -p`, and every `CLAUDE.md` between that cwd and the
 # filesystem root loads into the session. Under the repository the toolkit's own
 # instructions join that chain beside the seeded copy the scenario installed,
@@ -12,12 +12,11 @@
 #
 # Mints a short random per-run identifier the first time it is asked for, then
 # holds it in CANON_SANDBOX_RUN_ID for the rest of this process. A direct call
-# (not `$(...)`) exports it into the caller's own shell, which is what lets
-# `run.sh` mint once and have the provisioning and the check it shells out to
-# both inherit the same id as ordinary children. A call already carrying the
-# variable, inherited from such a parent, reuses it rather than minting a new one.
+# (not `$(...)`) exports it into the caller's own shell. A call already carrying
+# the variable, inherited from a parent such as `canon sandbox run`, reuses it
+# rather than minting a new one, which is what keeps a hook on the parent's tree.
 #
-# Twin of `mintSandboxRunId` in `src/commands/sandbox.ts`.
+# Twin of `mintSandboxRunId` in `src/sandbox/tree.ts`.
 mint_sandbox_run_id() {
   if [ -z "${CANON_SANDBOX_RUN_ID:-}" ]; then
     CANON_SANDBOX_RUN_ID="$(date +%s)-$$-$RANDOM"
@@ -33,7 +32,7 @@ sandbox_dir_prefix() {
   printf '%s/canon/sandbox\n' "${XDG_STATE_HOME:-$HOME/.local/state}"
 }
 
-# Twin of `sandboxTree` in `src/commands/sandbox.ts`. The exec boundary rules out
+# Twin of `sandboxTree` in `src/sandbox/tree.ts`. The exec boundary rules out
 # a shared constant, so a change to the default lands on both sides.
 #
 # A bare fall-through with no per-run component is one path per machine, so
@@ -49,158 +48,3 @@ resolve_sandbox_dir() {
   mint_sandbox_run_id
   printf '%s-%s\n' "$(sandbox_dir_prefix)" "$CANON_SANDBOX_RUN_ID"
 }
-
-# Collapses repeated separators, folds `.` and `..` segments, and strips every
-# trailing separator, leaving a bare root as `/`. Every comparison below is a
-# string test, so `//`, `$HOME//`, and `$HOME/../../usr` each read as a path no
-# rule names until this runs, and an unresolved `..` defeats the allowlist and
-# both directions of the repository test at once.
-#
-# The fold is lexical because the guard runs before provisioning creates the
-# tree, which rules out `cd` with `pwd -P` and any resolution needing the path
-# to exist. Nothing here follows a symlink, so a `..` below one resolves against
-# the link's own path rather than its target. A `..` climbing past the root
-# clamps to `/`, matching the kernel, which leaves the allowlist to refuse it
-# under the rule that already covers every root path.
-normalize_sandbox_path() {
-  local path="$1"
-
-  [ -n "$path" ] || return 0
-
-  while [ "$path" != "${path//\/\//\/}" ]; do
-    path="${path//\/\//\/}"
-  done
-
-  local root=""
-  if [ "${path#/}" != "$path" ]; then
-    root="/"
-    path="${path#/}"
-  fi
-
-  # `resolved` carries each kept segment behind its own separator, so a pop is
-  # one suffix removal and popping an empty stack is the no-op that clamps at
-  # the root. `climbed` holds the leading `..` a relative path has no segment to
-  # pop against, which dropping would change the directory it names.
-  local resolved="" climbed="" segment
-  local remaining=4096
-
-  while [ -n "$path" ] && [ "$remaining" -gt 0 ]; do
-    remaining=$((remaining - 1))
-
-    segment="${path%%/*}"
-    if [ "$segment" = "$path" ]; then
-      path=""
-    else
-      path="${path#*/}"
-    fi
-
-    case "$segment" in
-    "" | .) ;;
-    ..)
-      if [ -n "$resolved" ]; then
-        resolved="${resolved%/*}"
-      elif [ -z "$root" ]; then
-        climbed="$climbed../"
-      fi
-      ;;
-    *) resolved="$resolved/$segment" ;;
-    esac
-  done
-
-  if [ -n "$root" ]; then
-    path="${resolved:-/}"
-  else
-    path="${climbed}${resolved#/}"
-    path="${path:-.}"
-  fi
-
-  while [ "${#path}" -gt 1 ] && [ "${path%/}" != "$path" ]; do
-    path="${path%/}"
-  done
-
-  printf '%s' "$path"
-}
-
-# Whether `candidate` is `target` or a directory containing it. Removing the
-# former removes the latter, which is what makes an ancestor as dangerous as an
-# exact match.
-is_at_or_above() {
-  local candidate="$1"
-  local target="$2"
-
-  [ "$candidate" = "$target" ] || [ "${target#"$candidate"/}" != "$target" ]
-}
-
-# Prints the reason a location is unusable and returns non-zero, so the caller
-# reports one message naming the path rather than a bare refusal.
-#
-# Provisioning runs `rm -rf` on this path at three sites before staging, so the
-# test is an allowlist rather than a list of paths to refuse. A blocklist has to
-# name every system directory to be right once and stays wrong as soon as one is
-# missed, while requiring a strict descendant of the home directory or of the
-# temp root admits the default and every reasonable override and refuses `/`,
-# `/usr`, `/etc`, and `$HOME` itself without naming any of them.
-#
-# The repository test is separate and runs both ways. A path under the worktree
-# restores the ancestor chain the relocation removed, and a path above it is one
-# `rm -rf` away from deleting the repository. It resolves the main worktree root
-# rather than trusting `$PROJECT_ROOT`, since a linked worktree is itself inside
-# that root.
-assert_sandbox_dir_safe() {
-  local raw="$1"
-  local root="${2:-${PROJECT_ROOT:-$PWD}}"
-
-  if [ -z "$raw" ] || [ "${raw#/}" = "$raw" ]; then
-    printf 'CANON_SANDBOX_DIR must be an absolute path, got: %s\n' "${raw:-<empty>}"
-    return 1
-  fi
-
-  # `normalize_sandbox_path` stops at 4096 segments and drops the remainder,
-  # which would hand the tests below an ancestor of the path provisioning
-  # removes. Refusing past `PATH_MAX` keeps that bound out of reach, since a
-  # segment costs at least two bytes and no syscall accepts the string anyway.
-  if [ "${#raw}" -gt 4096 ]; then
-    printf 'Refusing the sandbox path. It is %s characters, past the longest path any filesystem here accepts.\n' "${#raw}"
-    return 1
-  fi
-
-  local dir home temp
-  dir="$(normalize_sandbox_path "$raw")"
-  home="$(normalize_sandbox_path "${HOME:-/root}")"
-  temp="$(normalize_sandbox_path "${TMPDIR:-/tmp}")"
-
-  # Every message below names `$raw`, which is what the operator set. The tests
-  # compare `$dir`, so a path carrying `..` is refused for a location its own
-  # spelling does not show.
-  local resolution=""
-  [ "$dir" = "$raw" ] || resolution=" It resolves to $dir."
-
-  if ! is_at_or_above "$home" "$dir" && ! is_at_or_above "$temp" "$dir"; then
-    printf 'Refusing %s as the sandbox. Provisioning removes the tree first, so the path has to sit under %s or %s.%s\n' "$raw" "$home" "$temp" "$resolution"
-    return 1
-  fi
-
-  if [ "$dir" = "$home" ] || [ "$dir" = "$temp" ]; then
-    printf 'Refusing %s as the sandbox. Provisioning removes the tree first, so the path has to sit under %s rather than be it.\n' "$raw" "$dir"
-    return 1
-  fi
-
-  local main_root
-  main_root="$(git -C "$root" worktree list --porcelain 2>/dev/null |
-    grep -m 1 '^worktree ' | cut -d' ' -f2-)"
-  main_root="$(normalize_sandbox_path "${main_root:-$root}")"
-
-  if is_at_or_above "$dir" "$main_root"; then
-    printf 'Refusing %s as the sandbox. Provisioning removes the tree first, and that path contains %s.%s\n' "$raw" "$main_root" "$resolution"
-    return 1
-  fi
-
-  case "$dir" in
-  "$main_root"/*)
-    printf 'Sandbox at %s sits inside %s, which puts the toolkit CLAUDE.md back on the session ancestor chain.%s Point CANON_SANDBOX_DIR outside the repository.\n' "$raw" "$main_root" "$resolution"
-    return 1
-    ;;
-  esac
-
-  return 0
-}

package/src/audits/baseline.ts

@@ -1,7 +1,7 @@
 import { mkdir, readFile, writeFile } from 'node:fs/promises'
 import { dirname, join, relative } from 'node:path'
 import type { AuditResult } from '@/audits/catalog'
-import { resolveExisting } from '@/legacy-path'
+import { resolveExisting } from '@/roots/legacy'
 
 /**
  * Where the retained counts live, relative to the project root.

package/src/audits/run.ts

@@ -7,8 +7,8 @@ import {
   classify,
   type Corpus,
 } from '@/audits/catalog'
-import { gitEnv } from '@/git-env'
-import { PROJECT_ROOT } from '@/project-root'
+import { gitEnv } from '@/git/env'
+import { PROJECT_ROOT } from '@/roots/project'
 
 /** Every value a corpus filter accepts, matching the `Corpus` union. */
 export const CORPORA: readonly Corpus[] = ['tracked', 'per-machine', 'upstream']

package/src/canvas/address.ts

@@ -9,6 +9,12 @@
 /** Marks the token stylesheet the server injects, which the file never holds. */
 export const TOKENS_ATTRIBUTE = 'data-canvas-tokens'
 
+/**
+ * Marks a document wrapper the server writes because the file leaves it to the
+ * browser to imply, so the shell counts only what the file states.
+ */
+export const IMPLIED_ATTRIBUTE = 'data-canvas-implied'
+
 /** On that same element, the hash of the file the frame was served from. */
 export const HASH_ATTRIBUTE = 'data-canvas-hash'
 
@@ -22,8 +28,9 @@ export interface ElementAddress {
   readonly tag: string
   /**
    * Every element the shell counted. A browser implies elements the file never
-   * states, such as a `tbody` or the document wrapper, and each one shifts the
-   * count, so a total that differs from the server's is what exposes it.
+   * states, such as a `tbody`, and each one shifts the count, so a total that
+   * differs from the server's is what exposes it. The server marks an implied
+   * document wrapper itself, so only the marked ones leave the count.
    */
   readonly count: number
   /**
@@ -53,7 +60,9 @@ export function excerpt(text: string): string {
 
 export function documentElements(doc: Document): Element[] {
   return [...doc.querySelectorAll('*')].filter(
-    (element) => !element.hasAttribute(TOKENS_ATTRIBUTE),
+    (element) =>
+      !element.hasAttribute(TOKENS_ATTRIBUTE) &&
+      !element.hasAttribute(IMPLIED_ATTRIBUTE),
   )
 }
 

package/src/canvas/capture.ts

@@ -13,7 +13,7 @@ import {
   FRAMES_PREFIX,
   startCanvas,
 } from '@/canvas/server'
-import { recordDir } from '@/record-root'
+import { recordDir } from '@/roots/record'
 
 /**
  * The element a frame is captured by. The document rather than its body, so a