@erclx/canon 5.37.0 → 5.39.0

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

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

@@ -39,15 +39,18 @@ Run these commands in parallel to gather git context:
 
 ### Primary concern
 
-- Identify the primary concern of the current branch. Rename it using `git branch -m` if the current name does not already match. Skip the rename if it already matches. Secondary concerns are extracted as new focused branches via cherry-pick.
-- If no single concern dominates (dumping-ground branch with no clear primary), split all commits into new focused branches and add `git branch -d <current>` to delete the original.
+The current branch keeps its primary concern, and each secondary concern leaves as a new focused branch via cherry-pick.
+
+- Rename the current branch with `git branch -m` when its name does not match the primary concern, and skip the rename when it does
+- If no single concern dominates, as on a dumping-ground branch, split every commit into new branches and add `git branch -d <current>`
 - Propose one new branch per secondary concern following branch.md format.
 
 ### Independent and stacked
 
-- Classify groups as independent or stacked before generating commands.
+Classify the groups before generating commands, since the mode decides each branch's base.
+
 - Independent groups: each group's commits apply to `main` without the others. Base every branch on `main`.
-- Stacked groups: groups are ordered and each depends on the commits before it. Base each branch on the previous group's branch. Cherry-pick only that group's commits onto it. The base branch already carries all prior commits.
+- Stacked groups: groups are ordered and each depends on the commits before it. Base each branch on the previous group's branch and cherry-pick only that group's commits.
 
 ## Response format
 
@@ -64,118 +67,43 @@ Run these commands in parallel to gather git context:
 
 **All <total> commits accounted for.**
 
-- For the primary concern (the current branch), show `<current_branch> → <new_name>` only when renaming. Show `<current_branch>` alone if the existing name already matches the concern.
+- For the primary concern, show `<current_branch> → <new_name>` only when renaming, and `<current_branch>` alone otherwise
 - For stacked mode, list rows in merge order: branches based on `main` first, then each layer above. For independent mode, list the primary concern first.
 
-If Mode is Stacked, append this line to the preview:
-
-`🔁 Sequential squash-merge loop. Squash-merge each PR bottom-up with --delete-branch. After each merge, signal me so I can restack the next branch onto main before you merge it.`
+### Merge order line
 
-If Mode is Independent, append this line to the preview:
+Append the line for the run's mode to the preview.
 
-`🔁 Squash-merge secondaries first, primary last. The primary keeps every cherry-picked commit, so merging it first lands every secondary's content on main and leaves the secondary PRs empty after rebase.`
+| Mode        | Line                                                                                                                                                                                                          |
+| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Stacked     | `🔁 Sequential squash-merge loop. Squash-merge each PR bottom-up with --delete-branch. After each merge, signal me so I can restack the next branch onto main before you merge it.`                           |
+| Independent | `🔁 Squash-merge secondaries first, primary last. The primary keeps every cherry-picked commit, so merging it first lands every secondary's content on main and leaves the secondary PRs empty after rebase.` |
 
 After outputting the preview, execute the final commands immediately. Claude Code's tool permission dialog is the confirmation gate. Do not wait for user input.
 
-Before running them, run the scan in `${CLAUDE_SKILL_DIR}/../git-pr/references/publish.md` against every title and body. Each body stages under `.canon/tmp/` and leaves through `gh`, so the hook sees neither and this scan is the only gate. Each resulting branch reaches the `pull_request` check the git-pr surface carries once its own pull request opens, but not before, so this scan is what catches a leak ahead of that.
+### Pre-publish scan
 
-### Final commands
+Before running them, run the scan in `${CLAUDE_SKILL_DIR}/../git-pr/references/publish.md` against every title and body. Each body stages under `.canon/tmp/` and leaves through `gh`, so the hook sees neither.
 
