@erclx/canon 5.40.0 → 5.42.0

package/claude/skills/plan-groundwork/references/groundwork.md

@@ -44,9 +44,11 @@ Does not govern:
 
 - Name the folder `<nn>-<slug>`, a two-digit ordinal and a kebab-case slug.
 - The ordinal marks a folder per track, opened once and worked over time, unlike a file addressed by name, one with its own sorting prefix, or one overwritten on purpose.
-- Claim the ordinal through `canon records ordinal groundwork <slug> --claim`, which reads the highest one across both `.canon/groundwork/` and `.canon/intake/` and creates the folder in one atomic act, so two sessions opening at once never share a number. The two kinds share one order.
+- Claim the ordinal through `canon records ordinal groundwork <slug> --claim`, which reads the highest across `.canon/groundwork/` and `.canon/intake/`, since the two kinds share one order
+- The claim creates the folder in the same atomic act, so two sessions opening at once never share a number
 - With neither folder holding an entry, the first one opened takes `01`, whatever number a track's own files start at.
-- Never renumber an existing folder. The ordinal is the order it opened, and a later reader cites it by that name.
+
+Never renumber an existing folder. The ordinal is the order it opened, and a later reader cites it by that name.
 
 ## What a working track looks like
 
@@ -86,20 +88,15 @@ A folder missing `06` and `07` is live, and that is its only status marker.
 
 ## README.md
 
-Orients. Holds no findings.
+Orients and holds no findings. It states the phase out loud in its first three lines, in the form `Groundwork phase. Nothing here is a feature plan.`
 
 - A one-line definition of the investigation
 - A `## Why` section stating why the track is running now
 - A file-map table of filename and what it holds, kept current
 - A `## Method` section splitting internal sources from external ones, naming which were used and which were not yet done, and listing under a leads heading any external source found but not opened
+- Closing `## Prior art` and `## Source citation` sections, the second stating the rule below so a returning session finds it in the folder
 
-### Closing sections and phase
-
-- A `## Prior art` section
-- A `## Source citation` section stating the rule below, so a returning session finds it in the folder
-- The phase stated out loud in the first three lines, in the form `Groundwork phase. Nothing here is a feature plan.`
-
-Every claim about a source outside the project carries a link to it, wherever the claim appears in the folder. Without one, a later reader cannot tell a fetched page from recall. A source found and not read is listed as a lead and is never cited, since a link to a page nobody opened is worse than no link. Listing it stops a later pass re-searching for it.
+Every claim about a source outside the project carries a link to it, wherever the claim appears in the folder, so a later reader can tell a fetched page from recall. A source found and not read is listed as a lead and never cited, since a link to a page nobody opened is worse than none. Listing it stops a later pass re-searching for it.
 
 Where the track supersedes an earlier plan or an earlier folder, name it and say not to go looking for it. Without that, the old reasoning keeps circulating.
 
@@ -117,11 +114,10 @@ Written when the subject is large enough to run away. Holds constraints, risks,
 
 ## 06-decision.md
 
-Closes the folder. Everything above it is input. Write it from the skeleton under `## Template`, with an H3 per dropped alternative.
+Closes the folder. Everything above it is input. Write it from the skeleton under `## Template`, with an H3 per dropped alternative, a list that stops a future session re-proposing a rejected idea.
 
-`## Revisit when` carries the "Overturned by" line of each lean that became the decision, as written. A lean the decision did not take carries nothing, and a track whose deciding leans carried no overturn line omits the section.
-
-The dropped list stops a future session re-proposing a rejected idea.
+- `## Revisit when` carries the "Overturned by" line of each lean that became the decision, as written
+- A lean the decision did not take carries nothing, and a track whose deciding leans carried no overturn line omits the section
 
 ## 07-next-session.md
 
@@ -158,7 +154,9 @@ A lean is weaker than a plan's suggestion: it records the current read on an ope
 
 ## Template
 
-### README.md
+The orienting README comes first, then the closing decision, with an H3 per dropped alternative.
+
+**`README.md`**
 
 ```markdown
 ---
@@ -203,7 +201,7 @@ Every claim about a source outside the project carries a link. A source found
 and not read is listed as a lead and is never cited.
 ```
 
