@erclx/canon 5.38.0 → 5.40.0

package/claude/skills/git-issue/SKILL.md

@@ -33,6 +33,8 @@ Then gather repo context in parallel:
 
 ### Preview
 
+Output the preview first.
+
 - **Title:** `<type>: <subject>`
 - **Label:** <bug or enhancement>
 - **Analysis:** <one line on what the issue captures>
@@ -41,9 +43,10 @@ After outputting the preview, execute the final command immediately. Claude Code
 
 ### Pre-publish scan
 
-Before running the final command, run the scan in `${CLAUDE_SKILL_DIR}/../git-pr/references/publish.md` against the title and body. The title and body go straight to the remote with nothing checking them on the way, so this scan is the only gate. It covers the phase-label check as well as the characters, since both go to a reader who has no task board. It applies on top of the banned phrases in `${CLAUDE_SKILL_DIR}/references/issue.md`.
+Before running the final command, run the scan in `${CLAUDE_SKILL_DIR}/../git-pr/references/publish.md` against the title and body, on top of the banned phrases in `${CLAUDE_SKILL_DIR}/references/issue.md`.
 
-The `pull_request` check the git-pr surface carries reads a pull request's own title and body alone, so an issue reaches no check behind this scan either.
+- The title and body go straight to the remote, and the `pull_request` check reads a pull request alone, so this scan is the only gate
+- It covers the phase-label check as well as the characters, since both reach a reader who has no task board
 
 ### Final command
 
@@ -60,8 +63,6 @@ rm -rf .canon/tmp/issue
 
 ## After execution
 
-Respond with exactly one line:
+Respond with exactly one line and add no other text:
 
 `✅ Issue: <url>`
-
-Do not add any other text.

package/claude/skills/git-pr/SKILL.md

@@ -39,18 +39,20 @@ Then run these commands in parallel to gather git context:
 
 ## Diff baseline
 
-Prefer `origin/main` over local `main`. Both reads resolve against `<base>`, so the commits listed and the changes described come from one scope. Never read a two-dot range against local `main` for either half: it resolves no merge base, so once local `main` moves, the diff reports its newer commits as reversed changes and the log lists commits already on the remote.
+Prefer `origin/main` over local `main`. Both reads resolve against `<base>`, so the commits listed and the changes described come from one scope.
 
-The baseline is unusable in two cases:
+Never read a two-dot range against local `main` for either half. It resolves no merge base, so once local `main` moves, the diff reports its newer commits as reversed changes and the log lists commits already on the remote.
+
+### Unusable baseline
+
+The baseline is unusable in two cases, and the no-commits guard below catches both, so stop there rather than describing an empty diff:
 
 - No merge base resolves against either ref.
 - The base equals HEAD, whichever ref resolved it. Nothing is committed ahead of the base to compare against.
 
-Either case leaves both reads empty, which the no-commits guard below catches. Stop there rather than composing a description from an empty diff.
-
 ## Guards
 
-- If branch name does not match `<type>/<description>` format (valid types are defined in `${CLAUDE_SKILL_DIR}/../git-branch/references/branch.md`), stop and output:
+- If the branch name does not match `<type>/<description>`, with the types `branch.md` defines, stop and output:
   `❌ Branch name does not follow conventions. Run /git-branch to rename first.`
 - If no commits ahead of main, stop and output:
   `❌ No commits ahead of main. Nothing to PR.`
@@ -59,6 +61,8 @@ Either case leaves both reads empty, which the no-commits guard below catches. S
 
 ### Preview
 
+Output the preview first.
+
 - **Title:** <title>
 - **Files changed:** <count>
 - **Analysis:** <brief summary of impact>
@@ -73,9 +77,12 @@ Leave a box unchecked only for the human-only cases the reference defines, and n
 
 ### Pre-publish scan
 
-Before running the final command, run the scan in `${CLAUDE_SKILL_DIR}/references/publish.md` against the PR title and body. The title and body go straight to the remote with nothing checking them on the way, so run the scan regardless of what backs it downstream. It covers the phase-label check as well as the characters, since both go to a reader who has no task board. It applies on top of the banned phrases in `${CLAUDE_SKILL_DIR}/references/pr.md`.
+Before running the final command, run the scan in `${CLAUDE_SKILL_DIR}/references/publish.md` against the PR title and body, on top of the banned phrases in `${CLAUDE_SKILL_DIR}/references/pr.md`. The title and body go straight to the remote, so run it whatever backs it downstream.
+
+- It covers the phase-label check as well as the characters, since both reach a reader who has no task board
+- It stays required where a `pull_request` job runs the same verb, since an older `canon` carries no such job and none of the newer keys
 
