@erclx/canon 5.38.0 → 5.39.0

package/claude/skills/draft-ready/SKILL.md

@@ -41,7 +41,11 @@ canon tasks next-label --claim --json
 
 The claim reserves the label under `.canon/ordinal-locks/`, so a second session allocating at the same moment gets the next one. A bare read reserves nothing and can return a label a live claim already holds.
 
-Branch on the record's `reason` rather than on the exit code, taking `label` from a record that carries one. `label-contended` means re-run the claim. Report the verb as unavailable and stop when the installed binary carries no `next-label` subcommand, or when an unknown `--claim` prints no record, since that binary predates the flag. Never fall back to a bare read or a label picked by hand, which reopens the collision the claim exists to prevent.
+Branch on the record's `reason` rather than on the exit code, taking `label` from a record that carries one.
+
+- `label-contended` means re-run the claim
+- Report the verb as unavailable and stop when the binary carries no `next-label` subcommand, or prints no record for an unknown `--claim`, since it predates the flag
+- Never fall back to a bare read or a label picked by hand, which reopens the collision the claim exists to prevent
 
 ## Step 3: write the overview
 
@@ -71,7 +75,9 @@ Run the match check in `${CLAUDE_SKILL_DIR}/references/assembly.md` before going
 
 ## Step 6: write the task
 
-Write `<main-root>/.canon/tasks/<label>-<slug>.md` by heredoc, from the label Step 2 claimed, without calling the verb again, since a second call would claim a different label. Its frontmatter, H1, and `## Outcomes` follow `${CLAUDE_SKILL_DIR}/../task-board/references/tasks.md`. Write a `Ready:` line beside the `Plan:` line pointing at the folder, then point the task at the plan through the verb:
+Write `<main-root>/.canon/tasks/<label>-<slug>.md` by heredoc from the label Step 2 claimed, never calling the verb again, which would claim another. Its frontmatter, H1, and `## Outcomes` follow `${CLAUDE_SKILL_DIR}/../task-board/references/tasks.md`.
+
+Write a `Ready:` line beside the `Plan:` line pointing at the folder, then point the task at the plan through the verb:
 
 ```bash
 canon tasks plan-link <task-stem> .canon/plans/feature-<slug>.md --json
@@ -79,13 +85,19 @@ canon tasks plan-link <task-stem> .canon/plans/feature-<slug>.md --json
 
 Branch on the record rather than on the exit. The `Ready:` line orients a worker reading the task, and `canon tasks archive` reads it to move the folder on ship.
 
-A task file with no row is a dropped task, so place the row in the same pass. The plan exists, so the row takes `## Run now`, per the tests in `${CLAUDE_SKILL_DIR}/../task-board/references/board.md`. A path `canon tasks plan-reach` reports as claimed is a shared file rather than a hold. Name each one and its holder wherever the row is reported below, so whoever controls the board decides whether a contract, a relocation, or a sweep moves the row to `## Up next`.
+### Place the row
+
+A task file with no row is a dropped task, so place the row in the same pass. The plan exists, so the row takes `## Run now`, per the tests in `${CLAUDE_SKILL_DIR}/../task-board/references/board.md`.
+
+A path `canon tasks plan-reach` reports as claimed is a shared file rather than a hold. Name each one and its holder wherever the row is reported, so whoever controls the board decides whether a contract, a relocation, or a sweep moves the row to `## Up next`.
+
+### Check the roster
 
-Check the roster the way `canon:task-board` Step 4 does, reading `canon sessions list --self --json` for this session and `canon sessions list --json` for a row from the same repository, under another `sessionId`, whose `name` starts with `orchestrator-`. Treat a refused read as a roster read that failed.
+Check the roster the way `canon:task-board` Step 4 does, reading `canon sessions list --self --json` for this session and `canon sessions list --json` for a same-repository row under another `sessionId` whose `name` starts with `orchestrator-`. A refused read counts as failed.
 
-- **Orchestrator found.** Write neither file. Message that session with the row's title, the plan link, and the group with its reason, so it places the row itself rather than two sessions writing the board at once.
-- **Not found, and this session's name starts with `worker-` or `planner-`.** Write neither file, since both role bodies ban a board write with no exception. Report the row and its group in Step 8.
-- **Not found otherwise, or the roster read fails.** Write the row into `priority.md` through the same `Bash` route the task file took. A failed read looks like a solo project, and stopping would strand the task on the one path with nobody to place it.
+- **Orchestrator found.** Write neither file. Message that session with the row's title, the plan link, and the group with its reason, so two sessions never write the board at once.
+- **Not found, and this session's name starts with `worker-` or `planner-`.** Write neither file, since both role bodies ban a board write. Report the row and its group in Step 8.
+- **Not found otherwise, or the roster read fails.** Write the row into `priority.md` through the task file's `Bash` route, since a failed read looks like a solo project and stopping strands the task.
 
 Say which branch fired in Step 8.
 

