@erclx/canon 5.27.0 → 5.28.0

package/docs/agents/pr-tick.md

@@ -0,0 +1,72 @@
+---
+title: The pull request checklist tick
+description: How canon pr tick marks the checklist boxes a UI pass drove, the stamp that names the commit each passed at, why a render at a newer head clears a tick, the refusal reasons it names, and why a taste box is never ticked
+---
+
+# The pull request checklist tick
+
+`canon pr tick` ticks the boxes of the visual checklist on the pull request's
+evidence comment. `review-ui` calls it once its verdict has posted, for every
+box that passed at the head it drove, so the person merging reads a checklist
+a driver worked through instead of one that stays empty.
+
+```bash
+canon pr tick 1341 --boxes 1,2,4 --head <sha> --json
+```
+
+Box numbers come from the `boxes` field of `canon pr evidence --json`, which
+numbers the checklist's box lines in order. A caller never counts lines itself.
+
+## What a tick looks like
+
+A ticked box ends in the commit it passed at, visible on the comment:
+
+```markdown
+- [x] click "Pricing" in the header → the pricing page opens · passed at `<short-sha>`
+```
+
+The stamp is visible rather than an HTML comment because the person it is for
+reads the merge record, and a hidden head would tell the machine what the
+reader cannot see. The reader matches the stamp only as the trailing segment of
+a line, so a box whose own text says `passed at` is left alone.
+
+## When a tick is cleared
+
+A tick is a claim about one commit, so a render at another commit does not
+carry it forward. `canon pr evidence` settles the checklist before it renders:
+
+- A tick stamped for the render's head stays.
+- A tick stamped for any other head is cleared and loses its stamp.
+- A tick with no stamp, such as one an author or the operator added by hand,
+  stays only when the comment it came from described the render's head.
+
+A render at the same head after `--preview` keeps every tick. A push that
+reaches the branch without a render leaves its ticks in place until the next
+one, and the stamp still shows which head earned them.
+
+## What it refuses
+
+`reason` on the record is what a caller branches on, not the exit code:
+
+| Reason         | What it means                                                                                                |
+| -------------- | ------------------------------------------------------------------------------------------------------------ |
+| `ticked`       | The boxes were ticked, with the remote tip in `head`.                                                        |
+| `stale-head`   | `--head` is not the branch tip on the remote. Nothing is written.                                            |
+| `taste-box`    | A named box ends in `(taste)`. Nothing is written.                                                           |
+| `no-box`       | A named number is past the end of the checklist. Nothing is written.                                         |
+| `no-checklist` | The evidence comment carries no checklist.                                                                   |
+| `no-comment`   | No comment on the pull request carries the evidence marker.                                                  |
+| `bad-boxes`    | `--boxes` is not a list of positive whole numbers, or `--head` is not a hex sha of seven characters or more. |
+
+A taste box is a judgment of look or feel that a driver reports as needing a
+person's eyes. Refusing it in the verb makes that rule a check rather than a
+sentence a driver can talk itself out of, and a refusal writes none of the
+boxes named beside it.
+
+The head is compared against the tip read from the remote rather than the pull
+request object, which lags a push by up to a minute. A push landing between
+that read and the write leaves a tick at an older head until the next render
+clears it, the same window `canon pr head` documents.
+
+The verb edits the marked comment in place with a `PATCH`, the way
+`canon pr local --remove` does, and ticking a box again restamps it.

package/docs/agents/sandbox.md

@@ -9,7 +9,7 @@ description: Scenario routing, the expectation scoring surface, and the coverage
 
 ## Scenarios
 