-Write the body here, ahead of the final command, since the scan below needs a file to read it from:
+Write the body here, ahead of the final command, since the scan needs a file to read it from:
 
 ```bash
 mkdir -p .canon/tmp/pr
@@ -90,70 +97,75 @@ Then run:
 canon labels scan --title "<title>" --body-file .canon/tmp/pr/body.md --json
 ```
 
-Branch on the JSON record rather than the exit code. An operator's shell can wrap `canon` in a function whose status comes from a trailing command, flattening a non-zero exit to 0, the same reason the labels step below branches on its own record rather than the exit.
+### Reading the scan
+
+Branch on the JSON record rather than the exit code, since a shell function wrapping `canon` can flatten a non-zero exit to 0. Stop and fix the title or body on any key below, and do not proceed to `### Final command` until a re-run comes back clean on all six.
 
-Stop and fix the title or body on a non-empty `phaseLabels`, `boardReferences`, `sessionLinks`, `titleFormatIssues`, `bannedCharacters`, or a `sections` record with anything in `outside` or `missing`. Do not proceed to `### Final command` until a re-run comes back clean on all six. `titleFormatIssues` names which `## Title` rule in `${CLAUDE_SKILL_DIR}/references/pr.md` the title breaks, structure, casing, or length, so fix the named rule rather than guessing. `sections.outside` lists each heading to rename or drop, `sections.missing` each required heading to add, and `bannedCharacters` names the character to restructure the sentence around. Leave `cutsRelease` and `semverTags` alone, since a release-please pull request legitimately carries version references its own fixed shape explains.
+| Key                 | Fix                                                                                  |
+| ------------------- | ------------------------------------------------------------------------------------ |
+| `phaseLabels`       | Remove the phase label                                                               |
+| `boardReferences`   | Remove the board reference                                                           |
+| `sessionLinks`      | Remove the session link                                                              |
+| `titleFormatIssues` | Fix the `## Title` rule in `pr.md` it names, being structure, casing, or length      |
+| `bannedCharacters`  | Restructure the sentence around the named character                                  |
+| `sections`          | Rename or drop each heading in `outside`, and add each required heading in `missing` |
 
-The scan stays required even where a `pull_request` workflow job runs the same verb, since a project holding an older `canon` carries no such job and no `titleFormatIssues`, `sections`, or `bannedCharacters` key.
+Leave `cutsRelease` and `semverTags` alone, since a release-please pull request legitimately carries version references its own fixed shape explains.
 
 ### Resolving the pull request
 
 The run resolves the pull request once, in the final command below, and every later step reads what that command printed. Nothing else looks the number up again.
 
-Never detect by head branch alone. A lookup that ignores state returns the closed pull request a reused branch name left behind, and the run rewrites it. Scoping the lookup to `state=open` returns empty there and sends the run down the create path.
-
-The lookup scopes to the base as well as the head. One head can carry open pull requests against two bases, and a lookup reading the first result would pick between them by list order. Resolving the base from the repository's default branch is what makes the detection and the create agree on which pull request the run is about.
-
-Every call goes through `gh api` against the REST endpoints rather than through `gh pr` or `gh repo view`, which run on GraphQL. A cloud session's GitHub access blocks GraphQL and serves REST, so the same block converges on a laptop and on a cloud VM.
+- Never detect by head branch alone. A lookup ignoring state returns the closed pull request a reused branch name left behind, so scope it to `state=open`.
+- Scope the lookup to the base as well as the head, resolved from the default branch, so detection and create agree on one pull request. A head can carry two bases.
+- Call `gh api` against REST rather than `gh pr` or `gh repo view`, which run on GraphQL. A cloud session's GitHub access blocks GraphQL and serves REST.
 
 A detached HEAD gives `git branch --show-current` an empty result, which would read as no open pull request and create a second one. The branch-name guard above stops the run first, since an empty name does not match `<type>/<description>`.
 
 ### Labels
 