package/claude/skills/draft-screencast/SKILL.md

@@ -10,8 +10,9 @@ metadata:
 ## Guards
 
 - If no topic is provided, stop: `❌ No screencast topic. Describe what you are recording.`
-- Draft, then hand off. Do not edit video or generate captions, and do not drive the application. A recording is another skill's job rather than something forbidden: write the draft, name `record-screencast` as the next step, and stop.
-- Stack-agnostic in the draft. Never name a recording tool, an editing tool, a font, or a window manager. Keep selectors, URLs, wait conditions, and timings out of the beats too, since those four are exactly what the compiler adds in a plan of its own. A beat carrying them stops being a document a person can read and edit down.
+- Draft, then hand off. Do not edit video, generate captions, or drive the application, since a recording is `record-screencast`'s job. Name it as the next step and stop.
+- Stack-agnostic in the draft. Never name a recording tool, an editing tool, a font, or a window manager.
+- Keep selectors, URLs, wait conditions, and timings out of the beats, since the compiler adds those four in a plan of its own and a beat carrying them stops being readable
 
 ## Step 1: read the project context
 
@@ -45,118 +46,11 @@ Build a 2-to-4-word kebab-case slug from the topic and discovery answers. Exampl
 
 Create `demos/<slug>/beats.md` at the project root, creating the folder if it does not exist. The file is committed with the rest of the demo's sources, so a recording can be rebuilt from the folder alone.
 
-Write all nine sections. Pre-seed every section with concrete content so the draft is shippable as-is. The user edits down rather than fills blanks.
+### Fill the template
 
-Load `canon:video-craft` for every zoom and caption value the draft names, and report it rather than proceeding silently when it does not resolve. The template below states none, since each number there traces to a source that skill records.
+Write all nine sections from `${CLAUDE_SKILL_DIR}/references/beats-template.md`, read on reaching this step. Pre-seed every section with concrete content so the draft ships as-is, and the user edits down rather than fills blanks. A run stopped at discovery skips it.
 
-```markdown
-# Screencast: <short title>
-
-## 1. Header
-
-- Audience: <from discovery>
-- Length: <from discovery>
-- Hero moment: <from discovery>
-- Pitch: <one sentence, derived from project context>
-
-## 2. Pre-recording checklist
-
-- [ ] Browser at 1920x1080 with notifications silenced
-- [ ] Session storage and history cleared for the recorded surfaces
-- [ ] Cursor highlighter on
-- [ ] Live URLs and fixtures verified healthy
-- [ ] <one or two project-specific items derived from context>
-
-## 3. Beat sheet
-
-Five beats. Each uses five fields. Add a sixth `Transition out` only when non-default.
-
-### Beat 1: Cold open
-
-- On screen: <derived from hero moment>
-- Action: <one verb, derived>
-- Watch for:
-- Emphasis: zoom onto the action, scale and speed per `canon:video-craft`
-- Caption:
-
-### Beat 2: Setup
-
-- On screen:
-- Action:
-- Watch for:
-- Emphasis: none
-- Caption:
-
-### Beat 3: Hero moment
-
-- On screen: <hero moment from discovery>
-- Action:
-- Watch for:
-- Emphasis: highlight overlay
-- Caption:
-
-### Beat 4: Payoff
-
-- On screen:
-- Action:
-- Watch for:
-- Emphasis: none
-- Caption:
-
-### Beat 5: Outro
-
-- On screen:
-- Action:
-- Watch for:
-- Emphasis: zoom out to full frame
-- Caption:
-
-## 4. Sequencing notes
-
-- Hover before click. The cursor needs a beat to register.
-- Do not cut mid-reset. Let state changes complete on screen.
-- Cut on action, not on stillness.
-- <one or two project-specific gotchas derived from context>
-
-## 5. Production notes
-
-- Resolution: 1920x1080
-- Frame rate: 30fps
-- Container: mp4 H.264
-- Zoom: only on an action too small to read at full frame, scale, speed, and dwell per `canon:video-craft`, zoomed out before every cut
-- Highlight overlay: ~1.5s soft glow
-
-## 6. Captions
-
-- Each caption names what its beat's frame shows, at most two lines of 42 characters, per `canon:video-craft`
-- Hold and reading rate per `canon:video-craft`, splitting a caption across beats rather than shortening its hold
-- Placed off the element the beat acts on
-
-## 7. Distribution
-
-Where the recording ships. Strike rows that do not apply.
-
-- [ ] Native upload to social platform
-- [ ] Canonical host (long-form video platform)
-- [ ] Linked from project README or release notes
-
-## 8. Resolved decisions
-
-Pre-seeded with the common picks. Strike or rewrite as needed.
-
-- Audio: silent plus captions
-- Language: English
-- Chip order: <leave for user, derived from beats>
-- Thumbnail: hero-moment frame
-
-## 9. Wrap
-
-What surrounds the take in the finished video. Each row carries a proposed default. Write `none` on every row to ship the raw take.
-
-- Intro: <proposed title card of two to three seconds naming the subject, or `none`>
-- Outro: <proposed closing card naming where to go next, or `none`>
-- Music: none
-```
+Load `canon:video-craft` for every zoom and caption value the draft names, and report it rather than proceeding silently when it does not resolve.
 
 ## Step 5: output
 