-### 06-decision.md
+**`06-decision.md`**
 
 ```markdown
 ---

package/claude/skills/plan-intake/references/intake.md

@@ -7,7 +7,7 @@ description: Folder layout, ordinal naming, reserved index number, frontmatter a
 
 Applies to an intake folder at `.canon/intake/<nn>-<slug>/`. One folder holds one dump, filed by domain, and every finding in it is an item carrying a measured problem, one proposed fix, and a verdict.
 
-The folder is gitignored, and backed wherever a records remote is configured: `canon records push` and `canon records pull` protect it against the machine being lost there, refuse with `no-remote` where it is not, and neither protects against a compaction dropping a session's reasoning before anyone has pushed. No check reaches its contents, so the shape below survives only by being read.
+The folder is gitignored. Where a records remote is configured, `canon records push` and `canon records pull` protect it against losing the machine, and elsewhere they refuse with `no-remote`. Neither saves reasoning a compaction drops before a push. No check reaches its contents, so the shape below survives only by being read.
 
 <!-- canon-length-exempt: the folder shape and the item template share one reader, and a split into a second reference is queued as its own change -->
 
@@ -41,11 +41,13 @@ Does not govern:
 
 ## Folder name
 
-- Name the folder `<nn>-<slug>`, a two-digit zero-padded ordinal followed by a kebab-case slug. This is the folder's own ordinal, distinct from the `NN-<domain>.md` numbering a cluster file carries inside it.
+- Name the folder `<nn>-<slug>`, a two-digit zero-padded ordinal and a kebab-case slug, distinct from the `NN-<domain>.md` numbering of its cluster files
 - The ordinal marks a folder per track, opened once and worked over time, distinct from a file addressed by name, one already carrying its own sorting prefix, or one deliberately overwritten.
-- Claim the ordinal through `canon records ordinal intake <slug> --claim`, which reads the highest one already present across both `.canon/intake/` and `.canon/groundwork/` and creates the folder in the same atomic act, closing the race a read-then-create sequence leaves open between two sessions opening at once. A listing then sorts by when each folder opened rather than alphabetically, and the count includes both kinds because the two share one creation-order line.
-- With neither folder holding an entry, the first one opened takes `01`. Do not read this off the numbering inside a dump, which starts at `00` and disagrees with groundwork's own first required file.
-- Never renumber an existing folder. The ordinal is the order it opened, and a later reader cites it by that name.
+- Claim the ordinal through `canon records ordinal intake <slug> --claim`, which reads the highest across `.canon/intake/` and `.canon/groundwork/`, since the two share one creation order
+- The claim creates the folder in the same atomic act, closing the race a read-then-create leaves open between two sessions opening at once
+- With neither folder holding an entry, the first one opened takes `01`, never read off a dump's inner numbering, which starts at `00`
+
+Never renumber an existing folder. The ordinal is the order it opened, and a later reader cites it by that name.
 
 ## What a working intake looks like
 
@@ -68,9 +70,8 @@ An intake failing these is non-conforming even when it satisfies every shape rul
 
 `00` is the only reserved number. Everything else is read order, and the domain rides in the filename so a reader knows what `07-tooling.md` holds without opening it.
 
-Do not reserve mid-range numbers. Clusters differ per dump, so a contract over `06` would force every future intake into one dump's shape. A folder whose shape is fixed can reserve its numbers, and that half of the convention does not transfer.
-
-Let the file count follow the number of separable domains. A large dump with two domains is a small folder.
+- Do not reserve mid-range numbers, since clusters differ per dump and a contract over `06` would force every intake into one dump's shape
+- Let the file count follow the number of separable domains. A large dump with two domains is a small folder.
 
 ## Frontmatter and dating
 
@@ -113,35 +114,39 @@ Where an item touches a task already on the board, say so in the index rather th
 ```
 
 - `Problem:`, `Fix:`, `Worth it:`, and the empty `You:` slot ship on every item. The other two are conditional.
-- Number items per cluster file, and give a finding split after the fact a letter suffix on the number it came from, as in `3a` beside `3`. Renumbering the items below it instead moves every label a reader or an answer already cited.
-- `Suggested:` is required whenever `Open:` is present. A bare question invites a bare answer, and `ok` against two defensible options carries no information. Where the answer is the operator's preference rather than a technical call, say so in that form rather than inventing a default.
-- `Overlaps:` never replaces `Worth it:`. The items where a live board task might be the thing that is wrong are exactly the ones whose verdict matters most.
-
-Two heading levels is the right depth inside a cluster file. A third means the cluster should have been its own file.
+- Number items per cluster file, giving a finding split later a letter suffix such as `3a` beside `3`, since renumbering moves every cited label
+- `Suggested:` is required whenever `Open:` is present, since `ok` against two defensible options carries no information
+- Where the answer is the operator's preference rather than a technical call, say so in that form rather than inventing a default
+- `Overlaps:` never replaces `Worth it:`, since an item a live board task might have wrong is the one whose verdict matters most
 