-Read `${CLAUDE_SKILL_DIR}/references/labels.md` on reaching this step, starting at its `## Labels at run time` section, for the verb to ask, the record to branch on, the fallback, and when `pr_labels` stays empty. The final command below takes the set it resolves as `pr_labels` and the record's `uncovered` paths as `pr_uncovered`, which only its fallback path reads.
+Read `${CLAUDE_SKILL_DIR}/references/labels.md` on reaching this step, starting at its `## Labels at run time` section, for the verb to ask, the record to branch on, the fallback, and when `pr_labels` stays empty.
 
-### Final command
+The final command takes the resolved set as `pr_labels` and the record's `uncovered` paths as `pr_uncovered`, which only its fallback path reads.
 
-Read `${CLAUDE_SKILL_DIR}/references/final-command.md` on reaching this step for the one command that pushes, finds or creates the pull request over REST, re-scans its live body for a session link, applies the labels through `canon labels apply`, and prints `number=`, `url=`, `head=`, `owed=`, `missingOnRemote=`, and `uncovered=`, and for the check binding every write to this branch's pull request.
-
-### Post the rendered-surface evidence
-
-Run this step on every pull request this skill opens or edits. Read `${CLAUDE_SKILL_DIR}/references/evidence.md` for finding the checklist and the local server, posting the evidence comparison, posting the checklist alone, and posting the preview address, each against the `<number>` the final command printed. Never judge from the diff whether an evidence image changed, since the verb answers `no-evidence` for a branch that changed none and a session cannot see an image it did not author.
-
-### Record the number on the task
-
-Write the `number` the final command printed onto the task the branch is closing, through `canon tasks pull-request`, and never resolve it again. Read `${CLAUDE_SKILL_DIR}/references/task-number.md` on reaching this step for which task it names, the invocation, the refusals it skips silently, and why the number lands here. Skip it when the final command refused on a head mismatch and printed no number.
-
-## After execution
+### Final command
 
-Respond with one line, using the `url` the final command printed:
+Read `${CLAUDE_SKILL_DIR}/references/final-command.md` on reaching this step, for the one command that pushes and finds or creates the pull request over REST, and for the check binding every write to this branch's pull request.
 
-`✅ PR: <url>`
+That command re-scans the live body for a session link, applies the labels through `canon labels apply`, and prints `number=`, `url=`, `head=`, `owed=`, `missingOnRemote=`, and `uncovered=`.
 
-Add a line for each path in the `uncovered=` value the final command printed, naming the path and the map it belongs in:
+### Post the rendered-surface evidence
 
-`⚠️ No label covers <path>. Add a row to canon/config/pr-labels.toml or a [declined] entry.`
+Run this step on every pull request this skill opens or edits. Read `${CLAUDE_SKILL_DIR}/references/evidence.md` for finding the checklist and the local server and for posting the evidence comparison, the checklist alone, and the preview address, each against the `<number>` the final command printed.
 
-Add a further line only when `owed=` or `missingOnRemote=` printed a value, naming each owed label, `owed=` less the names in `missingOnRemote=`, and separately the names in `missingOnRemote=`, since `owed=` already holds every absent label. Drop either half that is empty:
+Never judge from the diff whether an evidence image changed, since the verb answers `no-evidence` for a branch that changed none and a session cannot see an image it did not author.
 
-`⚠️ Labels not applied: <owed labels not in missingOnRemote>. Not on the remote: <missingOnRemote labels>.`
+### Record the number on the task
 
-Add a line when a checklist was posted, naming the pull request it landed on and which comment carries it:
+Write the `number` the final command printed onto the task the branch is closing, through `canon tasks pull-request`, and never resolve it again. Skip it when the final command refused on a head mismatch and printed no number.
 
-`📋 Posted the UI checklist to <number>, in the evidence comment.`
+Read `${CLAUDE_SKILL_DIR}/references/task-number.md` on reaching this step for which task it names, the invocation, the refusals it skips silently, and why the number lands here.
 
-`📋 Posted the UI checklist to <number>, on its own.`
+## After execution
 
-Add a line when the preview step returned an address:
+Respond with `✅ PR: <url>`, using the `url` the final command printed, then add only the lines below whose condition holds. Add no other text.
 