-Scenarios live under `sandbox/`, one folder per category. `sandbox/fixtures/` is the exception, holding file content that scenarios stage rather than scenarios of its own, so the picker and the coverage report both filter it out. That tree sits outside `files` in `package.json`, so an installed `canon` carries the command, reports it as toolkit-only on one line, and exits 1 rather than failing on the missing directory. Route non-interactively with `SANDBOX_SCENARIO`:
+Scenarios live under `sandbox/`, one folder per category and one file per command, either a TypeScript module or a bash script, and provisioning refuses a command present in both forms. `sandbox/fixtures/` is the exception, holding file content that scenarios stage rather than scenarios of its own, so the picker and the coverage report both filter it out. That tree sits outside `files` in `package.json`, so an installed `canon` carries the command, reports it as toolkit-only on one line, and exits 1 rather than failing on the missing directory. Route non-interactively with `SANDBOX_SCENARIO`:
 
 ```bash
 SANDBOX_SCENARIO=sync canon sandbox infra:tooling
@@ -93,7 +93,7 @@ The baseline is a detached worktree with full history, removed on exit including
 
 The record lists per arm `identical`, `differs` with the manifest keys that differ, `red-on-base` when both sides fail the same way, or `skipped-anchor`. It also carries `canonVersion`, `baseCommit`, `masksApplied`, `errors`, and `counts`. A declared arm adds a `check` entry from `canon sandbox check` on the head tree, whose `asserted` count shows its `expect.toml` resolved from `sandbox/fixtures/`.
 
-Exit 0 means every compared arm is identical or red the same way on both sides. Exit 1 means any `differs`, a base and head exit that disagree, or an armed arm that `canon sandbox coverage` lists and enumeration lacks.
+Exit 0 means every compared arm is identical or red the same way on both sides. Exit 1 means any `differs`, a base and head exit that disagree, an armed arm that `canon sandbox coverage` lists and enumeration lacks, a scenario present as both `.sh` and `.ts`, or a `.ts` scenario that fails to load.
 
 ## Scenario coverage
 

package/docs/agents/tasks-plans.md

@@ -59,7 +59,7 @@ The question block is read through the same parser `canon tasks validate` runs,
 
 Branch on `launchable` rather than on the exit code, for the reason the section above states: a shell profile wrapping `canon` in a function can take a later command's status and mask every non-zero exit, which reads a waiting plan as a launchable one.
 
-The orchestrator dispatch runbook calls this before it checks the branch or the file sets, so a row whose plan still needs a person is handed back rather than launched into a worker that halts on the same question.
+The orchestrator dispatch runbook calls this before it checks the branch or runs its conflict check, so a row whose plan still needs a person is handed back rather than launched into a worker that halts on the same question.
 
 ```bash
 canon tasks plan-answers dispatch-answer-gate --json | jq -r '.launchable'

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

@@ -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

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.
 
@@ -60,22 +60,22 @@ A branch review report takes the other route and is swept rather than archived.
 
 A fan-out of N worktrees produces N pull requests. The order they merge in matters only when two branches touch the same file.
 
-**Collision 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 collides. These paths are shared hotspots, so a branch touching one serializes rather than fans out, because parallel edits almost always produce a conflict or a stale regenerated 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
+- 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. A worktree on a stale `CLAUDE.md` costs more to rebase than it saved.
+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. Run `git fetch origin && git rebase origin/main` in the sibling, resolve any conflict in the worktree, push, then merge. Never force-merge a stale branch.
+**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.** If every sibling needs a rebase and every rebase conflicts on the same file, the branches should have serialized. Land one, wait, then start the next. The cleanup skill only tidies a flow that already worked.
+**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
 
