@erclx/canon 5.38.0 → 5.39.0

package/README.md

@@ -164,7 +164,7 @@ Each domain carries an entry written for someone maintaining the toolkit rather
 - [Claude Code plugin](canon/context/claude-plugin/index.md)
 - [Governance rules](canon/context/governance/index.md)
 - [Tooling stacks](canon/context/tooling/index.md)
-- [Design system](canon/context/design/index.md)
+- [Design system](canon/context/design.md)
 - [Slides](canon/context/features/slides.md)
 - [Transcripts](canon/context/features/transcripts.md)
 - [Sandbox](canon/context/sandbox/index.md)

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

@@ -1,7 +1,7 @@
 {
   "name": "canon",
   "description": "Runs your agent's work and keeps its code good, on one setup for every repo.",
-  "version": "5.38.0",
+  "version": "5.39.0",
   "author": {
     "name": "Eric Le",
     "url": "https://github.com/erclx"

package/claude/skills/api-design/SKILL.md

@@ -7,18 +7,16 @@ metadata:
 
 # API design
 
-A session changing a surface sees the one caller it is working for and none of the others, so it renames a field in place, returns whatever record it had in hand, and ships. Every caller it did not open breaks on the next release. This skill carries the judgment at the moment the surface is drawn: what a caller can observe, what the contract says before the body exists, and how a change lands without breaking anyone.
+A session changing a surface sees the one caller it is working for, so it renames a field in place, returns whatever record it had in hand, and ships. Every caller it did not open breaks on the next release. This skill carries the judgment at the moment the surface is drawn.
 
-Load it before changing anything a caller outside the module reads, whether code, a script parsing output, or a stored file. A surface is cheap to shape before its first caller and expensive after.
-
-Skip it when the change stays behind an existing boundary and alters nothing a caller can observe.
+Load it before changing anything a caller outside the module reads, whether code, a script parsing output, or a stored file, since a surface is cheap to shape before its first caller and expensive after. Skip it when the change alters nothing a caller can observe.
 
 ## Decide what a caller can observe
 
 Every observable behavior becomes a dependency once there are enough callers, whatever the contract promises, which is Hyrum's Law. Decide what is observable, and expose nothing by accident.
 
 - Return a shape built for the caller over the internal record you had in hand. A storage type, an internal identifier, or a field kept for bookkeeping becomes a contract the moment it ships.
-- Treat ordering, timing, default values, and the exact text of an error or a log line as observable. Sort output on purpose or say it is unordered, rather than leaving it in whatever order the data arrived.
+- Treat ordering, timing, default values, and the exact text of an error or a log line as observable. Sort output on purpose or say it is unordered, never in whatever order the data arrived.
 - Keep the surface as small as the first caller needs. A field or flag added later is free, and one removed later breaks someone.
 - Keep one name for one concept across every surface the project exposes. A caller learning `id` in one output and `key` in the next has to guess which is which.
 
@@ -31,7 +29,8 @@ Every observable behavior becomes a dependency once there are enough callers, wh
 
 ## Keep one error shape per surface
 
-- Give every failure on one surface the same shape, carrying a stable code a caller can branch on and a message for the person reading it. Branching on message text breaks the first time the message is reworded. Keep internal implementation details out of the message, since a caller reads it and cannot act on a stack frame.
+- Give every failure on one surface the same shape, a stable code a caller can branch on and a message for the person, since branching on message text breaks at the first rewording
+- Keep internal implementation details out of the message, since a caller reads it and cannot act on a stack frame
 - Reuse the error type the project already throws or returns where one exists, rather than inventing a second error convention beside it.
 
 ## Validate at the boundary
@@ -44,10 +43,10 @@ Every observable behavior becomes a dependency once there are enough callers, wh
 ## Change additively
 
 - Add a field, a flag, or a parameter as optional, with a default that keeps the old behavior.
-- Never rename or remove anything in place. Add the new name beside the old one, keep both working, and remove the old one only once no caller reads it, proving that and moving the callers through `deprecation-migration`.
+- Never rename or remove anything in place. Add the new name beside the old, keep both working, and remove the old only once no caller reads it, proven through `deprecation-migration`.
 - Never change what an existing field means or what type it carries. A new meaning takes a new name.
-- When a caller cannot pin a version, such as a module everything in one repository imports, keep one version of the surface live and migrate every caller in the change that alters it, the One-Version Rule. Two versions live side by side split the callers between them.
-- Record each deprecation where a caller looks, naming the replacement and what happens next, rather than in a commit message nobody reads again. Whether to deprecate, and when a deprecation turns compulsory, is `deprecation-migration`.
+- When a caller cannot pin a version, such as a module one repository imports, keep one version live and migrate every caller in the change, the One-Version Rule. Two live versions split the callers.
+- Record each deprecation where a caller looks, naming the replacement and what happens next, never only in a commit message. Whether and when to deprecate is `deprecation-migration`.
 
 ## Make a retried write safe
 
@@ -82,6 +81,8 @@ Read `${CLAUDE_SKILL_DIR}/references/adopted.md` only when extending this guidan
 
 ### Changes, retries, and order
 
+Changes to an existing surface carry their own signs.
+
 - An existing field is changing type or meaning under the same name.
 - A write that a client could retry carries no key, or checks for one with a read before the insert.
 - Output order follows whatever the underlying data returned, and nothing states whether it is sorted.
@@ -97,6 +98,8 @@ Check each line against the surface the change produced. A line answering no is
 
 ### Input, writes, and contract
 
+Check the input and the contract the same way.
+
 - Input is checked once, at the boundary, and nowhere deeper.
 - Every write a caller could retry takes a key, claims it atomically, and refuses a reused key with a different body.
 - The contract states what the surface returns and what it refuses.

package/claude/skills/auto-ship/SKILL.md

@@ -12,45 +12,62 @@ Chain the post-plan pipeline in a single run. Every step but the UI checklist ha
 ## Guards
 
 - All `.canon/plans/` reads resolve at the main worktree root, not the current worktree. Resolve that root the way `session-worktree` does.
-- Derive `<slug>` per `${CLAUDE_SKILL_DIR}/../git-branch/references/slug.md`. This skill takes the stop rather than the `latest` fallback, since it commits and opens a pull request. If empty, stop: `❌ Detached HEAD. Checkout the feature branch first.` This slug is provisional. It is superseded once `session-worktree` runs, whether at Step 0 or before this chain began. Every later step keys its output on the slug that run resolves, being the worktree and the branch, regardless of which plan Step 1 reads.
+- Derive `<slug>` per `${CLAUDE_SKILL_DIR}/../git-branch/references/slug.md`, taking the stop over the `latest` fallback, since this skill opens a pull request
+- If the slug is empty, stop: `❌ Detached HEAD. Checkout the feature branch first.`
 - Resolve `<plan>` in Step 1, ahead of any other read.
 - If the working tree has uncommitted changes unrelated to the plan, stop: `❌ Uncommitted changes outside the plan. Commit or stash before autoshipping.`
 
+Treat that slug as provisional. Once `session-worktree` runs, at Step 0 or before this chain began, every later step keys on the worktree and branch it resolved, whichever plan Step 1 reads.
+
 ## Step 0: take the role, then enter a worktree
 
 Invoke `canon:role-worker` first, whatever the worktree state. That skill states the boundaries, the lifetime, and the channel obligations of a session building one branch under one plan, and a dispatched worker reaches the role here and nowhere else. Report it rather than proceeding silently when `canon:role-worker` does not resolve.
 
-If `git rev-parse --git-dir` equals `git rev-parse --git-common-dir`, the session is in the main worktree. Invoke `canon:session-worktree` before continuing, carrying the argument the subsection below derives. The wrapper handles branch alignment. Do not call `EnterWorktree` directly.
-
-If neither command resolves, stop: `❌ Not a git repository. Autoship needs git or a WorktreeCreate hook.`
+Then compare `git rev-parse --git-dir` with `git rev-parse --git-common-dir`. The `session-worktree` wrapper handles branch alignment, so never call `EnterWorktree` directly.
 
-If the two commands differ, the session is already in a linked worktree. Continue.
+| Reading          | Route                                                                                          |
+| ---------------- | ---------------------------------------------------------------------------------------------- |
+| Equal            | The main worktree, so invoke `canon:session-worktree` with the argument the subsection derives |
+| Different        | Already in a linked worktree, so continue                                                      |
+| Neither resolves | Stop: `❌ Not a git repository. Autoship needs git or a WorktreeCreate hook.`                  |
 
 ### Name the worktree from the plan rather than leaving it to be derived
 
-When the invocation argument is a plan path or a bare slug, name the worktree from `canon tasks plan-branch <argument> --json` rather than from a reading of the plan. Read `${CLAUDE_SKILL_DIR}/references/worktree-name.md` before invoking `canon:session-worktree` for how each record shape reaches its tier 0 argument. A task path or no argument at all invokes it bare.
+When the invocation argument is a plan path or a bare slug, name the worktree from `canon tasks plan-branch <argument> --json` rather than from a reading of the plan. A task path or no argument at all invokes `canon:session-worktree` bare.
+
+Read `${CLAUDE_SKILL_DIR}/references/worktree-name.md` before invoking `canon:session-worktree`, for how each record shape reaches its tier 0 argument.
 
 ## Step 1: read the plan
 
-Resolve `<plan>` in this order, stopping at the first match:
+Resolve `<plan>` in this order, stopping at the first match. Only a path reaches tier 1, and a bare slug is read as a plan's throughout, since the two would collide on any similar name.
+
+1. **Caller-supplied task.** A path under `.canon/tasks/`. Take what its first `Plan:` line names, per `${CLAUDE_SKILL_DIR}/../task-board/references/tasks.md`, after reading `tier-failures.md`.
+2. **Caller-supplied plan.** Anything else, a plan path or a bare slug, as `session-worktree` tier 0 takes it. A slug resolves to `.canon/plans/feature-<slug>.md`, and a path is taken from the main root.
+3. **Derived.** `.canon/plans/feature-<slug>.md`, from the `<slug>` the Guards derived.
 
-1. **Caller-supplied task.** The invocation carried a path under `.canon/tasks/`. If it does not resolve to a file, stop: `❌ No task at <path>. Path was supplied, not derived, so check it and re-run.` Read that task's first `Plan:` line and take what it names as `<plan>`, per `${CLAUDE_SKILL_DIR}/../task-board/references/tasks.md`, reading `${CLAUDE_SKILL_DIR}/references/tier-failures.md` first for how the pointer resolves and the four stops it can take.
-2. **Caller-supplied plan.** The invocation carried something else. Accept it as a plan path or a bare slug, in the same position `session-worktree` tier 0 accepts its name. A bare slug resolves to `.canon/plans/feature-<slug>.md`, and a path is taken as given from the main worktree root. If it does not resolve to a file, stop: `❌ No plan at <path>. Path was supplied, not derived, so check it and re-run.`
-3. **Derived.** `.canon/plans/feature-<slug>.md`, from the `<slug>` the Guards derived. If it does not exist, stop: `❌ No approved plan at .canon/plans/feature-<slug>.md, where <slug> was derived from the current branch, <branch>. The invocation carried no argument, so pass a plan or a task path, or run /plan-feature first.`
+Each tier stops with its own message on a file that does not resolve.
 
-Only a path reaches tier 1, and a bare slug is read as a plan's throughout, since the two would collide on any similar name.
+| Tier    | Stop                                                                                                                                                                                                                |
+| ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Task    | `❌ No task at <path>. Path was supplied, not derived, so check it and re-run.`                                                                                                                                     |
+| Plan    | `❌ No plan at <path>. Path was supplied, not derived, so check it and re-run.`                                                                                                                                     |
+| Derived | `❌ No approved plan at .canon/plans/feature-<slug>.md, where <slug> was derived from the current branch, <branch>. The invocation carried no argument, so pass a plan or a task path, or run /plan-feature first.` |
 
 ### When a tier fails
 
 Tier 1 stops on a `Plan:` line linking several plans, on a task carrying none, and on a pointer into a plans archive or to no file. `${CLAUDE_SKILL_DIR}/references/tier-failures.md` carries the stop each one takes and the order the archive and existence tests run in.
 
-Test the shape of whatever `<plan>` resolved to before reading it as one, after all three tiers, since a file resolving under any tier can still be the wrong document.
+### Test the plan's shape
 
-Check for a `**Files to touch:**` or `## Files to touch` marker per `${CLAUDE_SKILL_DIR}/../plan-feature/references/plan.md`, the one section every plan carries structurally and a task never does, where `## Outcomes` and `## Findings` are the task's own. If neither form is present, stop: `❌ <path> carries no plan sections. A plan lives at .canon/plans/feature-<slug>.md, and a task reaches one through its Plan: line only from .canon/tasks/. Point autoship at either and re-run.`
+Test the shape of whatever `<plan>` resolved to before reading it, after all three tiers, since a file resolving under any tier can be the wrong document. Look for a `**Files to touch:**` or `## Files to touch` marker per `${CLAUDE_SKILL_DIR}/../plan-feature/references/plan.md`, which a plan always carries and a task never does.
 
-Read `<plan>` at the main worktree root. This file is the scope for this run.
+If neither form is present, stop: `❌ <path> carries no plan sections. A plan lives at .canon/plans/feature-<slug>.md, and a task reaches one through its Plan: line only from .canon/tasks/. Point autoship at either and re-run.` Otherwise read `<plan>` at the main worktree root, which is the scope for this run.
 
-Its sections and its answer contract are fixed by `${CLAUDE_SKILL_DIR}/../plan-feature/references/plan.md`. A blank `- Answer:` accepts the `- Suggested:` line above it, so an unanswered question is a decision this run executes rather than a reason to stop. When this run decides against that suggestion, rewrite the `- Suggested:` line as `overridden at execution to <pick>,` plus the measurement, leaving the `- Answer:` slot blank, and put the same deviation in one line under the open task's `## Findings`, per `${CLAUDE_SKILL_DIR}/../plan-feature/references/plan.md`, opening with the bold source-and-date label that `${CLAUDE_SKILL_DIR}/../task-board/references/tasks.md` fixes.
+### Unanswered questions
+
+The plan's sections and answer contract are fixed by `${CLAUDE_SKILL_DIR}/../plan-feature/references/plan.md`. A blank `- Answer:` accepts the `- Suggested:` line above it, so an unanswered question is a decision this run executes rather than a reason to stop.
+
+When this run decides against a suggestion, rewrite its line as `overridden at execution to <pick>,` plus the measurement, leaving `- Answer:` blank. Put the same deviation in one line under the open task's `## Findings`, opening with the bold source-and-date label `${CLAUDE_SKILL_DIR}/../task-board/references/tasks.md` fixes.
 
 ## Step 2: implement
 
@@ -73,7 +90,7 @@ Run `canon gov test-order --json` from the worktree this chain is building in, n
 The verb reads git history rather than the working tree, so it catches a violation that already reached this branch's history in an earlier session or round. It reports and never gates, so branch on the record's `kind` and its `findings` array rather than on the exit, which a shell function wrapping `canon` can flatten to zero.
 
 - `kind: 'measured'`, `findings` empty. Nothing on the branch reached history ahead of its test. Continue to Step 5.
-- `kind: 'measured'`, `findings` non-empty. Report each pair's `subject` and `reason` to the user and continue to Step 5. Do not stop the chain and do not attempt a fix, since rewriting it here rewrites what an earlier run shipped.
+- `kind: 'measured'`, `findings` non-empty. Report each pair's `subject` and `reason` and continue to Step 5 without a fix, since a rewrite here rewrites what an earlier run shipped.
 - `kind: 'unreadable'`. Report the `message` and continue to Step 5, since a shallow clone or a repository with no trunk is no reason to stop shipping.
 
 ### When the verb is absent
@@ -82,17 +99,22 @@ Never read a missing subcommand as clean. Read `${CLAUDE_SKILL_DIR}/references/v
 
 ## Step 5: UI checklist (conditional)
 
-If the diff touches UI files (JSX, TSX, Vue, Svelte, HTML, or CSS under `src/`), invoke `canon:ui-checklist`, then continue to Step 6 whatever it returns, in every run. The Step 6 draft mark holds the merge, so a stop here protects nothing. When it produces a checklist, read `${CLAUDE_SKILL_DIR}/references/ui-checklist.md` for the counts to hold before `git-pr` removes the file.
+If the diff touches UI files (JSX, TSX, Vue, Svelte, HTML, or CSS under `src/`), invoke `canon:ui-checklist`, then continue to Step 6 whatever it returns, in every run. The Step 6 draft mark holds the merge, so a stop here protects nothing.
+
+When it produces a checklist, read `${CLAUDE_SKILL_DIR}/references/ui-checklist.md` for the counts to hold before `git-pr` removes the file.
 
 ## Step 6: ship
 
 Invoke `canon:git-ship`. That body owns the sequence, being the verify gate, both doc syncs, staging, the commit grouping, the branch rename, the pull request, and the CI watch, along with the reason each step sits where it does. Read the order there and never here.
 
-One thing this chain adds. Mark the pull request as a draft as soon as `git-ship`'s pull request step returns, ahead of its CI watch, naming the number that step returned rather than one resolved by branch. Read `${CLAUDE_SKILL_DIR}/references/draft-mark.md` on reaching that point for the one command that proves the target, marks it, and reads the flag back. A `false` read stops the chain, and never re-issue the mark on it.
+### The draft mark
 
-Emit the Output block on the wake after `git-ship`'s background CI watch exits on `passing`, not when the turn ends on its watch line.
+This chain adds one thing. Mark the pull request as a draft as soon as `git-ship`'s pull request step returns, ahead of its CI watch, naming the number that step returned rather than one resolved by branch.
 
-`git-ship` verifies again at its own gate, repeating Step 3 on a clean run. Keep that repeat, since a resumed run enters at that gate.
+- Read `${CLAUDE_SKILL_DIR}/references/draft-mark.md` on reaching that point for the one command that proves the target, marks it, and reads the flag back
+- A `false` read stops the chain, and never re-issue the mark on it
+- Emit the Output block on the wake after `git-ship`'s background CI watch exits on `passing`, not when the turn ends on its watch line
+- Keep `git-ship`'s own verify gate, which repeats Step 3 on a clean run, since a resumed run enters at that gate
 
 ## Output
 
@@ -103,9 +125,7 @@ Respond with up to two lines:
 🖼️ <N> visual boxes unchecked (<M> taste), owed on the evidence comment of <PR url> to the operator, or to the UI reviewer for the boxes a driver can run
 ```
 
-`<state>` is whatever the Step 6 read returned, being `draft` or `ready, unsupervised`, rather than the state the mark asked for.
-
-Fill the second line from the counts Step 5 held, and omit it when no checklist was produced.
+`<state>` is whatever the Step 6 read returned, being `draft` or `ready, unsupervised`, rather than the state the mark asked for. Fill the second line from the counts Step 5 held, and omit it when no checklist was produced.
 
 This block replaces the one `git-ship` closes on rather than following it, since emitting both reports one run twice and buries the state under a `✅ Shipped` that does not name it.
 

package/claude/skills/backlog-triage/SKILL.md

@@ -9,25 +9,37 @@ metadata:
 
 A backlog only grows while nothing can decline a row. This pass reads every row against the current tree, files one verdict per row for the operator, and later applies what they approved.
 
-The record is an ordinary intake folder at `.canon/intake/<nn>-backlog-triage/`. Read `${CLAUDE_SKILL_DIR}/../plan-intake/references/intake.md` before writing any file in it, since it holds the item format, the frontmatter, the index shape, and the answer contract this skill is bound by. Read `${CLAUDE_SKILL_DIR}/../task-board/references/board.md` and `${CLAUDE_SKILL_DIR}/../task-board/references/tasks.md` before applying, since the first holds the backlog and the ordering file and the second holds the `Declined:` line.
+The record is an ordinary intake folder at `.canon/intake/<nn>-backlog-triage/`, so three sibling references bind it.
+
+- `${CLAUDE_SKILL_DIR}/../plan-intake/references/intake.md`, read before writing any file in the folder, holds the item format, the frontmatter, the index shape, and the answer contract
+- `${CLAUDE_SKILL_DIR}/../task-board/references/board.md`, read before applying, holds the backlog and the ordering file
+- `${CLAUDE_SKILL_DIR}/../task-board/references/tasks.md`, read before applying, holds the `Declined:` line
 
 ## Guards
 
-- Resolve `.canon/tasks/` and `.canon/intake/` at the main worktree root, not `pwd`. Run `git worktree list --porcelain | grep -m 1 '^worktree ' | cut -d' ' -f2-`, falling back to `pwd` outside a git repo.
+- Resolve `.canon/tasks/` and `.canon/intake/` at the main worktree root, from `git worktree list --porcelain | grep -m 1 '^worktree ' | cut -d' ' -f2-`, falling back to `pwd` outside git
 - If `.canon/tasks/backlog.md` does not exist at that root, stop: `❌ No backlog at .canon/tasks/backlog.md. Nothing to triage.`
-- Never fill a `You:` slot, and never read an empty one as agreement. Answering runs through `plan-intake-answer` or the operator's own edit, which is what keeps silence from deciding a row.
+- Never fill a `You:` slot, and never read an empty one as agreement, so silence never decides a row. Answering runs through `plan-intake-answer` or the operator's own edit.
 - Branch on each `canon` record's `ok` and `reason` rather than on the exit code, which a shell function wrapping `canon` can flatten to zero.
 
 ## Step 1: detect the phase
 
-Run `canon intake list --json` and take the folders whose slug ends in `-backlog-triage`. Read the newest by ordinal. Where the installed binary carries no such subcommand, stop and report it, since opening a folder beside one awaiting apply leaves the first stranded and applying needs the same verb.
+Run `canon intake list --json` and read the newest folder by ordinal whose slug ends in `-backlog-triage`. Where the binary carries no such subcommand, stop and report it, since a second folder would strand the first and apply needs the same verb.
+
+| State of the newest folder                | Route                                                                                                      |
+| ----------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
+| None, or fully applied                    | Run the file phase                                                                                         |
+| Unread above zero                         | Stop: `❌ <n> items in <slug> are unread. Run /canon:plan-intake-answer, then re-run this skill to apply.` |
+| Malformed above zero                      | Stop: `❌ <n> items in <slug> carry no answer slot. Repair them in the cluster files before applying.`     |
+| Every item answered, some not yet applied | Run the apply phase                                                                                        |
 
-- **No folder, or the newest is fully applied.** Run the file phase.
-- **Unread above zero.** Stop: `❌ <n> items in <slug> are unread. Run /canon:plan-intake-answer, then re-run this skill to apply.`
-- **Malformed above zero.** Stop: `❌ <n> items in <slug> carry no answer slot. Repair them in the cluster files before applying.`
-- **Every item answered, some not yet applied.** Run the apply phase.
+### When an item counts as applied
 
-An item is applied once its task has moved under `.canon/tasks/declined/` or `.canon/tasks/archive/`, or once its live task file carries a `## Findings` line naming the folder slug. A task whose file sits in none of the three folders counts as applied only once `backlog.md` no longer names it, since its dangling line is the one thing apply has left to remove. Test that per item rather than trusting a count, since a run can stop partway. An item apply skipped for an unreadable answer stays unapplied, so the folder stays in the apply phase until the operator rewrites that answer.
+Test each item rather than trusting a count, since a run can stop partway. An item apply skipped for an unreadable answer stays unapplied until the operator rewrites it.
+
+- Its task has moved under `.canon/tasks/declined/` or `.canon/tasks/archive/`
+- Its live task file carries a `## Findings` line naming the folder slug
+- Its task file sits in none of the three folders and `backlog.md` no longer names it, since the dangling line is all apply has left to remove
 
 ## File phase
 
@@ -35,7 +47,7 @@ Writes only inside `.canon/intake/<nn>-backlog-triage/`, so it runs under any ro
 
 ### Step 2: claim the folder
 
-Run `canon records ordinal intake backlog-triage --claim --json` and take its `name`. The verb creates the folder in the same act, so two sessions opening at once never share one. Where the installed binary carries no such subcommand, report it and stop rather than picking an ordinal by hand.
+Run `canon records ordinal intake backlog-triage --claim --json` and take its `name`. The verb creates the folder in the same act, so two sessions opening at once never share one. Where the binary carries no such subcommand, report it and stop rather than picking an ordinal by hand.
 
 ### Step 3: read every row
 
@@ -45,33 +57,51 @@ A row whose link resolves to no file gets an item anyway, carrying `decline` and
 
 ### Step 4: measure each row
 
-Measure every claim the task makes against the tree and `git log` during this pass. Grep for the construct its defect names and count the sites, check whether each open outcome's behavior exists, and search the log for a commit or pull request that shipped it under another task. Never carry a figure from the task file forward as current, since the task states what was true when it was filed.
+Measure every claim the task makes against the tree and `git log` during this pass, never carrying a figure from the task file forward, since it states what was true when filed. Name the commit the pass measured against in the overview body.
+
+- Grep for the construct its defect names and count the sites
+- Check whether each open outcome's behavior exists
+- Search the log for a commit or pull request that shipped it under another task
 
-Then gather the evidence Step 5 reads for each row that reproduces. Check whether its origin line or `## Findings` names an issue, a run, or a person it bit. Search the log for a commit or pull request that worked around it rather than fixing it. For a defect in something the project ships, whether a route or a page its users call or a rule, a seed, a scaffold, or a verb other repositories copy or run, name the shipped path it sits on. Record each one that is absent as absent rather than inferring it.
+For each row that reproduces, gather the evidence Step 5 reads, and record each piece that is absent as absent rather than inferring it.
 
-Name the commit the pass measured against in the overview body.
+- An issue, a run, or a person it bit, named in its origin line or `## Findings`
+- A commit or pull request that worked around it rather than fixing it
+- The shipped path a defect sits on, being a route or page users call, or a rule, seed, scaffold, or verb other repositories copy or run
 
 ### Step 5: pick the verdict
 
-Keep and promote carry the burden of proof, and a defect that still exists does not meet it. A row filed against the tree nearly always still reproduces, so a test of reproduction alone keeps almost every row.
+Keep and promote carry the burden of proof, and a defect that still exists does not meet it. A row filed against the tree nearly always reproduces, so a reproduction test alone keeps almost every row. A row earns keep or promote only by naming a cost or a reach from Step 4's evidence.
+
+| Ground | What it takes                                                                                                                                                |
+| ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| Cost   | A wrong result this pass observed by running the verb or reading committed output, or an issue, run, person, or workaround commit it hit, not measured fixed |
+| Reach  | The defect sits on a shipped path, so everyone reaching it receives a wrong instruction, a broken or unbounded behavior, or a wrong output, hit or not       |
+
+A plausible cost names nothing. A row arguing what could go wrong off a shipped path, with no observed output and no hit, is declined however likely it sounds.
+
+### What is not a reach
 
-A row earns keep or promote only by naming one of two things from the evidence Step 4 gathered:
+Three things are not a reach, and a row resting on one needs a cost instead.
 
-- **A cost**: the defect gives a wrong result that this pass observed, by running the verb that carries it or reading the committed output that shows it, or that the row's evidence shows an issue, a run, or a person hit, a workaround commit included. A hit counts only while the pass does not measure it as fixed or as no longer recurring.
-- **A reach**: the defect sits on a path the project ships, and everyone who reaches that path, whether a user calling it or a target copying or running it, receives the defect as a wrong instruction, a broken, failing, or unbounded behavior, or a wrong output. Reach needs no hit, since the path's users meet the defect whether or not anyone reported it.
+- A missing feature on a shipped surface, which leaves the path working and adds a capability, a document kind, or guidance
+- A defect that changes nothing a user or a target receives, such as dead code on a shipped path
+- A defect that shows only in this repository's own config, workflows, scripts, or fixtures
 
-A plausible cost names nothing. A row arguing what could go wrong off a shipped path, with no observed output and no hit, is declined however likely the argument sounds. Three things are not a reach: a missing feature on a shipped surface, a defect that changes nothing a user or a target receives, such as dead code on a shipped path, and a defect that shows only in this repository's own config, workflows, scripts, or fixtures.
+A missing protection is a defect, not a missing feature, and is a reach. Read a row that way when the shipped path lacks a run-time bound, check, or guard, such as a limit, a timeout, or input validation, so it can fail, run unbounded, or return a wrong output.
 
-A missing protection is a defect, not a missing feature. Read a row as a missing protection when the shipped path lacks a bound, a check, or a guard on what it does at run time, such as a limit, a timeout, or input validation, so that the path can fail, run unbounded, or return a wrong output for every user who reaches it. That is a reach. A missing feature leaves the path working as it does today and adds a capability, a document kind, or a sentence of guidance, and it is not a reach.
+A missing feature earns keep through the cost arm when a user asked for it in an issue or a report, or worked around its absence. A feature nobody asked for is declined, and neither a passing mention nor a request the project's own planning filed with no user behind it counts.
 
-A missing feature can still earn keep or promote through the cost arm. A user asking for it in an issue or a report, or working around its absence on their side, is a case someone hit, so that row is never declined for being a feature. A feature nobody asked for is declined. A passing mention is not a request, and neither is one the project's own planning records filed with no user behind it.
+### The four verdicts
 
-- **keep**: the defect reproduces this pass, stated with a count or a path, and the row names a cost or a reach, stated with the observation, the hit, or the shipped path.
-- **promote**: it qualifies for keep, and the thing it was waiting on has cleared, naming what cleared it.
-- **archive**: every open outcome is measured shipped, naming the commit or pull request per outcome position.
-- **decline**: anything else, including a defect that reproduces but names no cost and no reach, a defect the tree no longer holds, work superseded by another task, and a row whose argument rests only on its original filing.
+Age is evidence in neither direction. An old hit reads the same as a new one, by whether the pass measures it as still able to recur.
 
-Age is evidence in neither direction. A row untouched for months is not more declinable than one filed yesterday, and a row filed yesterday is not more worth keeping. An old hit is read the same way as a new one, by whether the pass measures it as still able to recur.
+| Verdict | When                                                                                                                                     |
+| ------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
+| keep    | The defect reproduces this pass, with a count or a path, and the row names a cost or a reach with its observation, hit, or shipped path  |
+| promote | It qualifies for keep, and what it was waiting on has cleared, naming what cleared it                                                    |
+| archive | Every open outcome is measured shipped, naming the commit or pull request per outcome position                                           |
+| decline | Anything else, including a reproduction naming no cost or reach, a defect the tree no longer holds, superseded work, or the filing alone |
 
 ### Step 6: write the items
 
@@ -79,9 +109,9 @@ Write one item per row in the intake item format, one cluster file per domain th
 
 - **`Problem:`** states what this pass measured, with the count, path, or commit behind it
 - **`Fix:`** states what applying the verdict does to the board
-- **`Worth it:`** names the cost or the reach the verdict rests on in one clause, or says the row names neither. A `yes` or a `later` carries no verdict on its own, so a decline can follow either word
+- **`Worth it:`** names the cost or reach the verdict rests on in one clause, or says the row names neither. A `yes` or `later` alone carries no verdict.
 - **`Open:`** reads `decline, archive, keep, or promote?` on every item
-- **`Suggested:`** opens with exactly one of the four verdict tokens, then the reason. An archive suggestion lists every outcome position it closes, as `archive 1, 3: shipped in #NNN`
+- **`Suggested:`** opens with exactly one verdict token, then the reason. An archive lists every outcome position it closes, as `archive 1, 3: shipped in #NNN`.
 - **`Overlaps:`** names a live board task that already carries the work, where one does
 - **`You:`** ships empty
 
@@ -89,42 +119,21 @@ Write `00-overview.md` last, per the intake standard, with the verdict counts by
 
 ## Apply phase
 
-Writes the board and task files. Refuses when this session's name starts with `planner-` or `worker-`: read it from `canon sessions list --self --json` before writing anything, and stop: `❌ Apply writes the board, which the <role> role bans. Run it from an operator or orchestrator session.` A refused or failed read proceeds, since it is indistinguishable from a solo project running no named sessions.
+Writes the board and task files, so it refuses when this session's name starts with `planner-` or `worker-`. Read the name from `canon sessions list --self --json` before writing anything, and stop: `❌ Apply writes the board, which the <role> role bans. Run it from an operator or orchestrator session.`
 
-Every write here is a main-root write. Route a change inside an existing file the way `session-worktree` states, and report it rather than proceeding silently when that skill does not resolve.
+A refused or failed read proceeds, since it is indistinguishable from a solo project running no named sessions. Every write here is a main-root write, so route a change inside an existing file the way `session-worktree` states, and report it rather than proceeding silently when that skill does not resolve.
 
 ### Step 7: read the answers
 
-Run `canon intake list <slug> --json` and read each item's `answer` and `suggested`.
-
-- An answer of `ok` takes the suggested verdict. A `suggested` that opens with no verdict token is malformed: report the item and skip it, never treating it as keep.
-- An answer opening with a verdict token overrides the suggestion. An override to archive names its own outcome positions, and one that names none is reported and skipped.
-- Any other answer, such as a free-text note, is reported and skipped. Never guess a verdict from prose.
-- An item already applied, by the test in Step 1, is skipped silently, which is what makes a re-run write nothing twice.
+Read `${CLAUDE_SKILL_DIR}/references/apply.md` on reaching this step, for how each answer reads, what each verdict runs, and how a refusal routes. The file phase skips it.
 
 ### Step 8: run each verdict
 
-Take the task stem from the item heading. Every verdict leaves the folder slug on its task, which is how Step 1 and `task-board`'s unlinked-origin scan both see the folder as acted on.
-
-- **decline**: `canon tasks decline <stem> --reason "<reason>, backlog triage <slug> item <cluster>#<n>" --json`. The verb clears the backlog line.
-- **decline on a missing file**: when the stem resolves to no file in `.canon/tasks/`, `declined/`, or `archive/`, the verb would refuse as `no-match`, so skip it. Drop the dangling line from `backlog.md` directly and report it as removed with no task behind it. Any other verdict on such an item is reported and skipped, since there is no file to keep, archive, or promote.
-- **archive**: `canon tasks outcome <stem> --close <p> ... --json` for the named positions, then `canon tasks archive <stem> --json`. Outcomes already closed report as closed rather than refusing, so archive still runs. Archive leaves `backlog.md` alone, so drop the task's backlog line once it succeeds, then append the `## Findings` line naming the evidence to the archived file.
-- **keep**: append the `## Findings` line naming what reproduced. The backlog line stays.
-- **promote**: move the backlog line to the bottom of `## Needs a plan` in `.canon/tasks/priority.md`, with a `Waiting on` cell stating what cleared and ending in `last`, then append the `## Findings` line.
-
-Write the `## Findings` line as `- **<YYYY-MM-DD>, backlog triage <slug>:** <verdict>, <evidence>`, the bold label form `${CLAUDE_SKILL_DIR}/../task-board/references/tasks.md` fixes. It is the last write on every verdict with a task file behind it, since Step 1 reads it as applied and a line written ahead of a refused move would mark a row done that never moved.
-
-Before any promote, check the roster the way `task-board` step 4 does: a live session in this repository whose name starts with `orchestrator-` and whose `sessionId` is not this one. When one is found, write the `## Findings` line but not `priority.md` or `backlog.md`, and message that session with the row and its cell so it places the row itself.
+Run each verdict through the task verbs the reference names, writing the `## Findings` line last on every verdict with a task file behind it.
 
 ### Step 9: route on a refusal
 
-Report every refusal on its item and continue with the rest, since one row's refusal says nothing about another's.
-
-- `decline` refusing with `no-match`: the task already moved elsewhere. Report and skip. A missing-file item never reaches the verb, per Step 8.
-- `outcome` refusing, or `archive` refusing with `open-outcomes`: the verdict named too few positions. Report the positions still open and leave the row on the backlog. Never retry with guessed positions.
-- A promote whose row already sits in `priority.md`: report it, skip the move, and still write the `## Findings` line.
-
-Close with `canon tasks validate --json` and report every finding it raises against a row this run touched. After a shell write under `.canon/tasks/`, regenerate the index with `canon indexes regen --no-stage --root <main-root> <main-root>/.canon/tasks/index.md`, since no hook fires on `Bash`.
+Report every refusal on its item and continue, then close with `canon tasks validate --json`, per the reference.
 
 ## Output
 

package/claude/skills/backlog-triage/references/apply.md

@@ -0,0 +1,69 @@
+---
+title: Backlog triage apply reference
+description: How the apply phase of a backlog triage reads the operator's answers, runs each verdict through the task verbs, writes the findings line, and routes a refusal
+---
+
+# Backlog triage apply reference
+
+Applies to Steps 7 through 9 of `backlog-triage`, the phase that writes the board and task files once every item in a `<nn>-backlog-triage` intake folder carries an answer. The role guard and the main-root write route stay in the skill body.
+
+## Step 7: read the answers
+
+Run `canon intake list <slug> --json` and read each item's `answer` and `suggested`. Never guess a verdict from prose.
+
+| Answer                                      | Reading                                                              |
+| ------------------------------------------- | -------------------------------------------------------------------- |
+| `ok`                                        | Takes the suggested verdict                                          |
+| `ok` on a `suggested` opening with no token | Malformed, so report the item and skip it, never treating it as keep |
+| Opens with a verdict token                  | Overrides the suggestion                                             |
+| An archive override naming no positions     | Reported and skipped                                                 |
+| Any other answer, such as a free-text note  | Reported and skipped                                                 |
+
+An item already applied, by the test in the skill's Step 1, is skipped silently, which is what makes a re-run write nothing twice.
+
+## Step 8: run each verdict
+
+Take the task stem from the item heading. Every verdict leaves the folder slug on its task, which is how Step 1 and `task-board`'s unlinked-origin scan both see the folder as acted on.
+
+| Verdict | Command and board write                                                                                                                                 |
+| ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| decline | `canon tasks decline <stem> --reason "<reason>, backlog triage <slug> item <cluster>#<n>" --json`, which clears the backlog line                        |
+| archive | `canon tasks outcome <stem> --close <p> ... --json` for the named positions, then `canon tasks archive <stem> --json`                                   |
+| keep    | Append the `## Findings` line naming what reproduced, leaving the backlog line                                                                          |
+| promote | Move the backlog line to the bottom of `## Needs a plan` in `.canon/tasks/priority.md`, its `Waiting on` cell stating what cleared and ending in `last` |
+
+### Archive and missing files
+
+An archive treats outcomes already closed as closed rather than refusing, so it still runs. Archive leaves `backlog.md` alone, so drop the task's backlog line once it succeeds, then append the `## Findings` line naming the evidence to the archived file.
+
+A decline whose stem resolves to no file in `.canon/tasks/`, `declined/`, or `archive/` would refuse as `no-match`, so skip the verb. Drop the dangling line from `backlog.md` directly and report it as removed with no task behind it. Any other verdict on such an item is reported and skipped, since there is no file to act on.
+
+### The findings line
+
+Write it as `- **<YYYY-MM-DD>, backlog triage <slug>:** <verdict>, <evidence>`, the bold label form `${CLAUDE_SKILL_DIR}/../task-board/references/tasks.md` fixes. It is the last write on every verdict with a task file behind it.
+
+Step 1 reads the line as applied, so a line written ahead of a refused move would mark a row done that never moved.
+
+### Promote and a live orchestrator
+
+Before any promote, check the roster the way `task-board` step 4 does, for a live session in this repository whose name starts with `orchestrator-` and whose `sessionId` is not this one.
+
+When one is found, write the `## Findings` line but not `priority.md` or `backlog.md`, and message that session with the row and its cell so it places the row itself.
+
+## Step 9: route on a refusal
+
+Report every refusal on its item and continue with the rest, since one row's refusal says nothing about another's.
+
+| Refusal                                               | Route                                                                                 |
+| ----------------------------------------------------- | ------------------------------------------------------------------------------------- |
+| `decline` with `no-match`                             | The task already moved elsewhere, so report and skip                                  |
+| `outcome` refusing, or `archive` with `open-outcomes` | Too few positions named, so report those still open and leave the row, never guessing |
+| A promote whose row already sits in `priority.md`     | Report it, skip the move, and still write the `## Findings` line                      |
+
+A missing-file item never reaches the verb, per Step 8.
+
+### Closing the run
+
+Close with `canon tasks validate --json` and report every finding it raises against a row this run touched.
+
+After a shell write under `.canon/tasks/`, regenerate the index with `canon indexes regen --no-stage --root <main-root> <main-root>/.canon/tasks/index.md`, since no hook fires on `Bash`.

package/claude/skills/build-in-slices/SKILL.md

@@ -7,9 +7,9 @@ metadata:
 
 # Build in slices
 
-A session handed a plan tends to build all of it in one pass and test at the end. The diff grows past what anyone can read, a failure late in the run could have come from any of the changes, and nothing in history marks a point that worked. A defect it notices on the way gets fixed in the same diff, so the review reads two changes as one. This skill carries the discipline that keeps each step small enough to verify and revert on its own.
+A session handed a plan tends to build all of it in one pass and test at the end. The diff grows past what anyone can read, a late failure could have come from any change, and nothing in history marks a point that worked.
 
-Load it before implementing a plan with more than one behavior or more than one file to change. Skip it for a change that is already one behavior in one place.
+A defect it notices on the way gets fixed in the same diff, so the review reads two changes as one. This skill keeps each step small enough to verify and revert on its own. Load it before implementing a plan with more than one behavior or file, and skip it for one behavior in one place.
 
 ## Run the cycle per slice
 
@@ -26,7 +26,7 @@ Leave the build passing at every commit. A slice that cannot pass on its own is
 
 - Prefer one path through every layer it needs, end to end, over one whole layer at a time. A finished path proves the layers fit, and a finished layer proves nothing until the next one meets it.
 - Take the riskiest or least certain piece first. When it fails, the slices that would have rested on it are not built yet.
-- Build the contract first when two sides are written against it, such as a command and the skill that calls it, or a format and its reader. Commit the contract as its own slice, then each side against it.
+- Build the contract first when two sides are written against it, such as a command and the skill calling it, or a format and its reader. Commit it as its own slice, then each side.
 - Read the plan's file list as the scope of the whole branch, not as the order. Cut the order from the three rules above.
 
 ## Keep each commit safe to revert on its own
@@ -40,7 +40,7 @@ Leave the build passing at every commit. A slice that cannot pass on its own is
 
 A defect outside the plan that turns up mid-build is a finding, not a slice. Fixing it on this branch widens a diff the plan scoped and hides the fix inside an unrelated review.
 
-- Write it in one line under the open task's `## Findings`, naming the file and what is wrong, when the build is closing a task. Open the line with the bold source-and-date label from `${CLAUDE_SKILL_DIR}/../task-board/references/tasks.md`.
+- Write it as one line under the task's `## Findings`, naming the file and the fault when the build closes a task, opening with the label `${CLAUDE_SKILL_DIR}/../task-board/references/tasks.md` fixes
 - Carry it in the handover message instead when no task exists, and never create a file to hold it.
 - Leave the file as it is, even when the fix is one line.
 - Fix it here only when the plan's own change cannot pass without it, and then say so in the commit that does.
@@ -74,6 +74,8 @@ Read `${CLAUDE_SKILL_DIR}/references/adopted.md` only when extending this guidan
 
 ### Scope and ordering
 
+Scope and order carry their own signs.
+
 - You opened a file the plan does not name and are about to edit it.
 - A commit deletes code and adds its replacement in the same change.
 - You are about to stage a test in a commit after the one that added its code.
@@ -89,6 +91,8 @@ Check each line against the branch the build produced. A line answering no is fi
 
 ### Tree and scope
 
+Check the tree and the scope the same way.
+
 - The working tree holds no uncommitted implementation work.
 - Every file changed is in the plan's scope, or its commit says why the plan needed it.
 - Every defect noticed outside the plan is written in the task's findings or the handover, and its file is unchanged.

package/claude/skills/canon-cli/SKILL.md

@@ -88,6 +88,8 @@ Read the doc each line names before running one of these. `canon docs install-an
 
 ### Design, migrate, and indexes
 
+Three more verbs rewrite files in place.
+
 - `canon design sync` replaces the shipped design files and leaves `.claude/design/project/` alone.
 - `canon migrate --write` rewrites files that cite a retired name or layout. It reports and writes nothing without the flag. See `canon docs migrate`.
 - `canon indexes regen` rewrites each generated `index.md` from the folder's current state, so a hand edit there is lost. See `canon docs indexes`.
@@ -96,4 +98,6 @@ Read the doc each line names before running one of these. `canon docs install-an
 
 ## Source of truth
 
-- `canon docs install-and-sync` states what each install and sync verb writes, refuses, or leaves alone. `canon docs indexes` and `canon docs migrate` state the same for their verbs. When a doc and this skill disagree, the doc wins.
+- `canon docs install-and-sync` states what each install and sync verb writes, refuses, or leaves alone
+- `canon docs indexes` and `canon docs migrate` state the same for their verbs
+- When a doc and this skill disagree, the doc wins