-`🔗 Preview: <url>`
+| Condition                                                 | Line                                                                                                        |
+| --------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
+| Each path in `uncovered=`                                 | `⚠️ No label covers <path>. Add a row to canon/config/pr-labels.toml or a [declined] entry.`                |
+| `owed=` or `missingOnRemote=` printed a value             | `⚠️ Labels not applied: <owed labels not in missingOnRemote>. Not on the remote: <missingOnRemote labels>.` |
+| A checklist posted in the evidence comment                | `📋 Posted the UI checklist to <number>, in the evidence comment.`                                          |
+| A checklist posted alone                                  | `📋 Posted the UI checklist to <number>, on its own.`                                                       |
+| The preview step returned an address                      | `🔗 Preview: <url>`                                                                                         |
+| The evidence step posted the local link                   | `🖥️ Local preview: <url>`                                                                                   |
+| The local step refused and evidence or a checklist posted | `🖥️ No local preview: <reason>`                                                                             |
 
-Add a line when the evidence step posted the local link:
+### The labels line
 
-`🖥️ Local preview: <url>`
+`owed=` already holds every absent label, so the first half names `owed=` less the names in `missingOnRemote=`, and the second names `missingOnRemote=` alone. Drop either half that is empty.
 
-Add a line instead when the local step refused as `no-server` or `no-listener-reader` and the evidence or checklist step posted something, since that pull request changes a rendered surface and a reviewer could have used the link. To add it later, start the server, run `canon pr local --json`, then run `canon pr evidence <number> --local <url> --json`, adding `--checklist` when one is still owed, and post the body the way the evidence step does. `git-followup` only carries a line forward, so it cannot add one the comment never had:
+### The no-local-preview line
 
-`🖥️ No local preview: <reason>`
+It fires when the local step refused as `no-server` or `no-listener-reader`, since that pull request changes a rendered surface and a reviewer could have used the link. `git-followup` only carries a line forward, so it cannot add one the comment never had.
 
-Do not add any other text.
+To add the link later, start the server and run `canon pr local --json`, then `canon pr evidence <number> --local <url> --json`, adding `--checklist` when one is still owed. Post the body the way the evidence step does.

package/claude/skills/git-pr/references/evidence.md

@@ -31,7 +31,7 @@ A reviewer on the operator's machine can open the branch's running dev server, w
 canon pr local --json
 ```
 
-The verb reads the listening sockets on this machine, keeps those whose process runs inside this worktree, and reports the lowest port serving an HTML page. A server in another worktree or in the main checkout is never reported, since it shows a different branch. `canon docs pr-local` states the contract. Read `reason` on the record rather than the exit code.
+The verb reads the listening sockets on this machine, keeps those whose process runs inside this worktree, and reports the lowest port serving an HTML page. A server in another worktree or in the main checkout is never reported, since it shows a different branch. `canon pr local --help` states the contract. Read `reason` on the record rather than the exit code.
 
 - `ok`: hold the record's `url` for the evidence step below.
 - `no-server` or `no-listener-reader`: hold the reason for the closing report, pass no link, and move on. Do not start a server here, since one started inside the ship chain has no owner to stop it.
@@ -110,7 +110,7 @@ The evidence comment is already posted, so the reviewer has the screenshots whil
 canon pr preview <number> --json
 ```
 
-The verb dispatches the project's Pages deploy on the pull request's branch and waits on the run for up to 15 minutes. It refuses before dispatching anything when the deploy command passes no `--branch`, since that deploy would publish the branch to production, and when the workflow's own push path filter matches no path the pull request changed, since a dispatch ignores that filter and the site it published would show none of the change. `canon docs pr-preview` states the contract. Read `reason` on the record rather than the exit code.
+The verb dispatches the project's Pages deploy on the pull request's branch and waits on the run for up to 15 minutes. It refuses before dispatching anything when the deploy command passes no `--branch`, since that deploy would publish the branch to production, and when the workflow's own push path filter matches no path the pull request changed, since a dispatch ignores that filter and the site it published would show none of the change. `canon pr preview --help` states the contract. Read `reason` on the record rather than the exit code.
 
 - `ok`: re-render the evidence body with the address on the line under `## Evidence`, then post or update it exactly as the evidence step does, through the same tmp file and the `commentId` the record carries:
 