-An item may carry a bolded standalone line between the bullets where a finding needs a name of its own. Keep it rare. Everything fitting the four bullets belongs in them.
+Two heading levels is the right depth inside a cluster file. A third means the cluster should have been its own file. An item may carry a rare bolded standalone line between the bullets where a finding needs a name of its own, and everything fitting the four bullets belongs in them.
 
 ## The answer contract
 
-`You:` belongs to the operator and ships empty on every item.
+`You:` belongs to the operator and ships empty on every item. Empty means unread and never agreement, so accepting a verdict is typed as one token, `- **You:** ok`.
 
-Empty means unread. It never means agreement. Accepting a verdict is typed as one token, `- **You:** ok`.
+- Never fill a `You:` slot, and never infer a disposition from an empty one
+- On a resume pass, report unread items by count rather than deciding them
 
-That inverts the plan file's contract, where a blank answer slot means accept the suggestion, and the inversion is deliberate. A plan is read in one sitting with every question already surfaced in conversation. An intake folder is read over weeks, so an empty slot is ambiguous between accepting the verdict and never having reached the item, and the second reading is far more likely. Acting on silence as consent ships a change nobody approved.
+### Why silence is not consent
 
-Never fill a `You:` slot, and never infer a disposition from an empty one. On a resume pass, report unread items by count rather than deciding them.
+This inverts the plan file's contract, where a blank slot means accept the suggestion. A plan is read in one sitting with every question already surfaced. An intake folder is read over weeks, so an empty slot more likely means nobody reached the item, and acting on it ships a change nobody approved.
 
-A slot is filled two ways. The operator types into the cluster file, or answers in chat and a verb lands the selection on the item. Both put the answer on the item, which is what keeps retrieval working, and neither lets a session decide one. An answer given in conversation and never written back leaves the item unread, since the file rather than the conversation is the record.
+### Filling a slot
 
-An item already carrying an answer is refused rather than overwritten, whichever route the second answer arrives by. A filled slot is a decision already made, and revising one is the operator editing their own line.
+The operator types into the cluster file, or answers in chat and a verb lands the selection on the item. Both put the answer on the item, which keeps retrieval working, and neither lets a session decide one.
 
-## Retrieval
+- An answer given in conversation and never written back leaves the item unread, since the file is the record
+- An item already carrying an answer is refused rather than overwritten, whichever route the second answer takes
+- Revising a filled slot is the operator editing their own line
 
-Answers live on items, so one pass over the folder reports every touched slot.
+## Retrieval
 
-A session with the toolkit CLI on PATH reads the folder through `canon intake list`, which reports per-folder counts bare and one folder's items with `--json`, and takes `--unread` to keep only the empty slots. It is the surface under test, and it skips the index and every fenced sample, which the greps below cannot do.
+Answers live on items, so one pass over the folder reports every touched slot. With the toolkit CLI on PATH, read the folder through `canon intake list`, the surface under test.
 