package/claude/skills/draft-screencast/references/beats-template.md

@@ -0,0 +1,119 @@
+---
+title: Beats template
+description: The nine-section template draft-screencast writes to demos/<slug>/beats.md, pre-seeded so the draft ships as-is
+---
+
+# Beats template
+
+Applies to the draft `draft-screencast` Step 4 writes. Fill every placeholder from the project context and the discovery answers. The template states no zoom or caption value, since each traces to a source `canon:video-craft` records.
+
+## Template
+
+```markdown
+# Screencast: <short title>
+
+## 1. Header
+
+- Audience: <from discovery>
+- Length: <from discovery>
+- Hero moment: <from discovery>
+- Pitch: <one sentence, derived from project context>
+
+## 2. Pre-recording checklist
+
+- [ ] Browser at 1920x1080 with notifications silenced
+- [ ] Session storage and history cleared for the recorded surfaces
+- [ ] Cursor highlighter on
+- [ ] Live URLs and fixtures verified healthy
+- [ ] <one or two project-specific items derived from context>
+
+## 3. Beat sheet
+
+Five beats. Each uses five fields. Add a sixth `Transition out` only when non-default.
+
+### Beat 1: Cold open
+
+- On screen: <derived from hero moment>
+- Action: <one verb, derived>
+- Watch for:
+- Emphasis: zoom onto the action, scale and speed per `canon:video-craft`
+- Caption:
+
+### Beat 2: Setup
+
+- On screen:
+- Action:
+- Watch for:
+- Emphasis: none
+- Caption:
+
+### Beat 3: Hero moment
+
+- On screen: <hero moment from discovery>
+- Action:
+- Watch for:
+- Emphasis: highlight overlay
+- Caption:
+
+### Beat 4: Payoff
+
+- On screen:
+- Action:
+- Watch for:
+- Emphasis: none
+- Caption:
+
+### Beat 5: Outro
+
+- On screen:
+- Action:
+- Watch for:
+- Emphasis: zoom out to full frame
+- Caption:
+
+## 4. Sequencing notes
+
+- Hover before click. The cursor needs a beat to register.
+- Do not cut mid-reset. Let state changes complete on screen.
+- Cut on action, not on stillness.
+- <one or two project-specific gotchas derived from context>
+
+## 5. Production notes
+
+- Resolution: 1920x1080
+- Frame rate: 30fps
+- Container: mp4 H.264
+- Zoom: only on an action too small to read at full frame, scale, speed, and dwell per `canon:video-craft`, zoomed out before every cut
+- Highlight overlay: ~1.5s soft glow
+
+## 6. Captions
+
+- Each caption names what its beat's frame shows, at most two lines of 42 characters, per `canon:video-craft`
+- Hold and reading rate per `canon:video-craft`, splitting a caption across beats rather than shortening its hold
+- Placed off the element the beat acts on
+
+## 7. Distribution
+
+Where the recording ships. Strike rows that do not apply.
+
+- [ ] Native upload to social platform
+- [ ] Canonical host (long-form video platform)
+- [ ] Linked from project README or release notes
+
+## 8. Resolved decisions
+
+Pre-seeded with the common picks. Strike or rewrite as needed.
+
+- Audio: silent plus captions
+- Language: English
+- Chip order: <leave for user, derived from beats>
+- Thumbnail: hero-moment frame
+
+## 9. Wrap
+
+What surrounds the take in the finished video. Each row carries a proposed default. Write `none` on every row to ship the raw take.
+
+- Intro: <proposed title card of two to three seconds naming the subject, or `none`>
+- Outro: <proposed closing card naming where to go next, or `none`>
+- Music: none
+```

