@erclx/canon 5.41.0 → 5.43.0

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.41.0",
+  "version": "5.43.0",
   "author": {
     "name": "Eric Le",
     "url": "https://github.com/erclx"

package/claude/skills/api-design/references/adopted.md

@@ -5,36 +5,56 @@ description: Which external API design sources this skill adopted, which it decl
 
 # Adopted and declined
 
-External sources were read and filtered rather than imported. This file is the record. A later session extending the skill adds to it rather than re-arguing an item already settled here.
+External sources were read and filtered rather than imported. This file is the record, and a later session extending the skill adds to it rather than re-arguing an item settled here.
 
-## Adopted
+## Adopted from the default shelf
 
-### From the default shelf
+### Observable behavior
 
-**Hyrum's Law.** [Software Engineering at Google, ch. 1](https://abseil.io/resources/swe-book/html/ch01.html): with enough users, every observable behavior of a system is depended on by somebody, whatever the contract promises. Adopted as the opening group, stated as design rules rather than as an observation, so a session decides what is observable before a caller decides it for them. Ordering and timing are named because the chapter's own examples are hash iteration order and timing.
+[Software Engineering at Google, ch. 1](https://abseil.io/resources/swe-book/html/ch01.html) states Hyrum's Law, that with enough users, every observable behavior of a system is depended on by somebody, whatever the contract promises.
 
-**The One-Version Rule.** [Software Engineering at Google, ch. 21](https://abseil.io/resources/swe-book/html/ch21.html): a repository keeps one version of each dependency, so a change to it migrates every caller rather than leaving two versions live. Adopted under additive change for a caller that cannot pin, which is any module imported from inside one repository.
+Adopted as the opening group, stated as design rules rather than as an observation, so a session decides what is observable before a caller decides it for them. Ordering and timing are named because the chapter's own examples are hash iteration order and timing.
 
-### From one external skill
+### One version per dependency
 
-From `addyosmani/agent-skills@2686b620`, [`skills/api-and-interface-design/SKILL.md`](https://github.com/addyosmani/agent-skills/blob/2686b620fc1fed2e8f60c704839c766b8594c6b6/skills/api-and-interface-design/SKILL.md):
+[Software Engineering at Google, ch. 21](https://abseil.io/resources/swe-book/html/ch21.html) states the One-Version Rule, keeping one version of each dependency in a repository, so a change to it migrates every caller rather than leaving two versions live. Adopted under additive change for a caller that cannot pin, which is any module imported from inside one repository.
+
+## Adopted from one external skill
+
+From `addyosmani/agent-skills@2686b620`, [`skills/api-and-interface-design/SKILL.md`](https://github.com/addyosmani/agent-skills/blob/2686b620fc1fed2e8f60c704839c766b8594c6b6/skills/api-and-interface-design/SKILL.md).
+
+### Contract and errors
 
 **Contract first.** Write the interface before the body. Adopted as its own group, widened from an endpoint to a signature, a flag set, an output shape, and a schema.
 
-**One error shape.** Every failure on one surface carries the same structure. Adopted with a stable code added for the caller to branch on, and a clause keeping internal implementation details out of the message, since no project rule carries either for every code stack.
+**One error shape.** Every failure on one surface carries the same structure. Adopted with a stable code for the caller to branch on, and internal details kept out of the message, since no project rule carries either for every code stack.
+
+### Input and change
 
 **Validation at the boundary.** Check input where it enters and trust it inside. Adopted, with a value read back from a file or another service counted as input.
 
-**Additive change.** New fields optional, nothing removed in place. Adopted, with a change of meaning under an existing name added as its own ban, since it breaks a caller as surely as a removal and no rename shows in the diff.
+**Additive change.** New fields optional, nothing removed in place. Adopted, with a change of meaning under an existing name as its own ban, since it breaks a caller as surely as a removal and no rename shows in the diff.
+
+### Idempotency
 
-**Idempotency.** A stored key honored on retry, an atomic claim under a unique constraint, a reused key with a different body failing loudly, and retention past the longest retry. Adopted as four rules, keeping the reused-key rule, which is the one most often left out.
+A stored key honored on retry, an atomic claim under a unique constraint, a reused key with a different body failing loudly, and retention past the longest retry. Adopted as four rules, keeping the reused-key rule, which is the one most often left out.
 
-**Excuses, red flags, and a closing checklist.** The same source's skill anatomy, adopted toolkit-wide through `${CLAUDE_SKILL_DIR}/../create-skill/references/skill-practice.md`. Each excuse row here rebuts a reason a session gives when it is about to break a caller, such as "nobody depends on that field".
+### The closing sections
+
+The same source's skill anatomy supplies the excuses, red flags, and closing checklist, adopted toolkit-wide through `${CLAUDE_SKILL_DIR}/../create-skill/references/skill-practice.md`. Each excuse row here rebuts a reason a session gives when about to break a caller, such as "nobody depends on that field".
 
 ## Declined
 
-**Protocol-specific guidance.** The source skill carries verbs, status codes, pagination, and URL shapes for one protocol style. Declined because the body has to hold for a function's exports, a command's flags, and a file format as much as an endpoint, and a protocol section would route every non-network surface to rules that do not apply. A project needing those conventions states them in its own stack rule.
+Each item below was read and left out, with the reason it changes nothing a session does here.
+
+### Protocol-specific guidance
+
+The source skill carries verbs, status codes, pagination, and URL shapes for one protocol style. Declined because the body holds for a function's exports, a command's flags, and a file format as much as an endpoint, so a protocol section would route every non-network surface to rules that do not apply.
+
+A project needing those conventions states them in its own stack rule.
+
+### Depth and versions
 
-**Interface depth.** Ousterhout's deep modules, after [A Philosophy of Software Design](https://web.stanford.edu/~ouster/cgi-bin/book.php), judge how much a module hides behind its surface. Declined here because depth is about what sits behind a boundary, and this skill owns only what crosses it. `code-craft` carries it.
+**Interface depth.** Ousterhout's deep modules, after [A Philosophy of Software Design](https://web.stanford.edu/~ouster/cgi-bin/book.php), judge how much a module hides behind its surface. Depth is about what sits behind a boundary, and this skill owns only what crosses it, so `code-craft` carries it.
 
-**Versioned surfaces as the default.** Shipping a new version beside the old for every breaking change. Declined as the default because additive change avoids the break in the first place, and two live versions split the callers. The One-Version Rule covers a caller that cannot pin.
+**Versioned surfaces as the default.** Shipping a new version beside the old for every breaking change. Additive change avoids the break in the first place and two live versions split the callers, so the One-Version Rule covers a caller that cannot pin.

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

@@ -20,6 +20,7 @@ Without this skill, the run from an approved plan to an open pull request is a c
 - Continue past a produced UI checklist rather than stopping on it, and report its unchecked boxes in the closing block, since the draft mark already holds the merge
 - Prove the draft target's head is the current branch and its state is open before marking it, and stop with nothing marked on a mismatch, since the number is retyped between steps and a draft mark on a release pull request holds that release
 - Stop a fan-in member after its verify and test order with a push and a done message rather than a pull request, and open an integrator's build by merging the member branches, since parallel batches sharing edge files put every open sibling into conflict on each merge
+- Wait for both review families through `canon pr review-state --wait` once CI passes on a launch that named a controller, which alone dispatches the reviewers, bounded at the lift's own default, and hand the record to the controller on a timeout, since a worker improvising the read polled issue comments, never saw a UI close posted as a review, and stalled with both reviewers idle
 - Name the recovery for the stop it took, since the value of stopping is that the user knows where to resume
 
 ## Must not

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

@@ -65,9 +65,9 @@ If neither form is present, stop: `❌ <path> carries no plan sections. A plan l
 
 ### 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.
+Read `## The suggested-and-answer contract` in `${CLAUDE_SKILL_DIR}/../plan-feature/references/plan.md` before acting on a question, for what it resolves to and the form an override takes. A question left open 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.
+Open the task's `## Findings` line for an override with the bold source-and-date label `${CLAUDE_SKILL_DIR}/../task-board/references/tasks.md` fixes.
 
 ## Step 2: implement
 
@@ -107,7 +107,7 @@ When the plan's `**Constraints:**` carry a `Fan-in member of` bullet, push the b
 
 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.
+When it produces a checklist, read `${CLAUDE_SKILL_DIR}/references/ui-checklist.md` for the counts to hold before `pr-evidence` removes the file. A diff passing this test also owes the preview server `role-worker` states, started before Step 6.
 
 ## Step 6: ship
 
@@ -119,9 +119,29 @@ This chain adds one thing. Mark the pull request as a draft as soon as `git-ship
 
 - 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
+- Act on the wake after the CI watch exits on `passing`, not when the turn ends on its watch line, moving to Step 7 under a named controller and to the Output block otherwise
 - Keep `git-ship`'s own verify gate, which repeats Step 3 on a clean run, since a resumed run enters at that gate
 
+## Step 7: wait for the reviews
+
+Run this step only when the launch named a controlling session, since only a controller dispatches the reviewers. A hand-launched run has nobody reviewing, so it emits the Output block on the CI wake instead of waiting on a pass that cannot arrive.
+
+Read review state through `canon pr review-state` alone, since both families post as pull request reviews, and a worker polling issue comments instead stalled with both reviewers idle. Run it in the background with the number Step 6 returned, since the wait outlasts a foreground shell call, and act on the wake.
+
+```bash
+canon pr review-state <number> --wait 1200 --json
+```
+
+Branch on the record's `reason` rather than on the exit, which a shell function wrapping `canon` can flatten to zero.
+
+| `reason`    | Route                                                                                                                  |
+| ----------- | ---------------------------------------------------------------------------------------------------------------------- |
+| `covered`   | Emit the Output block. Invoke `canon:review-address` when `review.reason` or `ui.reason` reads open at the tip         |
+| `timeout`   | Send the record to the controller per `canon:role-worker`, emit the Output block, and stop rather than waiting again   |
+| Any refusal | Report the `reason` to the controller the same way and stop, since an unread thread is not one nobody has reviewed yet |
+
+Skip the `review-address` call when a reviewer's message already started it, since that message carries the same posted pass. A close in both families needs nothing from this session, since the reviewers run the lift on their close.
+
 ## Output
 
 Respond with up to two lines:

package/claude/skills/auto-ship/references/draft-mark.md

@@ -19,14 +19,40 @@ gh api graphql -f query='mutation($id: ID!) { convertPullRequestToDraft(input: {
 gh api repos/{owner}/{repo}/pulls/<number> --jq '{isDraft: .draft}'
 ```
 
-The target check and the read-back go through REST. The mark itself is a GraphQL mutation, because the REST pull request update carries no draft field, so the mark is local-only: a cloud session's GitHub access blocks GraphQL, the mutation fails there, and the read-back reports `false`. A cloud worker's pull request therefore opens ready, and its chain stops at this step with the pull request already open.
+## Why the mark is local-only
 
-Name the number `git-ship`'s pull request step returned in every position rather than leaving any to resolve by branch. `${CLAUDE_SKILL_DIR}/../git-pr/REQUIREMENT.md` states why: a lookup that resolves by branch alone can return a closed pull request sharing that head, so the number is resolved once and reused rather than re-derived.
+The target check and the read-back go through REST. The mark itself is a GraphQL mutation, because the REST pull request update carries no draft field.
 
-A refusal is a stop. Report the line the shell printed, then resolve the number from the `number=` and `head=` lines of `git-pr`'s output and re-run the command by hand. The comparison sits in the shell rather than in the session's reading of a printed value, which is the same split `git-pr`'s `assert_own_pr` makes, because the judgment that picked a wrong number is the one that would read the check.
+- A cloud session's GitHub access blocks GraphQL, so the mutation fails there and the read-back reports `false`
+- A cloud worker's pull request therefore opens ready, and its chain stops at this step with the pull request already open
 
-The number crosses from that step's output into a command this session types, which is the one place a number gets authored rather than derived. A number misread there, or inferred from the newest pull request in view, would draft a stranger's pull request. A release pull request is the worst such target, since the mark holds the release and this role may not lift it again.
+## The number
 
-Report what the read returned rather than what the command printed, since the exit says the call ran and says nothing about the state. A `true` reports a draft. A `false` reports the pull request as opened ready and unsupervised, and the chain stops there. Never re-issue the mark on a disagreeing read, which fights whoever readied it instead of guarding anything.
+Name the number `git-ship`'s pull request step returned in every position rather than leaving any to resolve by branch. `${CLAUDE_SKILL_DIR}/../git-pr/REQUIREMENT.md` states why, since a lookup by branch alone can return a closed pull request sharing that head.
 
-Placement is why the call sits ahead of the watch rather than after it. Marking afterwards leaves the pull request unmarked for the whole CI run, which is the stretch an unattended worker's branch is least supervised. What the mark buys is a reader learning the pull request has had no review yet. It buys no bound on that stretch: readying a pull request to merge lifts the mark, GitHub requires it before a merge, and the act runs through `canon pr lift`, which a reviewer runs on its close and the controlling session runs as the fallback, or through the operator directly. `role-worker` states the mirroring refusal of an instruction to ready the pull request directly, whoever sends it.
+The number crosses from that step's output into a command this session types, the one place a number gets authored rather than derived. A number misread there, or inferred from the newest pull request in view, would draft a stranger's pull request.
+
+- A release pull request is the worst such target, since the mark holds the release and this role may not lift it again
+
+### A refusal
+
+A refusal is a stop. Report the line the shell printed, then resolve the number from the `number=` and `head=` lines of `git-pr`'s output and re-run the command by hand.
+
+The comparison sits in the shell rather than in the session's reading of a printed value, the same split `git-pr`'s `assert_own_pr` makes. The judgment that picked a wrong number is the one that would read the check.
+
+## The read-back
+
+Report what the read returned rather than what the command printed, since the exit says the call ran and says nothing about the state.
+
+- A `true` reports a draft
+- A `false` reports the pull request as opened ready and unsupervised, and the chain stops there
+- Never re-issue the mark on a disagreeing read, which fights whoever readied it instead of guarding anything
+
+## Why the mark sits ahead of the watch
+
+Marking afterwards leaves the pull request unmarked for the whole CI run, the stretch an unattended worker's branch is least supervised. What the mark buys is a reader learning the pull request has had no review yet.
+
+It buys no bound on that stretch. Readying a pull request to merge lifts the mark, and GitHub requires it before a merge.
+
+- The lift runs through `canon pr lift`, which a reviewer runs on its close and the controlling session runs as the fallback, or through the operator directly
+- `role-worker` states the mirroring refusal of an instruction to ready the pull request directly, whoever sends it

package/claude/skills/auto-ship/references/failure-recovery.md

@@ -7,16 +7,18 @@ description: The step an operator resumes from after each auto-ship stop point,
 
 Every stop point leaves recoverable state. The user resumes manually from the appropriate step.
 
-| Stop point                                 | Recovery                                                                                                                                        |
-| ------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------- |
-| No plan (derived)                          | Run `/plan-feature` to create one                                                                                                               |
-| No plan (caller-supplied)                  | Check the path or slug passed to autoship, then re-run                                                                                          |
-| No task (caller-supplied)                  | Check the task path passed to autoship, then re-run                                                                                             |
-| Task carries no `Plan:` line               | Write the plan, point the task's `Plan:` line at it, then re-run                                                                                |
-| Task points at an archived plan            | The work already shipped. Reopen the task against a live plan, or pass that plan's path directly.                                               |
-| Task's `Plan:` pointer resolves to nothing | Repoint the task's `Plan:` line at the plan that exists, then re-run                                                                            |
-| Resolved file carries no plan shape        | Point autoship at a plan under `.canon/plans/feature-<slug>.md` or at a task under `.canon/tasks/`, then re-run                                 |
-| Branch collision on worktree entry         | `session-worktree` Step 5 found `<slug>` already as a local branch. Resolve manually (rename or delete the stale branch), then re-run autoship. |
-| Verify fails                               | Read logs, fix manually, run `/git-ship`                                                                                                        |
-| git-ship fails                             | Inspect hook or remote error, run again                                                                                                         |
-| Draft target is not this branch's          | Nothing was marked. Read the number and `head=` from `git-pr`'s output, confirm they match, then run the mark by hand                           |
+| Stop point                                 | Recovery                                                                                                                                           |
+| ------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------- |
+| No plan (derived)                          | Run `/plan-feature` to create one                                                                                                                  |
+| No plan (caller-supplied)                  | Check the path or slug passed to autoship, then re-run                                                                                             |
+| No task (caller-supplied)                  | Check the task path passed to autoship, then re-run                                                                                                |
+| Task carries no `Plan:` line               | Write the plan, point the task's `Plan:` line at it, then re-run                                                                                   |
+| Task points at an archived plan            | The work already shipped. Reopen the task against a live plan, or pass that plan's path directly.                                                  |
+| Task's `Plan:` pointer resolves to nothing | Repoint the task's `Plan:` line at the plan that exists, then re-run                                                                               |
+| Resolved file carries no plan shape        | Point autoship at a plan under `.canon/plans/feature-<slug>.md` or at a task under `.canon/tasks/`, then re-run                                    |
+| Branch collision on worktree entry         | `session-worktree` Step 5 found `<slug>` already as a local branch. Resolve manually (rename or delete the stale branch), then re-run autoship.    |
+| Verify fails                               | Read logs, fix manually, run `/git-ship`                                                                                                           |
+| git-ship fails                             | Inspect hook or remote error, run again                                                                                                            |
+| Draft target is not this branch's          | Nothing was marked. Read the number and `head=` from `git-pr`'s output, confirm they match, then run the mark by hand                              |
+| Review wait timed out                      | The record went to the controller. Once the reviewers are dispatched, re-run `canon pr review-state <number> --wait 1200 --json` in the background |
+| Review wait refused                        | Fix what the `reason` names, such as an unreadable remote, then re-run `canon pr review-state <number> --wait 1200 --json` in the background       |

package/claude/skills/auto-ship/references/tier-failures.md

@@ -9,21 +9,42 @@ Step 1 of `auto-ship`, tier 1. The session reads this file when the invocation c
 
 ## Reading the pointer
 
-One plan per task is what makes the tier 1 read unambiguous, so it takes the first `Plan:` line outside a fenced sample and never scans for a second line or reads past a second link on that one. A caller who means the task holds its path already, having read it off the board, which is why a bare slug never reaches this tier.
+One plan per task is what makes the tier 1 read unambiguous. It takes the first `Plan:` line outside a fenced sample, and never scans for a second line or reads past a second link on that one.
 
-Read the target out of the link's parentheses, and take the rest of the line when the line carries no link, since an older task writes the target as a plain path with nothing around it. A bare line counts its leading run of tokens carrying `/` or ending in `.md` as targets and stops at the first word that is neither, so trailing prose after one path still names a single plan.
+- A caller who means the task already holds its path, having read it off the board, which is why a bare slug never reaches this tier
+- Read the target out of the link's parentheses, and take the rest of the line when it carries no link, since an older task writes the target as a plain path
+- A bare line counts its leading run of tokens carrying `/` or ending in `.md` as targets and stops at the first word that is neither, so trailing prose after one path still names a single plan
 
-Resolve a relative target against the directory holding the task file rather than against `.canon/tasks/`, and take a project-root target from the root. The archived task is what makes that base matter, since the standard points its line at `../../plans/archive/feature-<slug>.md` once the task sits a folder deeper, and reading that from `.canon/tasks/` lands on a repository-root `plans/archive/` that never exists.
+### Resolving the target
+
+Resolve a relative target against the directory holding the task file rather than against `.canon/tasks/`, and take a project-root target from the root.
+
+The archived task is what makes that base matter. The standard points its line at `../../plans/archive/feature-<slug>.md` once the task sits a folder deeper, and reading that from `.canon/tasks/` lands on a repository-root `plans/archive/` that never exists.
 
 ## When a tier fails
 
-Tier 1 stops on four failures, and each names a different repair:
+Tier 1 stops on four failures, each naming a different repair. Test them in the order below.
+
+| Failure                      | Stop                                                                                                                                                |
+| ---------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
+| The line links several plans | `❌ <path> links <N> plans on its Plan: line (<every target>), so the task does not say which one this run builds. Pass one plan path directly.`    |
+| No `Plan:` line at all       | `❌ <path> carries no Plan: line, so nothing there names a plan to run. Write the plan and point the task at it, or pass the plan path directly.`   |
+| Pointer into a plans archive | `❌ <path> points at an archived plan, which describes work that already shipped. Reopen the task against a live plan, or pass that plan directly.` |
+| Pointer resolves to no file  | `❌ <path> points at <target>, which does not exist. The citation is stale, so repoint the task or pass the plan path directly.`                    |
+
+### Why each test sits where it does
+
+Each row carries a reason a shortcut would get wrong.
+
+- Test several links first, since taking the first link runs whichever plan leads the line and reports success
+- A row still awaiting a plan is the ordinary case, so the no-line message names the missing pointer rather than the plan sections a reader would then hunt for
+- Test the resolved path for an archive rather than the task's outcomes or its `Pull request:` line, since a stale board gets its ticks wrong and the standard fixes where a shipped pointer lands
+
+### What counts as an archive
 
-- The line links more than one plan. Stop: `❌ <path> links <N> plans on its Plan: line (<every target>), so the task does not say which one this run builds. Pass one plan path directly.` Test this ahead of the three below, since taking the first link runs whichever plan leads the line and reports success.
-- No `Plan:` line at all. Stop: `❌ <path> carries no Plan: line, so nothing there names a plan to run. Write the plan and point the task at it, or pass the plan path directly.` A row still awaiting a plan is the ordinary case, so the message names the missing pointer rather than the missing plan sections a reader would then go hunting for.
-- The pointer resolves into a plans archive. Stop: `❌ <path> points at an archived plan, which describes work that already shipped. Reopen the task against a live plan, or pass that plan directly.` Test the resolved path rather than the task's outcomes or its `Pull request:` line, since a stale board gets its ticks wrong and the standard fixes where a shipped pointer lands.
-- The pointer resolves to no file. Stop: `❌ <path> points at <target>, which does not exist. The citation is stale, so repoint the task or pass the plan path directly.`
+An archive is `.canon/plans/archive/`, plus the two older spellings `${CLAUDE_SKILL_DIR}/../task-board/references/tasks.md` leaves in place for a project that archived plans before the folder nested. From a task those read `../plans-archive/` and `../.tmp/plans-archive/`.
 
-An archive is `.canon/plans/archive/` and also the two older spellings `${CLAUDE_SKILL_DIR}/../task-board/references/tasks.md` leaves in place for a project that archived plans before the folder nested, written from a task as `../plans-archive/` and `../.tmp/plans-archive/`. Test all three, since a shipped pointer in a project nobody migrated lands on the older two. Run the archive test ahead of the existence test, so a pointer into an archive that no longer holds the file still refuses as shipped work rather than as a stale citation.
+- Test all three, since a shipped pointer in a project nobody migrated lands on the older two
+- Run the archive test ahead of the existence test, so a pointer into an archive that no longer holds the file still refuses as shipped work rather than as a stale citation
 
-Each tier fails for a different reason and says so. A supplied path resolving to nothing is a typo, a derived path resolving to nothing is a plan nobody wrote, and a task pointer resolving to nothing is a stale citation the board should have caught.
+Each tier fails for a different reason and says so. A supplied path resolving to nothing is a typo, a derived one is a plan nobody wrote, and a task pointer resolving to nothing is a stale citation the board should have caught.

package/claude/skills/auto-ship/references/ui-checklist.md

@@ -1,6 +1,6 @@
 ---
 title: UI checklist counts
-description: What auto-ship Step 5 holds when ui-checklist produces a checklist, so the closing block can name the unchecked visual boxes after git-pr has removed the file
+description: What auto-ship Step 5 holds when ui-checklist produces a checklist, so the closing block can name the unchecked visual boxes after pr-evidence has removed the file
 ---
 
 # Hold the checklist counts
@@ -9,13 +9,18 @@ Step 5 of `auto-ship`. The session reads this file when `ui-checklist` has produ
 
 The chain continues to Step 6 here in every run, dispatched or hand-run, since the skill cannot tell the two apart and the draft mark at Step 6 holds the merge either way.
 
+## What to count
+
 Count two things in `.canon/tmp/handoff/ui-checklist/<slug>.md` at the main worktree root:
 
 - `<N>`, the `- [ ]` lines
 - `<M>`, how many of those end in `(taste)`
 
-Hold both until the Output block. `git-pr` removes the file once it posts the evidence comment, so a count taken after Step 6 reads nothing.
+Hold both until the Output block. `pr-evidence` removes the file once it posts the evidence comment, so a count taken after Step 6 reads nothing.
+
+## Reading the counts into the closing block
 
-The Output block's second line takes both counts. When every box is a taste box, `<N>` and `<M>` match and the boxes are owed to the operator alone, since a driver reports a taste box as needing a person's eyes rather than passing it, so say the operator and drop the UI reviewer clause.
+The Output block's second line takes both counts. When every box is a taste box, `<N>` and `<M>` match and the boxes are owed to the operator alone, so say the operator and drop the UI reviewer clause.
 
-When `ui-checklist` reports nothing to verify visually, it writes no file, Step 5 holds no count, and the Output block carries no boxes line.
+- A driver reports a taste box as needing a person's eyes rather than passing it, which is why the operator owns an all-taste set
+- When `ui-checklist` reports nothing to verify visually, it writes no file, Step 5 holds no count, and the Output block carries no boxes line

package/claude/skills/auto-ship/references/worktree-name.md

@@ -13,9 +13,15 @@ This step runs ahead of Step 1, so what it holds is the raw invocation argument
 canon tasks plan-branch <argument> --json
 ```
 
-- `conforms: true`: pass the record's `branch`, which is already `<type>/<slug>`, and invoke nothing else to derive a name.
-- `conforms: false`: the plan's own filename breaks a cap in `${CLAUDE_SKILL_DIR}/../git-branch/references/branch.md`. Pass `branch` anyway and say the cap it broke, since the alternative is a name this session shortened by hand, which is a second derivation and the thing this call exists to prevent. `git-branch` decides the rename at ship.
-- Anything else, including a refusal, a record carrying no `branch` key, and an installed binary carrying no `plan-branch` subcommand: invoke `canon:session-worktree` bare and let its ladder derive the name. Say the verb did not answer, so a reader can tell a derived name from a fallback one.
+| Record            | Route                                                                                                                                       |
+| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
+| `conforms: true`  | Pass the record's `branch`, already `<type>/<slug>`, and invoke nothing else to derive a name                                               |
+| `conforms: false` | The plan's filename breaks a cap in `${CLAUDE_SKILL_DIR}/../git-branch/references/branch.md`. Pass `branch` anyway and say the cap it broke |
+| Anything else     | Invoke `canon:session-worktree` bare and let its ladder derive the name, saying the verb did not answer                                     |
+
+- On `conforms: false`, the alternative is a name this session shortened by hand, a second derivation and the thing this call exists to prevent. `git-branch` decides the rename at ship.
+- Anything else covers a refusal, a record carrying no `branch` key, and an installed binary carrying no `plan-branch` subcommand
+- Saying the verb did not answer lets a reader tell a derived name from a fallback one
 
 The dispatch runbook runs the same verb on the same plan to pick the branch its collision check clears, so calling it here is what makes the checked branch and the taken branch one string.
 

package/claude/skills/build-in-slices/references/adopted.md

@@ -5,40 +5,54 @@ description: Which external sources on incremental building this skill adopted,
 
 # Adopted and declined
 
-External sources were read and filtered rather than imported. This file is the record. A later session extending the skill adds to it rather than re-arguing an item already settled here.
+External sources were read and filtered rather than imported. This file is the record, and a later session extending the skill adds to it rather than re-arguing an item settled here.
 
-## Adopted
+## Adopted from the default shelf
 
-### From the default shelf
+### Small changes
 
-**Small changes.** [Small CLs](https://google.github.io/eng-practices/review/developer/small-cls.html), from Google's engineering practices: a change should be self-contained and address one thing, a refactor goes in a change apart from the feature that needs it, and a test goes in the same change as the code it covers. Adopted as the rule that each commit carries one logical change, the refactor excuse row, and the rule that a slice's test never lands after its code.
+[Small CLs](https://google.github.io/eng-practices/review/developer/small-cls.html), from Google's engineering practices, keeps a change self-contained and about one thing, puts a refactor in a change apart from the feature needing it, and puts a test in the same change as its code.
 
-### The increment cycle
+Adopted as the rule that each commit carries one logical change, the refactor excuse row, and the rule that a slice's test never lands after its code.
 
-**Incremental implementation.** Addy Osmani's `agent-skills`, pinned at addyosmani/agent-skills@2686b620, [`skills/incremental-implementation/SKILL.md`](https://github.com/addyosmani/agent-skills/blob/2686b620/skills/incremental-implementation/SKILL.md). Adopted from it:
+## Adopted for the increment cycle
 
-- The increment cycle of implement, test, verify, commit, and next slice, with the commit routed through `git-commit` rather than a message format of its own.
-- Vertical, risk-first, and contract-first slicing, stated as rules for choosing the next slice rather than as worked examples tied to one stack.
-- Rule 1, one thing at a time, as one logical change per commit.
-- Rule 2, keep it compilable, as a build left passing at every commit.
+Addy Osmani's `agent-skills`, pinned at addyosmani/agent-skills@2686b620, [`skills/incremental-implementation/SKILL.md`](https://github.com/addyosmani/agent-skills/blob/2686b620/skills/incremental-implementation/SKILL.md), supplies the cycle and most of the rules.
 
-#### Rollback and the notes
+### The cycle and its rules
 
-- Rule 5, rollback-friendly, as the group on keeping each commit safe to revert and the rule against deleting and replacing in one commit.
-- The "noticed but not touching" list from its scope section, routed to the open task's findings or the handover rather than offered as new tasks, since a worker may not add a row to the board.
-- The note against re-running a command on unchanged code, scoped to a session's own repeats so it never reads as permission to skip a chain's verify step.
-- The rationalizations and red flags that carry across stacks, reworded as reasons this toolkit's sessions give, with one row added for the ship step committing everything anyway.
+The increment cycle of implement, test, verify, commit, and next slice is adopted with the commit routed through `git-commit` rather than a message format of its own.
+
+- Vertical, risk-first, and contract-first slicing, stated as rules for choosing the next slice rather than as worked examples tied to one stack
+- Rule 1, one thing at a time, as one logical change per commit
+- Rule 2, keep it compilable, as a build left passing at every commit
+
+### Rollback and the notes
+
+Rule 5, rollback-friendly, is the group on keeping each commit safe to revert and the rule against deleting and replacing in one commit.
+
+- The "noticed but not touching" list from its scope section, routed to the open task's findings or the handover, since a worker may not add a row to the board
+- The note against re-running a command on unchanged code, scoped to a session's own repeats so it never reads as permission to skip a chain's verify step
+- The rationalizations and red flags that carry across stacks, reworded as this toolkit's sessions give them, plus one row for the ship step committing everything anyway
 
 ## Declined
 
-**Rule 0, simplicity first, and the abstraction red flags.** Declined because `code-craft` owns when an abstraction earns its place and when to write the plainest code that passes. Restating it here would put two owners on one rule.
+Each item below was read and left out, with the reason it changes nothing a session does here.
+
+### Rules another skill owns
+
+**Rule 0, simplicity first, and the abstraction red flags.** `code-craft` owns when an abstraction earns its place and when to write the plainest code that passes, and restating it here would put two owners on one rule.
+
+**Rule 4, safe defaults.** A conservative default is a concern of the interface a caller sees, which belongs to the skill shaping that interface rather than to how the work is sequenced.
+
+### Rules this skill already covers
 
-**The rest of its scope section.** Declined as a scope call this skill makes: its slices already keep to the plan, and minimal edits, no unrequested features, and edits limited to what the user named restate that in different words. Only the noticed list was new.
+**The rest of its scope section.** Its slices already keep to the plan, and minimal edits, no unrequested features, and edits limited to what the user named restate that in different words. Only the noticed list was new.
 
-**Rule 3, feature flags for incomplete features.** Declined because the slices of one branch merge together as one pull request rather than reaching trunk one at a time, so nothing incomplete is exposed between them.
+**Rule 3, feature flags for incomplete features.** The slices of one branch merge together as one pull request rather than reaching trunk one at a time, so nothing incomplete is exposed between them.
 
-**Rule 4, safe defaults.** Declined because a conservative default is a concern of the interface a caller sees, which belongs to the skill shaping that interface rather than to how the work is sequenced.
+### Numbers and commands tied to one stack
 
-**The 100-line threshold.** Its red flag of more than 100 lines written without running tests. Declined because a line count means something different on every stack and a session cannot carry it from one to the next. The red flag is stated as a check instead: a slice implemented whose tests have not run.
+**The 100-line threshold.** Its red flag of more than 100 lines written without running tests means something different on every stack. The red flag is stated as a check instead, being a slice implemented whose tests have not run.
 
-**Its per-stack command lists and its definition-of-done pointer.** Declined because the project's own `CLAUDE.md` names its verify commands, and a body naming runners stops holding on the next stack.
+**Its per-stack command lists and its definition-of-done pointer.** The project's own `CLAUDE.md` names its verify commands, and a body naming runners stops holding on the next stack.

package/claude/skills/canvas-board/references/canvas.md

@@ -25,7 +25,8 @@ The folder is gitignored, so nothing in a repository checks its shape and nothin
 
 Governs the canvas content under `.canon/canvas/`: page folder names, frame files, the `layout.json` shape, how tokens reach a frame, and what a frame must not assume about where it renders.
 
-Also governs the house style of an explanation frame, being a diagram, a board of notes, or a comparison. A mockup of the project's own interface is not an explanation frame, and it follows the project's design document for type, color, and layout.
+- Also governs the house style of an explanation frame, being a diagram, a board of notes, or a comparison
+- A mockup of the project's own interface is not an explanation frame, and follows the project's design document for type, color, and layout
 
 Does not govern:
 
@@ -61,6 +62,8 @@ A canvas failing these is non-conforming even when it satisfies every shape rule
 
 ### Content and edits
 
+A frame is the only copy of its markup, so it carries everything it needs.
+
 - Keep a frame self-contained. Inline its own styles and scripts, or link a file inside the same page folder, since a frame is served from its page and nothing outside the canvas resolves.
 - Use the project's custom properties, `var(--<name>)`, for every value the token stylesheet defines. A literal copied from it shows the right color today and the wrong one after the next token change.
 - Edit a frame by rewriting its file. The file is the frame, and nothing else holds a copy of its markup.
@@ -76,9 +79,12 @@ Applies to an explanation frame only. A mockup of the project's interface render
 
 ### Colors, faces, and fit
 
-- Take colors from the project's custom properties. A frame that defines colors of its own sets the dark values on `:root` and the light ones under `[data-theme="light"]`, since the shell sets `data-theme` on each frame's root.
-- Name only the faces the canvas serves into every frame: `Geist Variable` for text, `Noto Sans Mono` for code, and `Excalifont` for a hand-drawn look. They render the same in a capture and in any browser, so a height fitted against them holds.
-- Make each box tall enough to show all its content, with no scrollbar and no clipped line. Run `canon canvas fit <page>/<frame>` rather than estimating, since it measures the content in the capture browser and sets the height.
+Take colors from the project's custom properties. A frame defining colors of its own sets the dark values on `:root` and the light ones under `[data-theme="light"]`, since the shell sets `data-theme` on each frame's root.
+
+- Name only the faces the canvas serves into every frame, being `Geist Variable` for text, `Noto Sans Mono` for code, and `Excalifont` for a hand-drawn look
+- Those render the same in a capture and in any browser, so a height fitted against them holds
+- Make each box tall enough to show all its content, with no scrollbar and no clipped line
+- Run `canon canvas fit <page>/<frame>` rather than estimating, since it measures the content in the capture browser and sets the height
 - Read frames left to right in reading order. Let `frame add` place each frame after the last with the standard gap, and move one only when the operator asks for a position.
 
 ## Layout
@@ -89,6 +95,8 @@ Applies to an explanation frame only. A mockup of the project's interface render
 
 ### Missing boxes and writes
 
+The layout file is shared state, so a write never discards a box another writer or reader holds.
+
 - Leave a frame out of the layout only when its position does not matter yet. A reader places an unnamed frame in a row after the others, at the default size of 1440 by 900.
 - Never write the file while a writer holds its lock, which is the same name with `.lock` appended. Two writers each replacing the whole file lose one of the two edits.
 - Treat a layout that does not parse as a defect to repair, never as an empty one to overwrite. Writing over it erases every box it held.
@@ -107,7 +115,8 @@ The keys below are the ones a reader parses. The frame names are placeholders.
 ## Tokens
 
 - Expect the token stylesheet first in every frame's `head` when it is served, ahead of anything the frame links. A stylesheet the frame links itself still wins the cascade.
-- Read where the tokens come from in this order: the canvas tool's own module inside its own checkout, else the project's installed base stylesheet plus anything in its project override folder, else none. A canvas with no token source renders unstyled and says so.
+- Read the tokens from the canvas tool's own module inside its own checkout, else the project's installed base stylesheet plus its project override folder, else none
+- A canvas with no token source renders unstyled and says so
 - Never paste the token stylesheet into a frame. The injected copy follows the project, and a pasted one stops following it the moment it is written.
 
 ## What a frame must not assume
@@ -118,7 +127,9 @@ The keys below are the ones a reader parses. The frame names are placeholders.
 
 ### Font, source, and checkout
 
-- Do not assume a default font. Set `font-family` with a served face first on an element the frame's text inherits from, since a capture checks the first family of the text it renders and the browser's default serif is absent from many machines. A frame naming a machine family such as `DejaVu Sans` renders at another height in another browser, which `canon canvas fit` reports.
+Do not assume a default font. Set `font-family` with a served face first on an element the frame's text inherits from, since a capture checks the first family of the text it renders and the browser's default serif is absent from many machines.
+
+- A frame naming a machine family such as `DejaVu Sans` renders at another height in another browser, which `canon canvas fit` reports
 - Do not assume the frame is the source. A picked direction is carried into the project's design document or a plan, and the operator clears the frame once it has been carried.
 - Do not assume the canvas survives the checkout. The folder is gitignored, so a lost checkout loses every page in it.
 

package/claude/skills/canvas-board/references/design.md

@@ -30,8 +30,8 @@ Does not govern:
 
 ## Two shapes
 
-- **An intent record** is the shape a project writes by hand. It carries rules, omissions, and each role's intent, and its lead names the stylesheet the values live in. It carries no value, since a hand-typed copy of the stylesheet drifts from it.
-- **A values record** is generated from a token source and carries the value tables beside the rules. It is never edited by hand, and its lead names the module it is rendered from. The toolkit's own record is one.
+- **An intent record** is the shape a project writes by hand, carrying rules, omissions, and each role's intent, with a lead naming the stylesheet. It carries no value, since a hand-typed copy drifts.
+- **A values record** is generated from a token source and carries value tables beside the rules. Never hand-edited, its lead names the module it renders from. The toolkit's own record is one.
 
 Everything below applies to both shapes unless it names one.
 
@@ -68,24 +68,43 @@ Headings and table rows are never counted, and a section holding a table and no
 
 ## Sections
 
-Use `## Overview`, `## Colors`, `## Typography`, `## Spacing`, `## Shapes`, `## Motion`, and `## Iconography`, in that order, which follows Google's DESIGN.md for the sections the two share. An optional `## Layout` sits between Spacing and Shapes. The parser still reads a record written under the earlier names, `## Personality`, `## Color`, and `## Borders`, as the sections they became.
+Use `## Overview`, `## Colors`, `## Typography`, `## Spacing`, `## Shapes`, `## Motion`, and `## Iconography`, in that order, which follows Google's DESIGN.md for the sections the two share.
+
+- An optional `## Layout` sits between Spacing and Shapes
+- The parser still reads the earlier names `## Personality`, `## Color`, and `## Borders` as the sections they became
 
 In an intent record, `## Colors` carries a `Role | Property | Intent` table and `## Shapes` a `Role | Property | When used` table. Each row names the custom property the stylesheet declares for that role, such as `--color-accent`. Typography and Spacing carry rules alone.
 
 Add either optional section when the project has content for it:
 
-- `## Layout`: page width, breakpoints, and grid rules, as current constraints. The surface-capture rule reads the breakpoints from here, so a project with none declared here is captured at the 320 reflow floor alone.
+- `## Layout`: page width, breakpoints, and grid rules as current constraints. The surface-capture rule reads breakpoints here, so a project declaring none is captured at the 320 reflow floor alone.
 - `## Mark`: the logo's construction rules and the files that carry it
 
 ## The uncertainty tag
 
 Applies to a values record alone. An intent record carries no value to tag, and a guessed value is marked where it is written, in the stylesheet.
 
-A cell no source anchors ends in ` ? verify`, written inside the cell rather than as a trailing column, since a trailing marker breaks the table parse. A cell wrapping itself in a code span carries the tag inside the span, as in `` `#ffffff ? verify` ``. Both spellings parse.
+### Writing the tag
+
+A cell no source anchors ends in ` ? verify`, written inside the cell rather than as a trailing column, since a trailing marker breaks the table parse. A cell wrapping itself in a code span carries the tag inside the span, as in `` `#ffffff ? verify` ``, and both spellings parse.
+
+- The renderer splits the tag off the value, so a swatch and a font sample are built from the value alone and the marker shows beside it
+- The preview reports anchored cells against tagged ones, which is where a reviewer reads the record's overall confidence
+
+### Which columns count
+
+The table fixes which columns the ratio reads, not the record. The first column names its row, and `Multiplier` and `When used` restate what the row carries, so no source could anchor them and none is counted.
+
+| Section    | Counted columns                           |
+| ---------- | ----------------------------------------- |
+| Colors     | `Intent`, `Value`                         |
+| Typography | `Family`, `Weight`, `Size`, `Line height` |
+| Spacing    | `Value`                                   |
+| Shapes     | `Radius`, `Width`                         |
 
-The renderer splits the tag off the value, so a swatch and a font sample are built from the value alone and the marker shows beside it. The preview also reports how many cells are anchored against how many are tagged, which is the reading a reviewer takes the record's overall confidence from.
+A cell tagged outside that set counts anyway, so a marker the preview draws is never missing from the ratio beside it.
 
-Which columns that ratio reads is fixed by the table rather than by the record. The first column of each table names its row, and `Multiplier` and `When used` restate what the row already carries, so none of them is something a source could anchor and none is counted. That leaves `Intent` and `Value` in Colors, `Family`, `Weight`, `Size`, and `Line height` in Typography, `Value` in Spacing, and `Radius` and `Width` in Shapes. A cell tagged outside that set counts anyway, so a marker the preview draws is never missing from the ratio beside it.
+### Prose sections
 
 A prose section takes its uncertainty inline instead, in a sentence saying what is proposed and what has yet to confirm it. A tag appended to a paragraph renders verbatim.
 

package/claude/skills/ci-workflow/REQUIREMENT.md

@@ -21,7 +21,8 @@ A cache keyed on a static string serves a stale browser or toolchain after a ver
 - Start the checks that share setup in one job and split them only once a run log puts the gate past roughly two minutes
 - Pin every action to a tag that cannot cross a major version
 - Key a cache on the version string of the thing it caches
-- Give every workflow a manual trigger beside its primary one
+- Give every workflow a manual trigger beside its primary one, except one that commits back, where a manual run has no branch to land on
+- Default the token to read-only and grant a write scope only on the job that needs it
 - Bound artifact upload to failures and set an expiry on it
 
 ## Must not