package/claude/skills/git-pr/references/final-command.md

@@ -54,7 +54,7 @@ case "$links" in
   printf 'Removed %s session link(s) from the live body of #%s.\n' "$links" "$pr_number" >&2
   ;;
 esac
-record=$(canon labels apply "$pr_number" --base "$base_branch" --json 2>/dev/null | tail -n 1)
+record=$(canon labels apply "$pr_number" --json 2>/dev/null | tail -n 1)
 if printf '%s' "$record" | jq -e 'has("earned")' >/dev/null 2>&1; then
   owed=$(printf '%s' "$record" | jq -r '.owed | join(",")')
   missing=$(printf '%s' "$record" | jq -r '.missingOnRemote | join(",")')

package/claude/skills/git-pr/references/labels.md

@@ -82,7 +82,7 @@ What it leaves unmeasured is a prefix reaching no path, so a row left behind by
 
 Apply labels after the pull request resolves, never as a field on the create. A create carrying a label the remote lacks either fails whole or creates the label, depending on the surface, and neither is the map's call. One step against a pull request that already exists covers the create and the edit path alike. It runs over REST, so it works where GraphQL is blocked, and the REST endpoint creates any label it is handed that the remote lacks, so the step reads each name off the remote first and warns on a missing one rather than adding it.
 
-`canon labels apply <number>` is that step. It resolves the earned set the way `canon labels audit` does, binds to the pull request only when its head is the current branch and it is open, and adds each earned label the pull request lacks. `--check` reports what is owed and writes nothing. The record carries `number`, `earned`, `present`, `added`, `owed`, `missingOnRemote`, and `uncovered`.
+`canon labels apply <number>` is that step. It resolves the earned set from the pull request's own files listing, or from the git range when `--base` is passed, binds to the pull request only when its head is the current branch and it is open, and adds each earned label the pull request lacks. `--check` reports what is owed and writes nothing. The record carries `number`, `earned`, `present`, `added`, `owed`, `missingOnRemote`, and `uncovered`.
 
 A pull request opened outside this skill, such as by `gh pr create`, takes the same command, since nothing else labels it.
 

package/claude/skills/git-pr/references/publish.md

@@ -44,7 +44,7 @@ A phase label is one way text names the board, and a path under a record root is
 
 Two shapes get past a reader scanning for a bare label. A code span quoting a label is still the label, so read a span whose whole content is one as a hit and leave a longer token inside a span alone, which is a fixture name rather than a reference. The second shape is a path under a record root, gitignored and therefore absent from every clone, so `.canon/feedback/` names a folder the remote's reader cannot open.
 
-Under the tracked `canon/` and `.claude/` folders there is no hit, since `canon/context/governance/rules.md` resolves everywhere. `.canon/` carries no such carve-out: one ignore line covers the root whole, so every path beneath it is a hit regardless of which folder names it.
+Under the tracked `canon/` and `.claude/` folders there is no hit, since `canon/context/surfaces/governance.md` resolves everywhere. `.canon/` carries no such carve-out: one ignore line covers the root whole, so every path beneath it is a hit regardless of which folder names it.
 
 Rewrite a hit to name what the reader can reach rather than deleting it. A row's subject stated plainly replaces its label, and what a record folder holds, said in a sentence, replaces its path.
 

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

@@ -9,15 +9,19 @@ metadata:
 
 Run the full post-feature workflow by invoking each skill in sequence using the Skill tool. After each skill returns, invoke the next step immediately in the same response.
 
-Do not output any text between steps and do not wait for user input. Tool permission dialogs are the only interrupts allowed. The final output is `✅ Shipped`, emitted on the wake after the step 9 watch exits on `passing` rather than when the turn ends on the watch line, unless a wrapping caller states it closes on its own block, which `auto-ship` does.
+Do not output any text between steps and do not wait for user input. Tool permission dialogs are the only interrupts allowed. The final output is `✅ Shipped`, emitted on the wake after the step 9 watch exits on `passing`, unless a wrapping caller such as `auto-ship` closes on its own block.
 
 ## Verify
 