package/claude/skills/draft-slides/SKILL.md

@@ -38,15 +38,18 @@ Each slide is a full HTML document laid out at 1280 by 720 CSS pixels. Position
 
 The render injects the project's token stylesheet ahead of each slide's own styles, so the deck takes the project's design rather than the toolkit's.
 
-- Use the project's custom properties, such as `var(--color-accent)`, for every color, face, and spacing value the stylesheet defines. Read the names from `.claude/design/base.css` and any overrides under `.claude/design/project/`. When neither exists, say the deck renders unstyled rather than inventing values to cover it.
-- Leave the `--color-*` roles to the stylesheet rather than redefining them in a slide. The master reads its colors off the first slide's `<html>`, and a slide body computing its own `--color-text` is reported, since the bands keep the master's colors.
+- Use the project's custom properties, such as `var(--color-accent)`, for every color, face, and spacing value, read from `.claude/design/base.css` and overrides under `.claude/design/project/`
+- When neither exists, say the deck renders unstyled rather than inventing values to cover it
+- Leave the `--color-*` roles to the stylesheet. The master reads its colors off the first slide's `<html>`, so a slide computing its own `--color-text` is reported, since the bands keep the master's.
 - Vary the composition across slides. Never repeat a title over bullets on every slide. Reach for columns, a row of large numbers, a grid of cards, a chart, a pull quote, and section dividers.
 
 ### Fit and shapes
 
+Text and shapes have to survive the conversion.
+
 - Keep titles short and lines tight, so text fits its box at the size the design sets rather than overflowing the frame.
 - Never write centered body text.
-- Prefer CSS the converter maps to native shapes. An element computing a property it cannot map is drawn as a picture of itself and reported on stderr, so a slide full of gradients and filters stops being editable.
+- Prefer CSS the converter maps to native shapes. An unmappable property is drawn as a picture and reported on stderr, so a slide full of gradients and filters stops being editable.
 
 ## Render
 
@@ -64,7 +67,7 @@ Read every `✗` line the render prints. A picture fallback, a refused link, cha
 
 Run this once after the first render, then stop.
 
-1. Convert the deck to images: `soffice --headless --convert-to pdf <deck>.pptx` then `pdftoppm -r 90 -png <deck>.pdf slide`. If `soffice` or `pdftoppm` is missing, skip the image pass and say so. Do not fail the render.
+1. Convert the deck with `soffice --headless --convert-to pdf <deck>.pptx`, then `pdftoppm -r 90 -png <deck>.pdf slide`. If either is missing, skip the image pass and say so rather than fail the render.
 2. Open and inspect every rendered image in this session, checking each slide for overlap, overflow, low contrast, and empty regions.
 3. Fix the reported issues and the `✗` lines in the slide files once, re-render, and stop. Do not loop indefinitely on aesthetics.
 

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

@@ -31,6 +31,8 @@ Run these commands in parallel to gather git context:
 
 ### Preview
 
+Output the preview first.
+
 - **Current:** <current_branch>
 - **Suggested:** <suggested_name>
 - **Length:** <count>/50
@@ -55,8 +57,6 @@ git branch -m <current> <suggested>
 
 ## After execution
 
-Respond with exactly one line:
+Respond with exactly one line and add no other text:
 
 `✅ Renamed: <current> → <suggested>`
-
-Do not add any other text.

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

@@ -30,6 +30,8 @@ Run these commands in parallel to gather git context:
 
 ### Preview
 
+Output the preview first.
+
 - **Files:** <if ≤3 list all, if >3 show first 3 + "+N more">
 - **Message:** `<type>(<scope>): <subject>`
 - **Length:** <count>/72
@@ -38,14 +40,14 @@ After outputting the preview, execute the final command immediately. Claude Code
 
 ### Final command
 
+Run it as soon as the preview is out.
+
 ```bash
 git commit -m "<type>(<scope>): <subject>"
 ```
 
 ## After execution
 
-Respond with exactly one line:
+Respond with exactly one line and add no other text:
 
 `✅ Committed: <type>(<scope>): <subject>`
-
-Do not add any other text.

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

