@erclx/canon 5.38.0 → 5.40.0

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.

package/claude/skills/git-worktree/references/cleanup.md

@@ -0,0 +1,55 @@
+---
+title: Worktree cleanup
+description: Which enumerated worktrees git-worktree cleanup removes, the skip reasons and their order, the preview, and the final command
+---
+
+# Worktree cleanup
+
+Applies to `git-worktree` in `cleanup` mode, after the enumeration has run and the roster read cleanly. The roster stop stays in the skill body.
+
+## The remove set
+
+Include a worktree when every test holds:
+
+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.
+
+### The skip set
+
+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 the operator can clear `dirty` and cannot clear `foreign`. Leading with the transient reason invites a commit or stash that changes nothing.
+
+## Preview
+
+```plaintext
+**Removing:** <count>
+
+| Path | Branch | PR |
+| ---- | ------ | -- |
+
+**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 without waiting for user input, since Claude Code's tool permission dialog is the confirmation gate.
+
+```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.

package/claude/skills/markdown-craft/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: markdown-craft
-description: Carries the format and structure rules for markdown, being headings, paragraph and list shape, code spans, the date form, punctuation, emphasis, file references, American spelling, and frontmatter wording, and runs the audit after an edit. Use before a substantial markdown edit, when writing a README, a doc, a skill body, or any `.md` file, or when asked "what are the markdown rules" or "which characters are banned". Do NOT use for voice, rhythm, or word choice, which is `write-human`, or for a Mermaid fence or figure, which is `draft-figure`.
+description: Carries the format and structure rules for markdown, being headings, the density limits, paragraph and list shape, code spans, the date form, punctuation, emphasis, file references, American spelling, and frontmatter wording, and runs the audit after an edit. Use before a substantial markdown edit, when writing a README, a doc, a skill body, or any `.md` file, or when asked "what are the markdown rules" or "which characters are banned". Do NOT use for voice, rhythm, or word choice, which is `write-human`, or for a Mermaid fence or figure, which is `draft-figure`.
 metadata:
   family: answer
 ---
@@ -9,7 +9,7 @@ metadata:
 
 Read `${CLAUDE_SKILL_DIR}/references/markdown.md` before a substantial markdown edit. Every rule in it is a fact a scan can settle, so do not work the banned characters from memory.
 
-Run `canon markdown audit <path>` after the edit. Rewrite the sentence carrying a hit rather than swapping the token for a near-synonym.
+Run `canon markdown audit <path>` after the edit, and fix every ban and density finding it reports before moving on. Rewrite the sentence carrying a ban hit rather than swapping the token for a near-synonym, and fix a density finding by its shape rather than trimming characters.
 
 ## Routes