@erclx/canon 5.38.0 → 5.39.0

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.

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

@@ -0,0 +1,73 @@
+---
+title: Stacked split commands and merge loop
+description: The final commands git-split runs in stacked mode, basing each branch on the one before it, and the restack loop run after each merge
+---
+
+# Stacked split commands and merge loop
+
+Applies to a `git-split` run whose preview reads `Mode: Stacked`, where the groups are ordered and each depends on the commits before it.
+
+## Final commands
+
+Base each branch on the previous one and cherry-pick only that group's commits, since the base branch already carries every prior commit.
+
+```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
+```
+
+## Stacked merge loop
+
+When the user signals the previous stacked PR has merged, restack the next one.
+
+1. Rebase and push, taking the own-commit-count from the original split table:
+
+   ```bash
+   git fetch origin main && git checkout <branch> && git rebase --onto origin/main HEAD~<own-commit-count> && git push --force-with-lease
+   ```
+
+2. Verify the base auto-retargeted to main with `gh api repos/{owner}/{repo}/pulls/<num> --jq .base.ref`. If not, run `gh api -X PATCH repos/{owner}/{repo}/pulls/<num> -f base=main --silent`.
+3. Reply: `✅ <branch> rebased onto main. Ready for squash-merge.`
+
+Both reads go through REST, which a cloud session's GitHub proxy serves where it refuses GraphQL.
+
+### Edge cases
+
+Two states change the loop.
+
+- If this branch's commits modify a file added by an unmerged upstream PR, wait for that PR to merge before rebasing
+- If a base-branch deletion orphaned the PR, recreate it with the final commands' create on `-f head=<branch> -f base=main` and a fresh body, then print `opened=true`

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

@@ -34,10 +34,14 @@ Run these commands in parallel to gather git context:
 
 ### Order and commands
 
+Order and stage the groups so each commit lands whole.
+
 - Order commits by dependency: commit dependencies before the files that import them.
 - Prefix the full command sequence with `git restore --staged .` to unstage everything, then stage and commit each group in order.
 - For `D` status files, use `git rm <file>`. For `A` or `M` files, use `git add <file>`.
-- For `R<score>` status rows, `--name-status` emits three tab-separated fields: `R<score>\t<old>\t<new>`. Treat the pair as one file, keep both paths in the same group, and restage them together with `git add <old> <new>` so git detects the rename at commit time. Splitting the pair across groups produces an add-plus-delete pair instead of a rename.
+- For `R<score>` status rows, `--name-status` emits three tab-separated fields, `R<score>\t<old>\t<new>`
+
+Treat a rename pair as one file. Keep both paths in one group and restage them with `git add <old> <new>`, so git detects the rename at commit time rather than recording an add plus a delete.
 
 ## Response format
 
@@ -53,12 +57,12 @@ Run these commands in parallel to gather git context:
 
 **All <total> files accounted for.**
 
-Count characters in each `<type>(<scope>): <subject>` line. Shorten any subject that exceeds 72 characters and update the table.
-
-After outputting the preview, execute the final command immediately. Claude Code's tool permission dialog is the confirmation gate. Do not wait for user input.
+Count characters in each `<type>(<scope>): <subject>` line, shortening any subject past 72 characters and updating the table. Then execute the final command immediately without waiting for user input, since Claude Code's tool permission dialog is the confirmation gate.
 
 ### Final command
 