-Run the verify commands `CLAUDE.md` names (lint, typecheck, tests) before the sequence starts. On a failure, stop: `❌ Verify failed. Fix the reported errors and run /git-ship again.` Make no fix attempt. This skill is the resume point after a stop, so the fix is the one the user is already making.
+Run the verify commands `CLAUDE.md` names (lint, typecheck, tests) before the sequence starts. On a failure, stop: `❌ Verify failed. Fix the reported errors and run /git-ship again.` Make no fix attempt, since this skill is the resume point and the user is already making the fix.
 
 When `CLAUDE.md` names no verify command, say so on one line and continue. A project with no suite is not a project with a failing one.
 
-Verify runs ahead of the sync skills so a stop leaves the tree exactly as the user left it. Re-running a suite the caller already ran costs one command, and the path it closes is the one that has no other guard: `auto-ship` verifies at its own Step 3 and then hands three of its stop points straight back here, so a fix made by hand after one of those stops otherwise reaches the remote with nothing re-run.
+### Why verify runs first
+
+Verify runs ahead of the sync skills so a stop leaves the tree exactly as the user left it. Re-running a suite the caller already ran costs one command.
+
+The path it closes has no other guard. `auto-ship` verifies at its own Step 3 and hands three of its stop points back here, so a hand fix after one of those would otherwise reach the remote with nothing re-run.
 
 ## Pre-check
 
@@ -29,60 +33,65 @@ Run `git diff --cached --name-only 2>/dev/null` to check for staged files. If ou
 2. Invoke `canon:task-complete` to mark the outcomes the diff shipped
 3. Invoke `canon:docs-sync` to sync public docs against changes since main
 4. Run `git add -A` to stage any files the sync skills wrote
-5. Run `canon tasks plan-reach <plan> --json` and report both lists it carries. Name the plan this branch built under, by path or by slug. Read `claimed` first and say who holds each path, since that is the half a reader acts on, then say how many of the changed paths `undeclared` names. Branch on the record rather than on the exit code, which a shell function wrapping `canon` can flatten to zero. This step reports and never stops the sequence.
-6. Invoke `canon:git-stage` to group staged changes and commit by concern, only when `git diff --cached --name-only` prints a path. When it prints nothing, the work already reached history in slices, so continue to step 7.
+5. Run `canon tasks plan-reach <plan> --json`, naming this branch's plan by path or slug, and report both lists per `### Reading the reach` below. This step never stops the sequence.
+6. Invoke `canon:git-stage` to commit by concern, only when `git diff --cached --name-only` prints a path. When it prints nothing, the work already reached history in slices, so continue.
 7. Invoke `canon:git-branch` to rename branch to match conventional format
 8. Invoke `canon:git-pr` to push branch and open pull request
 9. After the PR opens, watch CI in the background, so the session stays reachable while CI runs. Read `### Watching CI` below for the commands and the wake.
 
-A caller wrapping this sequence may act between step 8 and step 9, which is the one gap the order leaves open, since the pull request exists there and nothing has read its checks yet. `auto-ship` marks the pull request draft in it. Nothing else may go there, and a caller that needs a step anywhere else in the sequence is asking for a change to this body rather than for a place to stand.
+A caller wrapping this sequence may act between step 8 and step 9, the one gap the order leaves open, since the pull request exists and nothing has read its checks. `auto-ship` marks the pull request draft there. A caller needing a step anywhere else is asking for a change to this body.
 
-### Watching CI
+### Reading the reach
 
-Run `canon pr checks <number> --json` once in the foreground. When no record comes back at all, the target's CLI predates the verb, and the watch command is `gh pr checks <number> --watch`. The loop below would never exit on such a target, since an empty read never satisfies its test.
+Read `claimed` first and say who holds each path, since that is the half a reader acts on, then say how many changed paths `undeclared` names. Branch on the record rather than the exit code, which a shell function wrapping `canon` can flatten to zero.
 
-Otherwise start this loop through the Bash tool with `run_in_background` and a 60-minute timeout:
+### Why the reach reads at step 5
 
-```bash
-until canon pr checks <number> --json | jq -e '.state != "pending" or .conflicted == true' >/dev/null; do sleep 30; done; canon pr checks <number> --json
-```
+The branch is whole at step 5 and nowhere earlier. Steps 1 and 3 write past what the plan declared, and no pull request exists to carry the answer until step 8.
 