-For independent mode, base every branch on `main`:
-
-```bash
-# Rename current branch to reflect primary concern
-git branch -m <current_branch> <new_name>
-
-# Create, cherry-pick, push, and open PR for each secondary branch
-mkdir -p .canon/tmp/pr/split
-git switch -c <branch> main && git cherry-pick <sha> <sha> \
-  && git push -u origin <branch> \
-  && (cat <<'BODY' > .canon/tmp/pr/split/<branch>.md
-<body following pr.md template, written from the cherry-picked commits>
-BODY
-) && gh api -X POST 'repos/{owner}/{repo}/pulls' -f title="<title>" -f head=<branch> -f base=main -F body=@.canon/tmp/pr/split/<branch>.md --jq .html_url \
-  && printf 'opened=true\n' \
-  && rm .canon/tmp/pr/split/<branch>.md
-
-# Return to primary branch, push, and open its PR
-git checkout <new_name> && git push -u origin <new_name> \
-  && (cat <<'BODY' > .canon/tmp/pr/split/<new_name>.md
-<body following pr.md template, written from the primary's commits>
-BODY
-) && gh api -X POST 'repos/{owner}/{repo}/pulls' -f title="<title>" -f head=<new_name> -f base=main -F body=@.canon/tmp/pr/split/<new_name>.md --jq .html_url \
-  && printf 'opened=true\n' \
-  && rm .canon/tmp/pr/split/<new_name>.md
-
-# Clean up the body-file dir if all PRs succeeded (no-op when non-empty)
-rmdir .canon/tmp/pr/split 2>/dev/null || true
-```
-
-Every pull request opens through the REST pulls endpoint rather than the `gh pr` create subcommand, which runs on GraphQL and fails where a cloud session's GitHub proxy refuses it. The endpoint requires `base`, so each call names the branch its layer sits on. `-F` reads the body file, where `-f` would post the path itself.
-
-A create the endpoint refuses, such as one for a head that already has an open pull request, exits non-zero and stops the chain before `opened=true` prints and before the body file is removed. The `opened=true` line is what a pull request creation log reads to count the opening, since the REST call prints a URL and never names itself.
-
-For stacked mode, base each branch on the previous and cherry-pick only that group's commits:
-
-```bash
-# Rename current branch to reflect primary concern
-git branch -m <current_branch> <new_name>
-
-mkdir -p .canon/tmp/pr/split
-
-# Group 1: based on main
-git switch -c <branch-1> main && git cherry-pick <g1-sha> <g1-sha> \
-  && git push -u origin <branch-1> \
-  && (cat <<'BODY' > .canon/tmp/pr/split/<branch-1>.md
-<body following pr.md template, written from the cherry-picked commits>
-BODY
-) && gh api -X POST 'repos/{owner}/{repo}/pulls' -f title="<title>" -f head=<branch-1> -f base=main -F body=@.canon/tmp/pr/split/<branch-1>.md --jq .html_url \
-  && printf 'opened=true\n' \
-  && rm .canon/tmp/pr/split/<branch-1>.md
-
-# Group 2: based on <branch-1>, this group's commits only
-git checkout -b <branch-2> && git cherry-pick <g2-sha> <g2-sha> \
-  && git push -u origin <branch-2> \
-  && (cat <<'BODY' > .canon/tmp/pr/split/<branch-2>.md
-<body following pr.md template, written from the cherry-picked commits>
-BODY
-) && gh api -X POST 'repos/{owner}/{repo}/pulls' -f title="<title>" -f head=<branch-2> -f base=<branch-1> -F body=@.canon/tmp/pr/split/<branch-2>.md --jq .html_url \
-  && printf 'opened=true\n' \
-  && rm .canon/tmp/pr/split/<branch-2>.md
-
-# Return to primary branch, push, and open its PR on the last group's branch
-git checkout <new_name> && git push -u origin <new_name> \
-  && (cat <<'BODY' > .canon/tmp/pr/split/<new_name>.md
-<body following pr.md template, written from the primary's commits>
-BODY
-) && gh api -X POST 'repos/{owner}/{repo}/pulls' -f title="<title>" -f head=<new_name> -f base=<branch-2> -F body=@.canon/tmp/pr/split/<new_name>.md --jq .html_url \
-  && printf 'opened=true\n' \
-  && rm .canon/tmp/pr/split/<new_name>.md
-
-# Clean up the body-file dir if all PRs succeeded (no-op when non-empty)
-rmdir .canon/tmp/pr/split 2>/dev/null || true
-```
+Each branch reaches the `pull_request` check only once its own pull request opens, so this scan is what catches a leak ahead of that.
 
-## After execution
+### Final commands
 
-Respond with exactly one line:
+Read the command block for the run's mode on reaching this step, and skip the other.
 
-`✅ Renamed: <old> → <new> | PRs: <primary-url>, <url1>, <url2>`
+- Independent mode: `${CLAUDE_SKILL_DIR}/references/independent.md`
+- Stacked mode: `${CLAUDE_SKILL_DIR}/references/stacked.md`
 