+Run it as soon as the preview is out.
+
 ```bash
 git restore --staged .
 # Commit 1: <subject>
@@ -71,8 +75,6 @@ git add <old> <new> && git commit -m "<type>(<scope>): <subject>"
 
 ## After execution
 
-Respond with exactly one line:
+Respond with exactly one line and add no other text:
 
 `✅ Committed: <n> commits`
-
-Do not add any other text.

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

@@ -49,17 +49,32 @@ For each row, determine merge state of its branch:
    - `OPEN`: state is `open`, record PR number and URL.
    - `CLOSED`: state is `closed` (not merged), record PR number.
    - Command fails or returns no PR: fall through.
-3. Fallback: `git branch --merged main --format='%(refname:short)' 2>/dev/null | grep -qx "<branch>"` to detect linear-merge ancestry. On match, mark `merged (local)`. Otherwise `unmerged`. Match the name alone. Without `--format`, git decorates the current branch with `*` and every branch checked out in a linked worktree with `+`, which is the whole set being enumerated.
+3. Fallback: `git branch --merged main --format='%(refname:short)' 2>/dev/null | grep -qx "<branch>"`. On match, mark `merged (local)`, otherwise `unmerged`.
 
-Determine dirtiness: `git -C <path> status --porcelain` non-empty means `dirty`.
+Match the name alone in the fallback. Without `--format`, git decorates the current branch with `*` and every branch checked out in a linked worktree with `+`, which is the whole set being enumerated.
 
-Determine current: the row whose `path` equals `git rev-parse --show-toplevel`. Resolve the root rather than comparing `pwd`, which equals the worktree root only when the session sits at the top of it. A session in any subdirectory would match no row, and the current-worktree exclusion in `cleanup` would pass its own worktree into the remove set.
+### Dirty, current, and foreign
 
-Determine provenance: a non-main row is `foreign` when its `path` does not start with `<MAIN_ROOT>/.claude/worktrees/`. That prefix is the folder `session-worktree` creates under, a convention of that skill rather than a fact this one owns. A tree an operator registered by hand anywhere else on disk reads as `foreign`. Step 1 has already marked the main row `main`, so it never reaches this test.
+Three more marks come from the row's own path.
 
-Determine occupancy: run `canon sessions list --json` once for the whole enumeration, never once per row. Resolve each enumerated row's `path` and each live session's `worktree` field with `realpath` before comparing, since a session registered from a second clone of this repository reports a path under that clone rather than under `MAIN_ROOT`, and a raw string compare would hold nothing back. A row is `occupied` when a resolved `worktree` from any live session equals its resolved `path`. A resolved session `worktree` outside `MAIN_ROOT` names a different checkout, so it clears no row here and marks none as occupied.
+| Mark      | Test                                                                             |
+| --------- | -------------------------------------------------------------------------------- |
+| `dirty`   | `git -C <path> status --porcelain` is non-empty                                  |
+| current   | `path` equals `git rev-parse --show-toplevel`                                    |
+| `foreign` | A non-main row whose `path` does not start with `<MAIN_ROOT>/.claude/worktrees/` |
 
-The roster is unreadable when the command exits non-zero, when its JSON carries a `reason` field instead of a populated `sessions` array, or when `sessions` is non-empty but no entry carries a `worktree` key at all, which is the shape an older binary prints and cannot be told apart from a roster answering that nothing is occupied. `list` leaves the Notes column silent on that failure rather than changing behavior beyond it. `cleanup` refuses instead, stated in its own section below.
+Resolve the root rather than comparing `pwd`, which equals it only at the top of the worktree. A session in a subdirectory would match no row, and `cleanup` would pass its own worktree into the remove set.
+
+The `foreign` prefix is the folder `session-worktree` creates under, a convention of that skill rather than a fact this one owns. A tree an operator registered by hand anywhere else reads as `foreign`, and the main row never reaches this test.
+
+### Occupancy
+
+Run `canon sessions list --json` once for the whole enumeration, never once per row. A row is `occupied` when a live session's `worktree` equals its `path`.
+
+- Resolve both sides with `realpath` before comparing, since a session from a second clone reports a path under that clone and a raw compare would hold nothing back
+- A resolved session `worktree` outside `MAIN_ROOT` names a different checkout, so it marks no row occupied
+
+The roster is unreadable when the command exits non-zero, when its JSON carries a `reason` instead of a populated `sessions` array, or when `sessions` is non-empty and no entry carries a `worktree` key. An older binary prints that last shape, which cannot be told apart from nothing occupied.
 
 ## `list` mode
 
@@ -70,7 +85,7 @@ Print the enumeration as a table, then stop. `list` has no final command.
 | -- | ---------------------------------- | ----------------- | -------- | ------ | -------- |
 ```
 