-Emit `⏳ Watching CI on #<number> in the background` and end the turn. Print nothing more while the watch runs. The session wakes when the command exits, and the wake resumes this step rather than restarting the sequence at step 1. A wake that lands while the session is inside another skill, such as a `review-address` pass a message started during the watch, goes to whichever step is waiting on CI.
+It reports rather than acts because every crossing measured on the wave it was filed against merged clean. The undeclared list runs long enough on an ordinary branch that a gate would fire on nearly every ship.
 
-On the wake, branch on the final record's fields rather than on the exit:
+### When the verb is absent
 
-- `state: passing`: read the evidence thread under `### Settling the evidence thread` below, then continue to After completion on `settled`.
-- `state: failing`: stop the sequence and report the failing check with its URL.
-- `conflicted: true`: stop the sequence and report that the branch conflicts with its base, since no run will start for it. A rebase is the repair.
+An installed binary carrying no `plan-reach` subcommand reports the reach unread rather than clear. Say that, and continue.
 
-#### Refused and unsettled reads
+The verb ships with the CLI and this body with the plugin, so an older binary meets a missing subcommand. Reading that absence as clean would report the check passing on every branch that never ran it.
 
-- A `reason` and no `state`: the read was refused, such as `no-remote-branch` for a branch deleted on the remote. Stop and report that `reason`. A missing `state` is never a pass.
-- The command hit its timeout and printed no final record: report CI unsettled after 60 minutes, and emit no `✅ Shipped`.
-- The `gh pr checks --watch` fallback ran, which prints a check table rather than a record. Only a printed table carrying at least one check, every one passing, continues to After completion. Any failing check stops the sequence naming it with its URL. Empty or errored output stops the sequence and reports the message, since `no checks reported on the '<branch>' branch` is what a conflicted branch prints, and that fallback has no `conflicted` field to separate it from lag.
+### Watching CI
 
-Do not auto-fix any of these. The watch line and a stop report from any branch above are the two exceptions to the no-text-between-steps rule.
+Run `canon pr checks <number> --json` once in the foreground. When no record comes back at all, the CLI predates the verb, so read `${CLAUDE_SKILL_DIR}/references/ci-watch.md` for the fallback watch. Otherwise start this loop through the Bash tool with `run_in_background` and a 60-minute timeout:
 
-### Settling the evidence thread
+```bash
+until canon pr checks <number> --json | jq -e '.state != "pending" or .conflicted == true' >/dev/null; do sleep 30; done; canon pr checks <number> --json
+```
 
-On a `passing` wake, run `canon pr evidence <number> --check --json` against the number step 8 returned. It reads the pull request's comments and edits none, so the comment a reviewer already ticked stays as it is. Branch on `reason` and `owed` rather than the exit.
+Emit `⏳ Watching CI on #<number> in the background` and end the turn, printing nothing more while the watch runs. The wake resumes this step rather than restarting at step 1, and a wake landing inside another skill, such as a `review-address` pass, goes to whichever step is waiting on CI.
 
-- `settled`: nothing is owed, which is also what a branch that changed no rendered surface reads. Continue to After completion.
-- `owed`: run each step the record's `owed` list names, from `canon:git-pr`'s `references/evidence.md`, evidence first and then preview. Re-read once with the same command. Continue to After completion only on `settled`. Any other reading stops the sequence and reports the `reason` with the `owed` list, and the sequence never loops back for a second pass. A preview step that refuses, or a deploy that failed, leaves `preview` owed on the re-read, so that is the stop and not a retry.
-- Any other `reason`, such as `gh-failed`: the thread went unread. Stop and report the `reason`, since an unread thread is not a settled one.
-- No record at all, or an unknown flag error: the installed binary predates `--check`. Report the thread unread rather than settled, and continue to After completion without emitting a claim that it was checked.
+### Reading the wake
 
-The read is a closing step and the draft mark stays the only thing between steps 8 and 9. A caller that closes on its own block, as `auto-ship` does, waits on the same CI wake, so the read lands here and not in that body.
+Branch on the final record's fields rather than on the exit. Do not auto-fix any reading, and the watch line and a stop report are the two exceptions to the no-text-between-steps rule.
 