-The greps stay for a reader without the CLI, and they overcount by whatever the folder displays in a fence.
+- Bare, it reports per-folder counts, `--json` gives one folder's items, and `--unread` keeps only the empty slots
+- It skips the index and every fenced sample, which the greps below cannot do
+- The greps stay for a reader without the CLI, and they overcount by whatever the folder displays in a fence
 
 ```bash
 awk '/^### /{h=FILENAME": "$0} /^- \*\*You:\*\*./{print h; print "   "$0}' *.md

package/claude/skills/plan-intake-answer/REQUIREMENT.md

@@ -45,4 +45,4 @@ The batching fails a fifth way. A folder holding thirty unread items put as thir
 - Promoting an answered item onto the board, which is `task-board` and runs after the answers land
 - The item format, the answer contract, and retrieval, which the `plan-intake` skill's `references/intake.md` owns and this skill cites
 - The comparable answer slots in groundwork and feature plans, which carry their own contracts and are a separate measurement
-- Deciding when to fire. The skill is user-invoked through `disable-model-invocation`, so answering is the operator's call rather than a description match.
+- Deciding when to fire. The description states `Do NOT auto-trigger`, so answering is the operator's call rather than a description match.

package/claude/skills/plan-intake-answer/SKILL.md

@@ -1,7 +1,6 @@
 ---
 name: plan-intake-answer
-description: Walks an intake folder's unread items and puts them as batched questions in chat, writing each selection back onto the item it answers. Use when asked to "answer the intake", "work through the open items", "answer my intake questions", "go through the dump", or "let me answer these from here". Do NOT use to file a dump or write new items, which is `plan-intake`.
-disable-model-invocation: true
+description: Walks an intake folder's unread items and puts them as batched questions in chat, writing each selection back onto the item it answers. Use when asked to "answer the intake", "work through the open items", "answer my intake questions", "go through the dump", or "let me answer these from here". Do NOT use to file a dump or write new items, which is `plan-intake`. Do NOT auto-trigger.
 metadata:
   family: decide
 ---

package/claude/skills/pr-evidence/REQUIREMENT.md

@@ -0,0 +1,40 @@
+---
+name: pr-evidence
+description: What posting a pull request's rendered-surface evidence is for, the gaps it closes, and what it refuses to do
+---
+
+# PR evidence requirement
+
+## Gap
+
+Without this skill, the evidence a pull request carries is one step inside `git-pr`. A session refreshing the screenshots on a new head either reruns a title and body it did not mean to touch, or borrows the step's reference by path. Two skills borrowed it that way, and each copy drifted.
+
+A session judging from the diff whether an evidence image changed cannot see a regenerated image it did not author, so the image ships with no comment. A reviewer holding screenshots and a checklist has nothing to click into, and a slow deploy holds the ship chain while it waits for an address.
+
+## Must
+
+- Run the evidence verb on every pull request it is given and let `no-evidence` be the skip, since asking a session to look lets an unseen image ship with no comment
+- Run alone against an open pull request, resolving the number from the branch when none is passed, so a later head gets evidence without a body rewrite
+- Edit the one marked comment in place on a later run, so a re-post never duplicates the thread or drops a carried checklist
+- Put a preview address on a pull request changing a rendered surface when the project's deploy can mint one, since a reviewer needs a page to click into
+- Bound the wait on that preview and finish without the link on a timeout, since a slow deploy must not hold the ship
+- Link the branch's running local server when this worktree serves one, since a reviewer on the operator's machine can drive the branch
+- Drop that link when the pull request closes, since a link outliving its branch points at whatever runs there next
+
+## Must not
+
+- Dispatch a deploy whose command names no branch, since Cloudflare Pages publishes such a deploy to production
+- Create a pull request, or post against a number it guessed, since a write to a wrong number lands on another branch's thread
+- Call a GraphQL-backed `gh` subcommand, since the cloud review-address leg runs this skill through `git-followup`
+- Print a result line of its own, since `git-pr` prints one and its report ends with the lines this skill returns
+- Exist only for the author to type its name. `git-pr`, `git-followup`, and `git-ship` each invoke it, and a review of the catalog drops it when none does.
+
+## Guards
+
+- Stop and ask for the number when none was passed and no open pull request resolves for the branch
+
+## Out of scope
+
+- The title, body, labels, and pre-publish scan, which `git-pr` owns
+- Writing the checklist, which `ui-checklist` owns. This skill only consumes the handoff file and removes it after posting.
+- Driving the checklist in the running app, which `review-ui` owns

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

@@ -0,0 +1,53 @@
+---
+name: pr-evidence
+description: Posts the rendered-surface evidence on an open pull request, being the screenshot comparison with the UI checklist, the checklist alone when git refuses the comparison, the local server link, and the preview address, editing the one marked comment in place on every later head. Use when asked to "post the evidence", "refresh the screenshots on the PR", or "re-post the evidence on the new head", and as the closing step of `git-pr`. Do NOT use to write a pull request's title or body, which is `git-pr`, or to write the checklist, which is `ui-checklist`.
+metadata:
+  family: after-pr
+---
+
+# PR evidence
+
+The evidence a pull request carries is owed again on every new head, while its title and body are not. This skill posts it against one pull request number, so `git-pr` runs it as its last step and any session can run it alone after a push.
+
+## Resolve the pull request
+
+Take the number the caller passed and look nothing up. `git-pr` passes the number its final command printed, and never invokes this skill when that command refused on a head mismatch and printed none.
+
+Run bare, resolve the open pull request for the current branch:
+
+```bash
+canon pr head --json
+```
+
+Read `reason` on the record rather than the exit code, since a shell function wrapping `canon` can flatten it to zero.
+
+- A record carrying `number`: hold it for every step below
+- Any refusal, including `gh-failed` for a branch with no open pull request, stops the run with `❌ No open pull request resolved for this branch: <message>. Pass the number and re-run.`
+- Never create a pull request here and never guess a number, since a write to a wrong number lands on another branch's thread
+
+## Post the evidence
+
+Read `${CLAUDE_SKILL_DIR}/references/evidence.md` and run its sections in order against the number, being the checklist, the local server, the evidence comparison, the checklist alone, and the preview address.
+
+- Every post and edit goes through `gh api` over REST, since a cloud session's proxy refuses the GraphQL that `gh pr` runs on
+- 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
+- A lone run on a later head edits the marked comment through the record's `commentId` and passes no `--checklist` for a handoff already deleted, since the verb carries the checklist forward
+
+## Report
+
+Collect only the lines below whose condition holds, and nothing when none does. A lone run prints them. A run another skill invoked hands them back to that caller and prints nothing, since `git-pr` prints its own result line and then these lines, and printing here too shows them twice.
+
+| Condition                                                 | Line                                                               |
+| --------------------------------------------------------- | ------------------------------------------------------------------ |
+| 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>`                                    |
+| A git refusal or a preview refusal the reference reports  | `⚠️ <reason>: <message>`                                           |
+
+### The no-local-preview line
+
+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. A later run only carries a link forward, so it cannot add one the comment never had.
+
+To add the link later, start the server and run this skill again, adding `--checklist` to the evidence call when one is still owed.

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