-Notes column shows the first that applies of `current`, `occupied`, `foreign`, `dirty`, or empty. Show paths relative to `MAIN_ROOT` (`.claude/worktrees/<name>`). A `foreign` row sits outside `MAIN_ROOT`, so print its path in full.
+Notes column shows the first that applies of `current`, `occupied`, `foreign`, `dirty`, or empty. Show paths relative to `MAIN_ROOT` (`.claude/worktrees/<name>`), and a `foreign` row's path in full. An unreadable roster leaves the Notes column silent and changes nothing else.
 
 After the table, append a one-line hint:
 
@@ -79,54 +94,17 @@ After the table, append a one-line hint:
 
 ## `cleanup` mode
 
-If Enumeration marked the roster unreadable, stop: `❌ Session roster unreadable, so occupancy cannot be checked. Resolve the canon sessions list failure, then re-run cleanup.` Hold every non-main row rather than computing the remove set from the other five tests alone, since removing a tree a live session holds is the failure this skill exists to prevent and a sweep that removes nothing costs one re-run.
+If Enumeration marked the roster unreadable, stop: `❌ Session roster unreadable, so occupancy cannot be checked. Resolve the canon sessions list failure, then re-run cleanup.`
 
-From the enumeration, include a worktree in the remove set when all hold:
-
-1. Not the main row.
-2. Not the current session's worktree.
-3. Not occupied by a live session.
-4. Not a `foreign` tree.
-5. State is `merged` or `merged (local)`.
-6. Working tree is clean.
-
-Every other non-main row goes to the skip set with a one-word reason, the first that applies in this order: `current`, `occupied`, `foreign`, `dirty`, `open`, `closed`, `unmerged`. A `foreign` tree that is also dirty reports `foreign`, since `dirty` is a state the operator can clear and `foreign` is not. Leading with the transient reason invites a commit or stash that changes nothing, after which the row reports `foreign` and holds back anyway.
-
-### Preview
-
-```plaintext
-**Removing:** <count>
+Hold every non-main row rather than computing the remove set from the other tests, since removing a tree a live session holds is the failure this skill exists to prevent, and a sweep that removes nothing costs one re-run.
 
-| Path | Branch | PR |
-| ---- | ------ | -- |
+### Remove set and final command
 
-**Skipping:** <count>
-
-| Path | Branch | Reason |
-| ---- | ------ | ------ |
-```
-
-If the remove set is empty, stop with `❌ Nothing to remove. All linked worktrees are current, dirty, unmerged, or foreign.`
-
-### Final command
-
-After the preview, execute immediately. Claude Code's tool permission dialog is the confirmation gate. Do not wait for user input.
-
-```bash
-git -C <MAIN_ROOT> worktree remove <path1> \
-  && git -C <MAIN_ROOT> branch -D <branch1> \
-  && git -C <MAIN_ROOT> worktree remove <path2> \
-  && git -C <MAIN_ROOT> branch -D <branch2> \
-  && git -C <MAIN_ROOT> worktree prune
-```
-
-Chain one `worktree remove` + `branch -D` pair per row in the remove set, then a single `worktree prune` at the end.
+Read `${CLAUDE_SKILL_DIR}/references/cleanup.md` for the remove set, the skip reasons and their order, the preview, and the final command. `list` mode skips it.
 
 ## After execution
 
-Respond with exactly one line:
+Respond with exactly one line and add no other text:
 
 - `list`: `✅ <n> worktrees listed`
 - `cleanup`: `✅ Removed: <count> worktrees, <count> branches pruned`
-
-Do not add any other text.