-### Why the reach reads at step 5
+| Record                                  | Route                                                                                 |
+| --------------------------------------- | ------------------------------------------------------------------------------------- |
+| `state: passing`                        | Settle the evidence thread below, then continue to After completion on `settled`      |
+| `state: failing`                        | Stop the sequence and report the failing check with its URL                           |
+| `conflicted: true`                      | Stop and report the branch conflicts with its base, since no run will start. Rebase.  |
+| A `reason` and no `state`, or a timeout | Read `${CLAUDE_SKILL_DIR}/references/ci-watch.md` for the refused and unsettled reads |
+
+### Settling the evidence thread
 
-The branch is whole there and nowhere earlier. Steps 1 and 3 write past whatever the plan declared, so a reading taken ahead of them misses the chain's own additions, and no pull request exists until step 8 to carry the answer anywhere.
+On a `passing` wake, run `canon pr evidence <number> --check --json` against the number step 8 returned. It reads the comments and edits none, so a comment a reviewer ticked stays as it is. Branch on `reason` and `owed` rather than the exit.
 
-It is the one step here that reports rather than acts, which is why it never stops the sequence. Every crossing measured on the wave it was filed against merged clean, and the undeclared list runs long enough on an ordinary branch that a gate would fire on nearly every ship.
+| Reading                                 | Route                                                                                                   |
+| --------------------------------------- | ------------------------------------------------------------------------------------------------------- |
+| `settled`                               | Nothing is owed, as on a branch that changed no rendered surface, so continue                           |
+| `owed`                                  | Run each step the `owed` list names, then re-read once, as below                                        |
+| Any other `reason`, such as `gh-failed` | Stop and report it, since an unread thread is not a settled one                                         |
+| No record, or an unknown flag error     | The binary predates `--check`, so report the thread unread and continue without claiming it was checked |
 
-### When the verb is absent
+On `owed`, run the named steps from `canon:git-pr`'s `references/evidence.md`, evidence first and then preview, and re-read with the same command. Continue only on `settled`, and stop on any other reading with the `reason` and the `owed` list, never looping back.
 
-An installed binary carrying no `plan-reach` subcommand reports the reach unread rather than clear. Say that, and continue. The verb ships with the CLI and this body ships with the plugin, so a target on an older binary meets a missing subcommand, and a body reading that absence as a clean answer would report the check passing on every branch that never ran it.
+A refused preview step or a failed deploy leaves `preview` owed on the re-read, so that is the stop and not a retry. The read is a closing step, so the draft mark stays the only thing between steps 8 and 9, and a caller closing on its own block waits on the same wake.
 
 ## After completion
 

package/claude/skills/git-ship/references/ci-watch.md

@@ -0,0 +1,31 @@
+---
+title: CI watch fallback and refusals
+description: What the git-ship CI watch does when the installed CLI predates the checks verb, when a read is refused, and when the watch times out
+---
+
+# CI watch fallback and refusals
+
+Applies to step 9 of `git-ship` once the watch wakes on anything but a `state` of `passing` or `failing` or a `conflicted: true` record, and to a target whose CLI carries no `canon pr checks`.
+
+## The fallback watch
+
+When `canon pr checks <number> --json` returns no record at all, the target's CLI predates the verb, and the watch command is `gh pr checks <number> --watch`. The polling loop would never exit on such a target, since an empty read never satisfies its test.
+
+The fallback prints a check table rather than a record, and has no `conflicted` field to separate a conflict from lag.
+
+| Output                                | Route                                     |
+| ------------------------------------- | ----------------------------------------- |
+| At least one check, every one passing | Continue to After completion              |
+| Any failing check                     | Stop the sequence, naming it with its URL |
+| Empty or errored                      | Stop the sequence and report the message  |
+
+Empty output stops rather than waits, since `no checks reported on the '<branch>' branch` is what a conflicted branch prints.
+
+## Refused and unsettled reads
+
+Neither of these is a pass, and neither emits `✅ Shipped`.
+
+- A `reason` and no `state` means the read was refused, such as `no-remote-branch` for a branch deleted on the remote. Stop and report that `reason`.
+- A watch that hit its timeout and printed no final record is CI unsettled after 60 minutes, so report it that way
+
+Do not auto-fix any of these. A stop report is one of the two exceptions to the no-text-between-steps rule.