@@ -0,0 +1,150 @@
+---
+title: Rendered-surface evidence
+description: How pr-evidence finds the UI checklist and the local server, posts the evidence comparison or the checklist alone as the fallback for a git refusal, and adds the preview address, for a change that touches a rendered surface
+---
+
+# Rendered-surface evidence
+
+The procedure of `pr-evidence`, run in order against one pull request number. It runs on every pull request with no test on the diff ahead of it, since `no-evidence` is the silent branch for one that changes no rendered surface.
+
+## Contents
+
+- [Find the UI checklist](#find-the-ui-checklist)
+- [Find the local server](#find-the-local-server)
+- [Post the evidence comparison](#post-the-evidence-comparison)
+- [Post the UI checklist alone](#post-the-ui-checklist-alone)
+- [Post the preview address](#post-the-preview-address)
+
+## Find the UI checklist
+
+`ui-checklist` writes a visual checklist to `.canon/tmp/handoff/ui-checklist/<slug>.md` at the main worktree root when a change needs visual verification, with `<slug>` derived per `${CLAUDE_SKILL_DIR}/../git-branch/references/slug.md`. This skill is the file's sole consumer.
+
+- Resolve the main root the way `session-worktree` does, `git worktree list --porcelain | grep -m 1 '^worktree ' | cut -d' ' -f2-` falling back to `pwd`
+- A missing file means no checklist was produced, and the two steps below each skip their checklist half
+- Scan an existing file against `${CLAUDE_SKILL_DIR}/../git-pr/references/publish.md` before either step posts it, the same as the body
+- The evidence step decides where it lands, since a checklist reads next to its screenshots and posting it alone is the fallback for a refused render
+
+## Find the local server
+
+A reviewer on the operator's machine can open the branch's running dev server, which screenshots and a checklist cannot stand in for. Ask the verb before the evidence step, so the first evidence comment already carries the link:
+
+```bash
+canon pr local --json
+```
+
+The verb reports the lowest port serving an HTML page whose process runs inside this worktree, never one in another worktree or the main checkout, which shows a different branch. `canon pr local --help` states the contract. Read `reason` on the record rather than the exit code.
+
+- `ok`: hold the record's `url` for the evidence step below.
+- `no-server` or `no-listener-reader`: hold the reason for the closing report and pass no link. Never start a server here, since one started inside the ship chain has no owner to stop it.
+- Anything else, including no record or an older binary's unknown-subcommand error: move on silently, as a skip rather than a stop.
+
+### Where the link lands
+
+Pass `--local` to the evidence step only on an `ok`. The binary answering `ok` is the one carrying the flag, so a binary lacking the verb never meets a flag it would reject.
+
+- With a checklist, a diff carrying no evidence image still renders `ok`, and the link rides on the address line under `## Evidence`, above the checklist
+- A link with neither an evidence image nor a checklist still reports `no-evidence`, so a branch changing no rendered surface gets no comment holding a link alone
+- A seeded workflow drops the whole address line once the pull request closes, hosted and local together, so neither link outlives its branch
+
+## Post the evidence comparison
+
+Run the verb once against the pull request number. Pass `--checklist` when the checklist step found a file and `--local` when the step above returned `ok`, and leave each flag off otherwise:
+
+```bash
+canon pr evidence <number> --checklist <main-root>/.canon/tmp/handoff/ui-checklist/<slug>.md --local <url> --json
+```
+
+One call answers both questions because a checklist decides `no-evidence`. A diff carrying a checklist and no evidence image renders `ok` with the checklist in a marked body, so the checklist lands in the one comment a later call finds and edits.
+
+- Pass `--checklist` only for a file that exists
+- The verb refuses as `unreadable-checklist` on a path it cannot read or one holding nothing, a caller bug rather than a transient failure
+- Stop and repair the path on that refusal rather than posting a body with the checklist silently dropped
+
+### Reading the record
+
+Read `reason` on the record rather than the exit code.
+
+- `no-evidence`: nothing changed under an `evidence/` segment and no checklist was passed. Say nothing about the evidence and move on.
+- `ok`: write `body` to `.canon/tmp/pr/evidence/body-<number>.md` at the main worktree root, then post or update the comment:
+
+```bash
+gh api -X POST repos/{owner}/{repo}/issues/<number>/comments -F body=@<main-root>/.canon/tmp/pr/evidence/body-<number>.md --silent
+```
+
+Both posts in this file use the REST issue-comments endpoint, since the `gh pr` subcommands run on GraphQL and a cloud session's GitHub proxy refuses it. `git-followup` runs this skill, so a GraphQL post here would break the cloud review-address leg.
+
+When the record carries a `commentId`, edit that comment in place instead of posting a second. The body reads from the tmp file with `@`, which needs `-F`, since `-f` posts the path itself as the body:
+
+```bash
+gh api -X PATCH repos/{owner}/{repo}/issues/comments/<commentId> -F body=@<main-root>/.canon/tmp/pr/evidence/body-<number>.md
+```
+
+Delete the handoff file and the tmp body once that call reports success, per the cleanup below, since the checklist now lives on the pull request.
+
+### Git refusals
+
+Any other `reason` is a mirrored git refusal, being `gh-missing`, `gh-failed`, `no-base`, `unreadable-changes`, or `would-empty`. Report it and move on without stopping the chain, since a branch that rarely carries evidence images should not fail on a transient read.
+
+Fall through to the checklist step, which posts the checklist alone rather than losing it.
+
+## Post the UI checklist alone
+
+Run this step only as the fallback, when the evidence step reported a git refusal and a checklist file exists, since every other branch with a checklist rendered `ok` and carried it. The comment carries no marker, so a later `canon pr evidence` call reports no `checklist` for it.
+
+```bash
+gh api -X POST repos/{owner}/{repo}/issues/<number>/comments -F body=@<main-root>/.canon/tmp/handoff/ui-checklist/<slug>.md --silent
+```
+
+### Cleanup
+
+Run the cleanup only once the call that carried the checklist reports success, whichever step that was. On a failure, stop and leave the file, since a retry needs it and deleting it loses the only copy.
+
+The cleanup is a main-root delete, so it goes out as a plain `rm` and then a plain `rmdir`, routed the way `session-worktree` states:
+
+```bash
+rm <main-root>/.canon/tmp/handoff/ui-checklist/<slug>.md
+```
+
+```bash
+rmdir <main-root>/.canon/tmp/handoff/ui-checklist 2>/dev/null || true
+```
+
+- The `rmdir` is a no-op while another branch's pending checklist sits in the folder, so this step never deletes a handoff not its own
+- `git-followup` re-runs `canon pr evidence` with no `--checklist`, and the verb carries the checklist forward out of the comment it edits
+- A tick survives a render at the head its stamp names and is cleared by one at a newer head, so the next UI pass earns it again
+
+## Post the preview address
+
+Run this step when the evidence step returned `ok`, the fallback posted a checklist, or `canon pr evidence <number> --check --json` lists `preview` in `owed`. Otherwise skip it silently.
+
+- The first two mean the pull request changes a rendered surface, and a reviewer holding a checklist with no screenshots needs the live page most
+- The third is how `git-ship` reaches this step alone when an earlier run's deploy timed out
+- An evidence record carrying a `commentId` takes the third alone, since a preview already on the comment counts as settled whatever head built it, so a later push does not re-mint one
+- The evidence comment is already posted, so the reviewer has the screenshots while the deploy runs
+
+```bash
+canon pr preview <number> --json
+```
+
+### What the verb refuses
+
+The verb dispatches the project's Pages deploy on the pull request's branch and waits on the run for up to 15 minutes. `canon pr preview --help` states the contract. It refuses before dispatching anything in two cases.
+
+- The deploy command passes no `--branch`, since that deploy would publish the branch to production
+- The workflow's push path filter matches no changed path, since a dispatch ignores that filter and the site would show none of the change
+
+### Reading the preview record
+
+Read `reason` on the record rather than the exit code.
+
+- `ok`: re-render the evidence body with the address under `## Evidence`, then post or update it as the evidence step does, through the same tmp file and the record's `commentId`:
+
+```bash
+canon pr evidence <number> --preview <url> --json
+```
+
+The hosted address opens the address line, and a local link already on the comment follows it, carried forward with no flag.
+
+- `no-deploy` or `unserved`: the project deploys nothing a dispatch can start, or its site builds from nothing this branch changed. Say nothing and move on.
+- `unfenced`, `no-alias`, `run-failed`, `timeout`, or a mirrored `gh` refusal: report the record's `message` and move on without stopping the chain
+- A missing link costs the reviewer a click, and a held ship costs the whole chain

package/claude/skills/review-address/references/post-review-findings.md

@@ -5,11 +5,18 @@ description: How review-address posts something worth reporting after Step 7 clo
 
 # Post a finding after the review closed
 
-Outside the numbered flow of `review-address`. The session reads this file when it has something worth reaching the reviewing session after Step 7 already closed the review.
+Outside the numbered flow of `review-address`. The session reads this file when it has something worth reaching the reviewing session after Step 7 already closed the review, such as a settled risk, a filed follow-up, or another finding. It posts directly rather than waiting on a review pass that has nothing left to trigger it.
 
-Not everything worth reaching the reviewing session surfaces inside the numbered flow in `SKILL.md`. A worker that settled a risk, filed a follow-up, or found something else worth reporting after Step 7 already closed the review posts it directly rather than waiting on a review pass that has nothing left to trigger it. Write the body the way Step 6 writes a reply: load `write-human` for voice and word choice, follow `${CLAUDE_SKILL_DIR}/../markdown-craft/references/markdown.md` for punctuation, and run the `${CLAUDE_SKILL_DIR}/../git-pr/references/publish.md` scan before posting with `canon labels scan --body-file .canon/tmp/pr/reply/reply-<number>.md`.
+## The body
 
-Open with `## Post-review findings` rather than `## Review response`, since nothing on the thread is being answered. `review-pr` states the full heading set this belongs to and routes it the same as a response: `role-orchestrator`'s poll picks it up and sends the reviewing session back for a pass. Close the body with `🤖 Addressed by Claude Code` on its own line, matching the reply's footer.
+Write the body the way Step 6 writes a reply.
+
+- Load `write-human` for voice and word choice, and follow `${CLAUDE_SKILL_DIR}/../markdown-craft/references/markdown.md` for punctuation
+- Run the `${CLAUDE_SKILL_DIR}/../git-pr/references/publish.md` scan before posting, with `canon labels scan --body-file .canon/tmp/pr/reply/reply-<number>.md`
+- Open with `## Post-review findings` rather than `## Review response`, since nothing on the thread is being answered
+- Close the body with `🤖 Addressed by Claude Code` on its own line, matching the reply's footer
+
+`review-pr` states the full heading set this belongs to and routes it the same as a response, so `role-orchestrator`'s poll picks it up and sends the reviewing session back for a pass.
 
 ```bash
 gh api -X POST 'repos/{owner}/{repo}/issues/<number>/comments' -F body=@.canon/tmp/pr/reply/reply-<number>.md --silent

package/claude/skills/review-address/references/rebase-conflicts.md

@@ -21,20 +21,35 @@ Pop only when the stash ran. On a clean tree, which is what a run whose findings
 
 Never merge `main` into the branch. The repository squash-merges, so a merge commit here reads as noise on the pull request.
 
+### A branch carrying merges
+
+A branch carrying merge commits of its own, such as a fan-in integrator's, rebases with `git rebase --rebase-merges origin/main` instead. A plain rebase drops the merges and replays every member commit in one line, which loses the one merge commit per member a reviewer reads.
+
+- `--rebase-merges` re-runs each merge without the resolution it recorded, so resolve each again by the rules below
+- `git config rerere.enabled true`, set before the first merge, replays a recorded resolution in place of resolving it again
+
 ## Resolving a conflict
 
 These rules apply to a hunk from the rebase and a hunk from the stash pop alike:
 
 - Never take one side wholesale with `--ours` or `--theirs`. Both sides are valid content, so the drop is silent and passes every check.
-- Never resolve a generated file by hand. A file the project check rebuilds, such as an `index.md` carrying no `auto: false`, takes either side to clear the conflict and gets its real content from the regen below.
-- Where two branches wrote prose into one file, keep both sides and rewrite what the merge broke. A section that opens by counting what follows needs the count updated rather than the two versions concatenated.
-- When a hunk needs a decision the tree does not carry, stop rather than guessing, and name where the branch was left. The two sources recover differently. A guess that compiles is the failure this stage would otherwise introduce, and either case reaches the operator as an ordinary finding on the next review pass.
-  - A hunk raised by the rebase takes `git rebase --abort`, which restores the old base: `❌ Conflict needs a decision at <file>. Branch left on its old base.`
-  - A hunk raised by the stash pop arrives after the rebase already landed, so no abort applies and the conflict stays in the tree: `❌ Conflict needs a decision at <file>. Branch rebased, fixes left conflicted in the tree.`
+- Never resolve a generated file by hand, such as an `index.md` carrying no `auto: false`. Take either side and let the regen below rebuild it.
+- Where two branches wrote prose into one file, keep both sides and rewrite what the merge broke, such as a count opening a section
+- Both sides of every hunk sit in the conflict and `git log origin/main` names what landed, so never wait on the orchestrator for context
+
+### A hunk needing a decision
+
+When a hunk needs a decision the tree does not carry, stop rather than guessing and name where the branch was left, since a guess that compiles is the failure this stage would introduce. Either case reaches the operator as an ordinary finding on the next review pass. The two sources recover differently.
+
+- A hunk raised by the rebase takes `git rebase --abort`, which restores the old base: `❌ Conflict needs a decision at <file>. Branch left on its old base.`
+- A hunk raised by the stash pop arrives after the rebase landed, so the conflict stays in the tree: `❌ Conflict needs a decision at <file>. Branch rebased, fixes left conflicted in the tree.`
+
+### The stop message
 
-Both sides of every hunk sit in the conflict and `git log origin/main` names what landed, so the tree carries the context. Do not wait on the orchestrator for it.
+The stop still owes a message, since the next review pass never starts on a branch nobody pushed. When the launch named a controlling session, send it the stop line through `canon:session-relay` before halting, per the worker channel the `role-worker` skill states.
 
-The stop still owes a message. When the launch named a controlling session, send it the stop line through `canon:session-relay` before halting, adding the commit on `main` that wrote the other side of the hunk, per the worker channel the `role-worker` skill states. Nothing else surfaces the halt, since the next review pass that would read it as a finding never starts on a branch nobody pushed. With nobody named, print the two lines above and stop.
+- Add the commit on `main` that wrote the other side of the hunk
+- With nobody named, print the two lines above and stop
 
 ## After the rebase
 

package/claude/skills/review-address/references/rest-reads.md

@@ -5,7 +5,9 @@ description: The reads review-address runs over REST, being the findings on the
 
 # REST reads
 
-The guard and Step 1 of `review-address`. The session reads this file on reaching Step 1, and from the guard when `canon pr head --json` hands back no `number`. Every read 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 runs this skill, so one GraphQL call breaks the whole leg.
+The guard and Step 1 of `review-address`. The session reads this file on reaching Step 1, and from the guard when `canon pr head --json` hands back no `number`.
+
+Every read 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 runs this skill, so one GraphQL call breaks the whole leg.
 
 ## The findings