-Read each URL off the line its create printed through `--jq .html_url`.
+Every pull request opens through the REST pulls endpoint rather than the `gh pr` create subcommand, which runs on GraphQL and fails where a cloud session's GitHub proxy refuses it. The endpoint requires `base`, so each call names its layer's branch, and `-F` reads the body file where `-f` would post the path.
 
-Do not add any other text.
+A create the endpoint refuses, such as one for a head with an open pull request, exits non-zero and stops the chain before `opened=true` prints and the body file is removed. A pull request creation log counts openings off `opened=true`, since the REST call prints a URL and never names itself.
 
-## Stacked merge loop
+## After execution
 
-When the user signals the previous stacked PR has merged, restack the next one.
+Respond with exactly one line and add no other text, reading each URL off the line its create printed through `--jq .html_url`:
 
-1. Rebase and push. The own-commit-count comes from the original split table.
-   `git fetch origin main && git checkout <branch> && git rebase --onto origin/main HEAD~<own-commit-count> && git push --force-with-lease`
-2. Verify the PR's base auto-retargeted to main with `gh api repos/{owner}/{repo}/pulls/<num> --jq .base.ref`, a REST read a cloud session's GitHub proxy serves where it refuses GraphQL. If not, retarget it with `gh api -X PATCH repos/{owner}/{repo}/pulls/<num> -f base=main --silent`.
-3. Reply: `✅ <branch> rebased onto main. Ready for squash-merge.`
+`✅ Renamed: <old> → <new> | PRs: <primary-url>, <url1>, <url2>`
 
-Edge cases:
+## Stacked merge loop
 
-- If this branch's commits modify a file added by an unmerged upstream PR, wait for that PR to merge before rebasing.
-- If the PR was orphaned by base-branch deletion, recreate it with the same create the final commands run, passing `-f head=<branch> -f base=main` and a regenerated body, and print `opened=true` after it.
+When the user signals the previous stacked PR has merged, restack the next one. Read `${CLAUDE_SKILL_DIR}/references/stacked.md` from its `## Stacked merge loop` section for the rebase, the retarget, the reply, and the two edge cases. An independent split skips it.

package/claude/skills/git-split/references/independent.md

@@ -0,0 +1,40 @@
+---
+title: Independent split commands
+description: The final commands git-split runs in independent mode, basing every new branch on main and opening each pull request over REST
+---
+
+# Independent split commands
+
+Applies to a `git-split` run whose preview reads `Mode: Independent`. Every branch is based on `main`, since each group's commits apply there without the others.
+
+## Final commands
+
+```bash
+# Rename current branch to reflect primary concern
+git branch -m <current_branch> <new_name>
+
+# Create, cherry-pick, push, and open PR for each secondary branch
+mkdir -p .canon/tmp/pr/split
+git switch -c <branch> main && git cherry-pick <sha> <sha> \
+  && git push -u origin <branch> \
+  && (cat <<'BODY' > .canon/tmp/pr/split/<branch>.md
+<body following pr.md template, written from the cherry-picked commits>
+BODY
+) && gh api -X POST 'repos/{owner}/{repo}/pulls' -f title="<title>" -f head=<branch> -f base=main -F body=@.canon/tmp/pr/split/<branch>.md --jq .html_url \
+  && printf 'opened=true\n' \
+  && rm .canon/tmp/pr/split/<branch>.md
+
+# Return to primary branch, push, and open its PR
+git checkout <new_name> && git push -u origin <new_name> \
+  && (cat <<'BODY' > .canon/tmp/pr/split/<new_name>.md
+<body following pr.md template, written from the primary's commits>
+BODY
+) && gh api -X POST 'repos/{owner}/{repo}/pulls' -f title="<title>" -f head=<new_name> -f base=main -F body=@.canon/tmp/pr/split/<new_name>.md --jq .html_url \
+  && printf 'opened=true\n' \
+  && rm .canon/tmp/pr/split/<new_name>.md
+
+# Clean up the body-file dir if all PRs succeeded (no-op when non-empty)
+rmdir .canon/tmp/pr/split 2>/dev/null || true
+```
+
+Repeat the secondary block once per secondary branch. The skill body states why each create goes through the REST endpoint and what `opened=true` marks.