@@ -85,7 +85,7 @@ Land any in-flight edit to a hotspot on `main` before fanning out. A worktree on
 
 `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/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@erclx/canon",
   "type": "module",
-  "version": "5.27.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/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

@@ -8,7 +8,7 @@ import {
   type Corpus,
 } from '@/audits/catalog'
 import { gitEnv } from '@/git/env'
-import { PROJECT_ROOT } from '@/project-root'
+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/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

package/src/canvas/client/inspector/field.tsx

@@ -21,6 +21,8 @@ export interface Scrub {
   readonly begin: () => ScrubSession
   /** Holds a scrubbed number inside what the property accepts. */
   readonly clamp: (value: number) => number
+  /** Scales each pixel's move, for a value whose useful range is small. */
+  readonly step?: number
 }
 
 interface FieldProps {
@@ -120,8 +122,11 @@ export function Field({
           const moved = event.clientX - held.lastX
           held.lastX = event.clientX
           held.value = scrub.clamp(
-            Math.round((held.value + moved * scrubStep(event.shiftKey)) * 10) /
-              10,
+            Math.round(
+              (held.value +
+                moved * scrubStep(event.shiftKey) * (scrub.step ?? 1)) *
+                10,
+            ) / 10,
           )
           const shown = String(held.value)
           if (input.current) input.current.value = shown
@@ -177,6 +182,60 @@ export function Field({
   )
 }
 
+interface SelectFieldProps {
+  readonly label: string
+  readonly glyph: string
+  /** Each option's value, which is also what it shows. */
+  readonly options: readonly string[]
+  readonly value: string
+  readonly isBusy: boolean
+  readonly isWide?: boolean
+  readonly onCommit: (value: string) => void
+}
+
+/**
+ * A value picked from a fixed list, drawn like a field with a chevron. The
+ * select is native, so its list opens above the panel's clipping. A current
+ * value outside the list stays as an option, so it shows rather than blanks.
+ */
+export function SelectField({
+  label,
+  glyph,
+  options,
+  value,
+  isBusy,
+  isWide,
+  onCommit,
+}: SelectFieldProps): JSX.Element {
+  const shown = options.includes(value) ? options : [...options, value]
+  return (
+    <div class={fieldClass(isWide, 'is-select')}>
+      <span class="glyph" aria-hidden="true" title={label}>
+        {glyph}
+      </span>
+      <select
+        class="glyph-field-input glyph-select"
+        aria-label={label}
+        value={value}
+        disabled={isBusy}
+        onChange={(event) => {
+          const picked = event.currentTarget.value
+          if (picked !== value) onCommit(picked)
+        }}
+      >
+        {shown.map((option) => (
+          <option key={option} value={option}>
+            {option}
+          </option>
+        ))}
+      </select>
+      <svg class="select-chevron" viewBox="0 0 16 16" aria-hidden="true">
+        <path d="M4.5 6.5 8 10l3.5-3.5" />
+      </svg>
+    </div>
+  )
+}
+
 interface ReadOnlyFieldProps {
   readonly label: string
   readonly glyph: string

package/src/canvas/client/inspector/fields.css

@@ -679,3 +679,81 @@
   height: 14px;
   fill: currentColor;
 }
+
+/*
+ * A value picked from a fixed list. The native select draws its value as the
+ * field's text and the chevron sits over its right edge, so the platform list
+ * opens on press and the field keeps the height of every other one.
+ */
+.glyph-field.is-select {
+  position: relative;
+}
+
+.glyph-select {
+  appearance: none;
+  padding-right: 22px;
+  cursor: pointer;
+}
+
+.select-chevron {
+  position: absolute;
+  right: 6px;
+  width: 12px;
+  height: 12px;
+  fill: none;
+  stroke: var(--color-muted);
+  stroke-width: 1.5;
+  pointer-events: none;
+}
+
+/* A raw marker inside a field sits before its menu, clear of the value. */
+.glyph-field .raw {
+  padding: 0 2px 0 var(--space-xs);
+}
+
+/* Mutually exclusive choices for one value, drawn as one field split evenly. */
+.segmented {
+  display: grid;
+  grid-template-columns: repeat(4, minmax(0, 1fr));
+  gap: 2px;
+  min-height: 24px;
+  padding: 1px;
+  border: 1px solid var(--color-border);
+  border-radius: var(--radius-action);
+  background: var(--color-surface);
+}
+
+.segment {
+  display: grid;
+  place-items: center;
+  min-height: 22px;
+  padding: 0;
+  border: 0;
+  border-radius: var(--radius-action);
+  background: transparent;
+  color: var(--color-muted);
+  cursor: pointer;
+}
+
+.segment:hover {
+  color: var(--color-text);
+}
+
+.segment[aria-pressed='true'] {
+  background: var(--color-chrome);
+  color: var(--color-text);
+}
+
+.segment:disabled {
+  opacity: 0.5;
+  cursor: not-allowed;
+}
+
+.segment svg {
+  width: 14px;
+  height: 14px;
+  fill: none;
+  stroke: currentColor;
+  stroke-width: 1.5;
+  stroke-linecap: round;
+}