@@ -16,18 +16,25 @@ its own reply, so skip the comment in step 7. The push and body sync still run.
 
 - If `git branch --show-current` returns `main`, stop: `❌ On main. Switch to a PR branch first.`
 - If `git status --porcelain` is empty, stop: `❌ No changes to ship.`
-- Resolve `<number>` once, here, through `canon pr head --json`, reading the record's `number`. Every later step names this `<number>` rather than resolving it again. A record refusing with `ambiguous-pull` stops: `❌ Two open PRs on this branch. Name the one to update.`
-- When no record comes back, or it carries no `number`, read the open pull requests on the branch over REST instead. The branch is encoded so a `/` in its name reaches the query as `%2F`:
+- Resolve `<number>` once, here, through `canon pr head --json`, reading the record's `number`. Every later step names this `<number>` rather than resolving it again.
+- A record refusing with `ambiguous-pull` stops: `❌ Two open PRs on this branch. Name the one to update.`
 
-  ```bash
-  gh api "repos/{owner}/{repo}/pulls?head={owner}:$(git branch --show-current | jq -Rr @uri)&state=open" --jq '.[].number'
-  ```
+### Fallback lookup
 
-  Nothing printed stops: `❌ No open PR for this branch. Use git-ship to open one.` More than one number takes the `ambiguous-pull` stop above rather than the first, since two open pull requests on one head against different bases leave nothing to say which one this push updates.
+When no record comes back, or it carries no `number`, read the open pull requests on the branch over REST instead. The branch is encoded so a `/` in its name reaches the query as `%2F`:
 
-Every read and write in this skill runs on REST, since the `gh pr` subcommands run on GraphQL and a cloud session's GitHub proxy refuses it. A cloud worker answering a review reaches this skill through `review-address`, so one GraphQL call here breaks that whole leg.
+```bash
+gh api "repos/{owner}/{repo}/pulls?head={owner}:$(git branch --show-current | jq -Rr @uri)&state=open" --jq '.[].number'
+```
+
+- Nothing printed stops: `❌ No open PR for this branch. Use git-ship to open one.`
+- More than one number takes the `ambiguous-pull` stop rather than the first, since two open pull requests on one head leave nothing to say which one this push updates
+
+### REST and the tracking ref
+
+Every read and write in this skill runs on REST, since the `gh pr` subcommands run on GraphQL and a cloud session's GitHub proxy refuses it. A cloud worker reaches this skill through `review-address`, so one GraphQL call breaks that whole leg.
 
-A missing tracking ref is no longer a guard. An open pull request proves the branch reached the remote, and a branch created by worktree entry has been measured carrying an open pull request with no tracking ref, where the old guard reported that the branch still needed pushing. That message describes a state the branch is not in, so the run stopped on a diagnosis nobody could act on. Step 4 sets the ref instead.
+A missing tracking ref is not a guard, since an open pull request proves the branch reached the remote. A branch created by worktree entry carries an open pull request with no tracking ref, so step 4 sets the ref instead.
 
 ## Sequence
 
@@ -40,7 +47,7 @@ A missing tracking ref is no longer a guard. An open pull request proves the bra
 
    The lease is what stops the force from overwriting a commit this session never read. Run the ancestry test only where an upstream resolves, since it reads `@{u}`.
 
-5. Post the evidence comparison, on every invocation including `reply-owned`, since this comment is not the reply step 8 owns. Run `canon pr evidence <number> --json` and read `reason` on the record rather than the exit code.
+5. Post the evidence comparison on every invocation, `reply-owned` included, since it is not step 8's reply. Run `canon pr evidence <number> --json` and read `reason` rather than the exit code.
    - `no-evidence`: nothing changed under an `evidence/` segment this push. Say nothing and move on.
    - `ok`: write `body` to `.canon/tmp/pr/evidence/body-<number>.md` at the main worktree root (resolved the way `session-worktree` does), then post the comment with `gh api -X POST repos/{owner}/{repo}/issues/<number>/comments -F body=@<main-root>/.canon/tmp/pr/evidence/body-<number>.md --silent` when the record carries no `commentId`, or edit the existing one in place with `gh api -X PATCH repos/{owner}/{repo}/issues/comments/<commentId> -F body=@<main-root>/.canon/tmp/pr/evidence/body-<number>.md` when it does. Clean up the tmp file only after the call reports success.
    - Any other reason is one of the mirrored git refusals (`gh-missing`, `gh-failed`, `no-base`, `unreadable-changes`, `would-empty`). Report it and continue without stopping the chain.

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

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

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

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