@erclx/canon 5.26.0 → 5.28.0

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

@@ -39,9 +39,9 @@ The verb reads the listening sockets on this machine, keeps those whose process
 
 Pass `--local` to the evidence step only on an `ok` here. 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 a local link rides in the same comment above the checklist, so a reviewer gets both in one place. A local link with neither an evidence image nor a checklist still reports `no-evidence`, which keeps a branch that changed no rendered surface from getting a comment holding a link and nothing else.
+With a checklist, a diff carrying no evidence image still renders `ok`, and a local link rides in the same comment on the address line under `## Evidence`, above the checklist, so a reviewer gets both in one place. A local link with neither an evidence image nor a checklist still reports `no-evidence`, which keeps a branch that changed no rendered surface from getting a comment holding a link and nothing else.
 
-A seeded workflow replaces the line with a note once the pull request closes, so the link does not outlive the branch it points at.
+A seeded workflow drops the whole address line once the pull request closes, hosted and local segments together and with no note in their place, so neither link outlives the branch it points at.
 
 ## Post the evidence comparison
 
@@ -98,7 +98,7 @@ rmdir <main-root>/.canon/tmp/handoff/ui-checklist 2>/dev/null || true
 
 The `rmdir` is a no-op when another branch's pending checklist still sits in the folder, which keeps this step from deleting a handoff that is not its own.
 
-Deleting the file is what makes the later re-render safe. `git-followup` re-runs `canon pr evidence` with no `--checklist`, and the verb carries the checklist forward out of the comment it is editing, so the boxes a reviewer already ticked survive the push.
+Deleting the file is what makes the later re-render safe. `git-followup` re-runs `canon pr evidence` with no `--checklist`, and the verb carries the checklist forward out of the comment it is editing, so the checklist survives the push. A tick survives a render at the head its stamp names and is cleared by one at a newer head, which leaves the next UI pass to earn it again.
 
 ## Post the preview address
 
@@ -110,15 +110,15 @@ The evidence comment is already posted, so the reviewer has the screenshots whil
 canon pr preview <number> --json
 ```
 
-The verb dispatches the project's Pages deploy on the pull request's branch and waits on the run for up to 15 minutes. It refuses before dispatching anything when the deploy command passes no `--branch`, since that deploy would publish the branch to production. `canon docs pr-preview` states the contract. Read `reason` on the record rather than the exit code.
+The verb dispatches the project's Pages deploy on the pull request's branch and waits on the run for up to 15 minutes. It refuses before dispatching anything when the deploy command passes no `--branch`, since that deploy would publish the branch to production, and when the workflow's own push path filter matches no path the pull request changed, since a dispatch ignores that filter and the site it published would show none of the change. `canon docs pr-preview` states the contract. Read `reason` on the record rather than the exit code.
 
-- `ok`: re-render the evidence body with the address on its first line, then post or update it exactly as the evidence step does, through the same tmp file and the `commentId` the record carries:
+- `ok`: re-render the evidence body with the address on the line under `## Evidence`, then post or update it exactly as the evidence step does, through the same tmp file and the `commentId` the record carries:
 
 ```bash
 canon pr evidence <number> --preview <url> --json
 ```
 
-The hosted address takes the first line and a local link already on the comment moves to the second, carried forward with no flag.
+The hosted address opens the address line and a local link already on the comment follows it on the same line, carried forward with no flag.
 
-- `no-deploy`: the project deploys nothing a dispatch can start. Say nothing and move on.
+- `no-deploy` or `unserved`: the project deploys nothing a dispatch can start, or nothing this branch changed is something its site builds from. Say nothing and move on.
 - Any other `reason`, being `unfenced`, `no-alias`, `run-failed`, `timeout`, or a mirrored `gh` refusal: report it with 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/git-ship/SKILL.md

@@ -1,6 +1,8 @@
 ---
 name: git-ship
 description: Runs the full post-feature workflow by syncing docs, staging commits, renaming the branch, and opening a PR. Use after implementing a feature, or when asked to "ship", "ship this", or "ship it". Do NOT auto-trigger. Shipping is a decision the user takes.
+metadata:
+  family: ship
 ---
 
 # Ship

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

@@ -1,6 +1,8 @@
 ---
 name: git-split
 description: Splits a mixed-commit branch into focused branches off main using cherry-pick. Use when a branch has unrelated commits, asking "split this branch", or needing to separate concerns into reviewable PRs.
+metadata:
+  family: after-pr
 ---
 
 # Git split

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

@@ -1,6 +1,8 @@
 ---
 name: git-stage
 description: Groups staged files by concern and generates one conventional commit per group. Use when asked to "group these changes into commits", or when staged changes span multiple concerns and need to ship as separate commits. Do NOT use on a single-concern staged set. That is `git-commit`, which also preserves a hunk-level selection this skill's unstage and restage over whole files would widen.
+metadata:
+  family: ship
 ---
 
 # Git stage

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

@@ -1,6 +1,8 @@
 ---
 name: git-worktree
 description: Lists linked worktrees with PR state and cleans up merged ones. Use when asked to "list worktrees", "clean up worktrees", or after shipping a PR to reclaim slots. Do NOT use to enter a worktree from scratch (use `session-worktree`).
+metadata:
+  family: after-pr
 ---
 
 # Git worktree

package/claude/skills/index-lookup/SKILL.md

@@ -1,6 +1,8 @@
 ---
 name: index-lookup
 description: Answers a topic search over every tracked index.md catalog in the project by running `canon indexes list --json` and matching the topic against each entry's title, description, and path, then reports the hits or names why there are none. Names the gitignored task and memory catalogs and the groundwork and intake record folders as pointers outside its walked corpus, so it never claims a topic is undocumented when the topic only sits there. Use when asked "where is X documented", "is there a page about X", "search the docs for X", "find the index entry for X", or "what covers X". Do NOT use to grep source code, browse a file whose path is already known, or regenerate an index, which is `canon indexes regen`.
+metadata:
+  family: answer
 ---
 
 # Index lookup

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

@@ -1,6 +1,8 @@
 ---
 name: markdown-propose
 description: Reviews a named markdown surface against a named concern, drafts a per-file proposal under `.canon/proposals/<nn>-<slug>/` carrying a diff and a reason for each change, and stops without editing a source file. Takes the concern and the surface as inputs, such as a claim stated stronger than the record, a fact gone stale, two files disagreeing, or a passage duplicated without derivation. A later invocation applies what the operator answered. Use when asked to "propose a change to CLAUDE.md", "draft a rewrite of this standard", "propose fixes to this doc", "draft alternatives for this passage", or "apply the answered proposals". Do NOT use to report without drafting a replacement (`canon markdown audit`), to review a diff already made (`review-branch`), or to file a raw brain dump as findings (`plan-intake`).
+metadata:
+  family: check
 ---
 
 # Markdown propose

package/claude/skills/memory-capture/SKILL.md

@@ -1,6 +1,8 @@
 ---
 name: memory-capture
 description: Extracts durable patterns from the current session, routes a domain fact to the context entry that owns it, and writes the residue to `.canon/memory/` as feedback, project, user, or reference files. Use when asked to "capture memory", "capture lessons", "wrap up the session", "end of session memory", or as a step in autoship. Do NOT use to curate existing memory. Use `memory-review` for that.
+metadata:
+  family: ship
 ---
 
 # Memory capture

package/claude/skills/memory-review/SKILL.md

@@ -1,6 +1,8 @@
 ---
 name: memory-review
 description: Reviews `.canon/memory/` and proposes per-entry actions (promote to an always-loaded rule, move into a skill body, route to a context entry, hand off to governance, or retire as stale). Also runs the discuss, challenge, apply, and cleanup phases on an existing review file. Use when asked to "review memory", "discuss memory questions", "challenge the promotes", "apply memory decisions", "cleanup memory review", "promote memory", or "consolidate memories". Do NOT auto-apply. Output a grouped proposal and wait for block-by-block approval.
+metadata:
+  family: ship
 ---
 
 # Memory review

package/claude/skills/plan-feature/SKILL.md

@@ -1,6 +1,8 @@
 ---
 name: plan-feature
 description: Plans a feature by reading the project's Claude setup and scanning relevant source files. Outputs which files to touch, risks, and ambiguities, then stops. Use before implementing anything, or when asked to "implement X", "add X", "build X", or "I want to add X". Do NOT implement. Plan only.
+metadata:
+  family: decide
 ---
 
 # Plan feature

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

@@ -1,6 +1,8 @@
 ---
 name: plan-groundwork
 description: Opens and runs a numbered groundwork folder under `.canon/groundwork/<nn>-<slug>/` for a topic that has to be measured before it can be planned. Detects open, resume, and close from the folder itself. Use when asked to "research X", "dig into X", "work out what we should do about X", "measure this before we commit", or "open a groundwork folder". Do NOT use to write a feature plan or to implement. That is `plan-feature`.
+metadata:
+  family: decide
 ---
 
 # Plan groundwork

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

@@ -1,6 +1,8 @@
 ---
 name: plan-intake
 description: Files a raw brain dump into a numbered intake folder under `.canon/intake/<nn>-<slug>/`, one item per finding carrying a measured problem, a proposed fix, and a verdict. Use when asked to "file this dump", "triage my notes", "work through this list", "sort out this brain dump", or "run an intake pass". Do NOT use for one question that has to be measured before anyone can plan it. That is `plan-groundwork`.
+metadata:
+  family: decide
 ---
 
 # Plan intake

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

@@ -2,6 +2,8 @@
 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
+metadata:
+  family: decide
 ---
 
 # Plan intake answer

package/claude/skills/project-commands/SKILL.md

@@ -1,6 +1,8 @@
 ---
 name: project-commands
 description: Runs a command the project documents in its development context entry and stops there. Use when asked to "start the app", "start the dev server", "run the checks", "run the build", "spin it up", or "what commands does this project have". Do NOT use to confirm a change works in a running app, which needs verification past the launch. Do NOT use to deploy, publish, or release.
+metadata:
+  family: build
 ---
 
 # Project commands

package/claude/skills/read-frames/SKILL.md

@@ -1,6 +1,8 @@
 ---
 name: read-frames
 description: Pulls numbered still frames from any video, a raw take or a composed render, through `canon demo frames`, reads each one with the Read tool, and reports one plain description per frame. Never judges the recording, since a frame read is evidence rather than a verdict. Use when asked to "check the recording", "read the demo frames", "see what the video shows", or right after `canon demo run` writes a take or a composition renders and nobody has opened the video yet. Do NOT use to record the video, which is `record-screencast`, or to state whether the recording looks correct or broken, which is out of scope for every surface in the toolkit today.
+metadata:
+  family: answer
 ---
 
 # Read frames

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

@@ -1,6 +1,8 @@
 ---
 name: record-screencast
 description: Drives a screencast draft through to a recording. Compiles it with `canon demo compile` when no plan exists yet at the default path, skipping compile when one is already there, runs `canon demo run` once nothing is unresolved, then composes the take into a finished mp4 through HyperFrames when the draft's wrap section asks for anything. Reports every unresolved field from the compile or run record and stops rather than guessing one. Use when asked to "record the screencast", "run the demo", "compile and record this draft", or right after `draft-screencast` prints its next-step line. Do NOT use to draft the beats, which is `draft-screencast`, or to fill in a plan's target or URL, which is the operator's own edit.
+metadata:
+  family: generate
 ---
 
 # Record screencast

package/claude/skills/repo-metadata/SKILL.md

@@ -1,6 +1,8 @@
 ---
 name: repo-metadata
 description: Proposes a GitHub About description, homepage, and topic set computed from the README's opening line and package.json, reports the difference against what the repository's remote already carries, and stops without writing. A later invocation, carrying the operator's answered fields, writes the change through gh repo edit. Use when asked to "propose repo metadata", "check the github description", "does our github about text match the readme", "sync github topics", "update the repo homepage", or "apply the repo metadata answers". Do NOT use to edit README.md itself, or to change a repository setting other than description, homepage, or topics.
+metadata:
+  family: setup
 ---
 
 # Repo metadata

package/claude/skills/restate-plainly/SKILL.md

@@ -1,6 +1,8 @@
 ---
 name: restate-plainly
 description: Restates a dense answer or a named markdown document in plain language, cutting jargon and keeping only what changes a decision. Use when asked to "restate that in plain language", "say that plainly", "what does this actually mean", "cut the jargon", "give me the plain version", or "restate this document". Do NOT use to draft or revise prose, which is `write-human`, and do NOT fire on the model's own judgment that its own output was dense.
+metadata:
+  family: answer
 ---
 
 # Restate plainly

package/claude/skills/review-address/REQUIREMENT.md

@@ -19,6 +19,8 @@ A declined finding fails on a third axis, which is where its reason ends up. A w
 - Handle each finding independently, so one unresolved item does not block the others
 - Verify before pushing, since a red follow-up costs the reviewer a second pass
 - Rebase onto `origin/main` when the branch no longer merges, after the findings are addressed and before the push, so one force-push carries both
+- Rebase as well when the branch still merges but `main` changed a file it writes since it branched, since a clean merge can hide a semantic conflict and the pull request's green run tested a `main` that no longer exists
+- Leave a branch alone when `main` moved only on files it does not write, since rebasing on every merge is a merge queue's cost without its batching
 - Test staleness on every invocation, including one carrying no findings, since a branch goes stale from `main` moving rather than from anything the review said
 - Re-test once the fixes are commits, since the first test reads committed history and cannot see a fix that touches lines `main` moved
 - Rebuild a generated file through the project check rather than resolving its conflict by hand
@@ -45,8 +47,8 @@ A declined finding fails on a third axis, which is where its reason ends up. A w
 ## Guards
 
 - No open pull request for the current branch: stop
-- The pull request carries no review comments or threads and the branch still merges: stop with a pass. A closed review says nothing about whether the branch still merges, so the staleness test decides this one rather than the finding count.
-- A conflict needing a decision the tree does not carry: stop with the branch left on its old base
+- The pull request carries no review comments or threads, the branch still merges, and `main` changed no file it writes: stop with a pass. A closed review says nothing about whether the branch still merges, so the staleness test decides this one rather than the finding count.
+- A conflict needing a decision the tree does not carry: stop with the branch left on its old base, and message the controlling session when the launch named one, since a stopped worker reaches nobody otherwise
 
 ## Out of scope
 

package/claude/skills/review-address/SKILL.md

@@ -1,6 +1,8 @@
 ---
 name: review-address
 description: Pulls review findings and CI status on the current branch's open PR, fixes each in the working tree, refreshes any stale `.claude/` docs, replies with a summary comment, and pushes a follow-up commit. The worker's return leg after `review-pr`. Use when asked to "address the review", "fix the PR comments", "respond to review", or after an orchestrator posts findings. Do NOT use to write a review. That is `review-pr`.
+metadata:
+  family: after-pr
 ---
 
 # Review address
@@ -11,7 +13,7 @@ the PR from an independent session. This skill consumes them: fix, reply, push.
 ## Guards
 
 - Resolve `<number>` and `<tip>` off `canon pr head --json`. An `ambiguous-pull` refusal stops: `❌ Two open PRs on this branch. Name the one to address.` A record with no `number` takes the lookup in `${CLAUDE_SKILL_DIR}/references/rest-reads.md`. Nothing resolving stops: `❌ No open PR. Nothing to address.`
-- If the PR has no review comments or threads, run step 5's staleness test before deciding. A branch that still merges stops here: `✅ No review findings to address.` One that does not skips steps 1 through 4 and runs step 5 onward, since a branch goes stale from `main` moving and a closed review says nothing about whether it still merges.
+- If the PR has no review comments or threads, run step 5's staleness test before deciding. A branch that passes both of its halves stops here: `✅ No review findings to address.` One that fails either skips steps 1 through 4 and runs step 5 onward, since a branch goes stale from `main` moving and a closed review says nothing about whether it still merges.
 - Fix findings. Do not merge.
 
 ## Step 1: pull the review findings and CI status
@@ -52,12 +54,20 @@ reports no conflict on a branch that has one.
 ```bash
 git fetch origin main
 git merge-tree --write-tree origin/main HEAD
+fork=$(git merge-base origin/main HEAD)
+git diff -z --name-only --no-renames "$fork" HEAD |
+  xargs -0 -r git --literal-pathspecs diff --name-only --no-renames "$fork" origin/main --
 ```
 
-A zero exit means the branch still merges. Skip to step 6, which is the ordinary
-run. A non-zero exit means it does not, so read
-`${CLAUDE_SKILL_DIR}/references/rebase-conflicts.md` for the stash-and-rebase
-sequence, the conflict resolution rules, and the check to re-run afterward.
+`merge-tree` exiting non-zero means the branch no longer merges, and a path the
+last command prints means `main` changed a file it writes after it branched, so
+its green run tested a merge nobody will make. Even a clean merge can hide
+semantic conflicts, per Fowler's [Mainline Integration](https://martinfowler.com/articles/branching-patterns.html#mainline-integration),
+so either one sends the branch to `${CLAUDE_SKILL_DIR}/references/rebase-conflicts.md`
+for the sequence, the conflict rules, and the check to re-run. When that check
+fails after a clean rebase, the failure is the semantic conflict, fixed on the
+branch like any other. Neither firing skips to step 6, which covers a `main` that
+moved only on files the branch does not write.
 
 `git merge-tree` reads committed history, so this test says nothing about the
 fixes still sitting in the working tree. A branch that merges clean as committed,
@@ -139,8 +149,9 @@ full pass rather than a delta, and the reader is owed the reason.
 A run the second guard sent straight to step 5 has no findings to map, so it
 takes a different body rather than an empty list. Open it with `## Rebase`, not
 `## Review response`, since nothing on the pull request is being responded to and
-that heading claims a review this run never read. State that the branch stopped
-merging, name what landed on `main`, name the files resolved by hand and those
+that heading claims a review this run never read. State which half of the test
+fired, being a branch that stopped merging or one `main` changed files under,
+name what landed on `main`, name the files resolved by hand and those
 the regen rebuilt, and close the same way. The heading stays outside the
 `## Review` family so the close-out's equality test on the first line never
 matches it.
@@ -240,10 +251,4 @@ Do not merge. Hand back to the orchestrator for re-review.
 
 ## Post-review findings
 
-Not everything worth reaching the reviewing session surfaces inside the numbered flow above. 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}/../../standards/markdown.md` for punctuation, and run the `${CLAUDE_SKILL_DIR}/../../standards/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. `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.
-
-```bash
-gh api -X POST 'repos/{owner}/{repo}/issues/<number>/comments' -F body=@.canon/tmp/pr/reply/reply-<number>.md --silent
-```
+Something worth reaching the reviewing session can surface after Step 7 already closed the review. Read `${CLAUDE_SKILL_DIR}/references/post-review-findings.md` before posting it, for the heading it opens with, the voice and scan its body takes, and the call that posts it.

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

@@ -0,0 +1,16 @@
+---
+title: Post-review findings
+description: How review-address posts something worth reporting after Step 7 closed the review, being the heading, the voice and scan the body takes, the footer, and the one REST call that posts it
+---
+
+# 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.
+
+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}/../../standards/markdown.md` for punctuation, and run the `${CLAUDE_SKILL_DIR}/../../standards/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. `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.
+
+```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

@@ -1,11 +1,11 @@
 ---
 title: Rebase a stale branch
-description: The stash-and-rebase sequence, the conflict resolution rules, and the two recovery messages a hunk needing a decision takes
+description: The stash-and-rebase sequence, the conflict resolution rules, the two recovery messages a hunk needing a decision takes, and the message it owes the controlling session
 ---
 
 # Rebase a stale branch
 
-Mechanics for Step 5 of `review-address` once `git merge-tree` exits non-zero. A branch that still merges skips this file entirely, which is the ordinary run.
+Mechanics for Step 5 of `review-address` once either half of its staleness test fires, being `git merge-tree` exiting non-zero or `main` having changed a file the branch writes. A branch passing both skips this file entirely, which is the ordinary run.
 
 ## The sequence
 
@@ -34,6 +34,8 @@ These rules apply to a hunk from the rebase and a hunk from the stash pop alike:
 
 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. 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.
+
 ## After the rebase
 
 Re-run the project check. It rebuilds the generated files and covers what the replayed commits broke, and step 6 commits the result alongside the fixes.

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

@@ -1,6 +1,8 @@
 ---
 name: review-branch
 description: Reviews all changes since main for bugs, edge cases, and logic flaws. Reads CLAUDE.md, REQUIREMENTS.md, and ARCHITECTURE.md for context, then applies a structured review to the full diff and outputs a findings report. Coding standards from `.claude/rules/` are auto-loaded by Claude Code. Use when asked to review changes, run a code review, or check the current branch. Do NOT auto-trigger on vague signals like "looks good" or "can you check this". Require an explicit review request or an autoship invocation.
+metadata:
+  family: check
 ---
 
 # Review branch

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

@@ -1,6 +1,8 @@
 ---
 name: review-craft
 description: Carries what a code review looks for and how much evidence a finding needs, from design and scope through breakage outside the diff, a test or check the change weakens to pass, performance, developer experience, executable prose, stale docs, security classes, and rendered output checked against the screenshots a pull request carries. Use when reviewing a change, when a review procedure loads it for its axes, or when asked "what should a review look for", "what does a good review check", "how sure do I need to be before flagging this", or "did the review look at the screenshots". Do NOT use to run a review, post it, or grade its findings, which is `review-branch` for local work and `review-pr` for a pull request, and do NOT use for a deliberate full security audit, which is the built-in `security-review`.
+metadata:
+  family: build
 ---
 
 # Review craft

package/claude/skills/review-craft/references/ui.md

@@ -18,9 +18,9 @@ Read the thread over REST, which a cloud session's GitHub proxy serves where it
 gh api --paginate 'repos/{owner}/{repo}/issues/<number>/comments?per_page=100' --jq '.[] | select((.body // "") | contains("<!-- pr-evidence: head=")) | .body'
 ```
 
-Take the comment whose body carries a `<!-- pr-evidence: head=<sha> -->` marker. Match the marker, never the first line, since the body opens with a `**Preview:**` line when the project has a preview address.
+Take the comment whose body carries a `<!-- pr-evidence: head=<sha> -->` marker. Match the marker, never the first line, since the body opens with `## Evidence` and a comment posted before that layout opens with a `**Preview:**` line instead.
 
-Flag the change as shipping no screenshot when it paints and the pull request carries no marked comment, carries one with no `## Evidence` section, or carries only a checklist posted alone. Then decide how to raise it by whether the project keeps captures, which is the same test `canon pr evidence` applies:
+Flag the change as shipping no screenshot when it paints and the pull request carries no marked comment, carries one with no comparison, meaning no `**Base:**` line and no `<details>` table, or carries only a checklist posted alone. The `## Evidence` heading opens every marked comment, a checklist-only one included, so the heading alone never means screenshots are present. Then decide how to raise it by whether the project keeps captures, which is the same test `canon pr evidence` applies:
 
 ```bash
 git ls-tree -r --name-only <base> | grep -E '(^|/)evidence/.*\.(png|jpe?g|gif|webp|avif|svg)$' | head -1
@@ -45,7 +45,7 @@ mkdir -p .canon/tmp/pr/review/evidence/<number>
 git show <sha>:<path> > .canon/tmp/pr/review/evidence/<number>/<side>-<name>.png
 ```
 
-Take the sha from the row, so the base and head sides are exactly what the comment shows. Then open each file with the file-reading tool. A `*(new)*` base cell has no before image.
+Take the sha from the row, so the base and head sides are exactly what the comment shows. Then open each file with the file-reading tool. A `*(new)*` base cell has no before image, and a state whose cases are all added has no Base column at all. Read the URL out of the `src=` of each `<img>`, or out of `![](` in a comment posted before the embed changed.
 
 ## How many to open
 
@@ -67,11 +67,11 @@ A finding names the wireframe or design-file line the image breaks, never a tast
 
 ## The checklist
 
-The `## What to look at` block between the `pr-checklist` markers is the author's claim about what was verified.
+The `## What to look at` block between the `pr-checklist` markers holds what was claimed as verified. A tick stamped `passed at` the current head is the UI reviewer's pass, and an unstamped tick is an author's or operator's claim.
 
-- Test each ticked box against an opened image showing the state and width it names. Flag a box whose image contradicts it, quoting the box.
+- Test each ticked box against an opened image showing the state and width it names, a stamped one included, since the UI reviewer drove the running app and not the committed stills. Flag a box whose image contradicts it, quoting the box.
 - A ticked box no image covers is untested rather than confirmed, and the finding says so.
-- Test only the rows the current comment shows. A box ticked on an earlier head can describe images the comment no longer carries.
+- Test only the rows the current comment shows. The next render clears a tick whose stamp names another head, so a tick not stamped at the current head may describe images the comment no longer carries.
 - Leave unchecked boxes to the procedure's own read of the description.
 
 ## With no pull request

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

@@ -1,6 +1,8 @@
 ---
 name: review-pr
 description: Reviews an open pull request from an independent session and posts findings as a review comment on the PR. Posts a first pass against the whole change and every later pass against only the commits added since, under `## Review` while any finding is open and `## Review closed` once a pass carries none. Reads project docs and the task board for cross-feature context a self-review lacks. Use when asked to "review the PR", "review this feature's PR", "post a PR review", "re-review the PR", "close out the review", "confirm the findings are fixed", or acting as the orchestrator reviewing a worker's PR. Do NOT use to review local uncommitted changes. That is `review-branch`.
+metadata:
+  family: after-pr
 ---
 
 # Review PR
@@ -83,13 +85,7 @@ Test every unchecked box against the testing discipline in `${CLAUDE_SKILL_DIR}/
 
 Test every ticked box too, bounded to one naming a file or a command. Confirm what it names still exists at `<headRefOid>`, `git show <headRefOid>:<path>` for a file or `git grep <command> <headRefOid>` for a command, rather than re-running what it claims. A box naming neither stays untested, since nothing here can confirm a claim carrying no artifact. A box ticked before a later commit removed or replaced what it names is a `should-fix` finding on the body itself, filed under a `**PR body**` block ahead of the file blocks, since what it corrupts is the merge record rather than a file in the diff.
 
-Test what `## Key Changes` claims against the diff it describes, with `canon pr key-changes <number> --json`. This repository squash-merges, so that section becomes the commit message and the record on the trunk once the branch is gone, which is the same thing a stale ticked box corrupts. Branch on the record rather than on the exit code, which a shell function wrapping `canon` can flatten to zero.
-
-Read `unmet` as a `should-fix` finding under the same `**PR body**` block the stale box takes, one entry per path, quoting the bullet the record carries on `preview` and naming the `head` the comparison ran at. Read the bullet before filing it, since one class survives the reader: a bullet citing where something is defined while claiming an edit elsewhere, which puts a real path in the claim region and points the change at a locative the path does not name. Report that as the class rather than as a stale claim. A body is edited between pushes, so the reading is true at that commit and can be false a minute later. Read `unnamed` for yourself and raise nothing off the count. The class still covers a real omission and equally a generated asset or a regenerated index that earns no bullet, and the entries the reader can name as owing none are already held apart under `incidental`. Open the section and confirm no bullet names the file before putting a single one to the author, because this instruction has sent the question to three pull requests in one day over bullets that had named the files all along, and one of those authors added bullets nobody needed. Report `unresolved` and `incidental` nowhere: the first was judged in neither direction and the second owes no bullet, so neither says anything about the body.
-
-A `reason` of `no-claims` means the reader resolved no path out of a section that exists, which is the extractor failing over prose rather than the body being wrong. Say so and raise nothing. `no-section` is the body carrying no such heading, which is a finding only where the pull request template asks for one.
-
-Compose this on the body read Step 4 already performs rather than opening a second one. That step scans the title and body for a leaked phase label, and both reads answer from the same text at the same head.
+Then test what `## Key Changes` claims against the diff it describes. Read `${CLAUDE_SKILL_DIR}/references/key-changes.md` for the verb that compares them, which field of its record becomes a finding, and which ones raise nothing.
 
 Ask rather than grade. Whether a human is genuinely required is a reading the branch author may hold a reason this session cannot see, so the question carries no severity and enters no count. What it does carry is the heading and the dispatch, on the rule the opening states, because a question the author never receives corrects nothing and the author is the only party who can answer it. Answering it closes it, and the answer may be that the requirement holds.
 
@@ -109,7 +105,7 @@ Use severity: `critical` (blocks merge), `should-fix` (fix before merge), `minor
 
 ## Step 4: post to the PR
 
-Read `${CLAUDE_SKILL_DIR}/references/post.md` for the body file name, the body shape for each pass, the Testing, reviewer, and PR body blocks, the marker every body carries, and the scans ahead of the post. That file sends a pass repeating a standing close-out on to `${CLAUDE_SKILL_DIR}/references/close-out.md`, which rewrites the comment in place.
+Read `${CLAUDE_SKILL_DIR}/references/post.md` for the body file name, the body shape, the PR body block, the marker every body carries, and the scans ahead of the post, and `${CLAUDE_SKILL_DIR}/references/body-variants.md` for the Testing and reviewer blocks and the close-out bodies. That file sends a pass repeating a standing close-out on to `${CLAUDE_SKILL_DIR}/references/close-out.md`, which rewrites the comment in place.
 
 ## Step 5: output
 

package/claude/skills/review-pr/references/body-variants.md

@@ -0,0 +1,52 @@
+---
+title: Body variants for the review comment
+description: The Testing and reviewer blocks a pass may carry, and the close-out bodies for a pass carrying nothing, only minors, a withdrawal, or only answered reviewer requests
+---
+
+# Body variants
+
+Step 4 of `review-pr`, beside `post.md`. That file names the body file and gives the shape a finding-carrying pass takes, and this one holds the blocks and close-outs that vary it.
+
+A Testing box the Step 3 check raised goes in a `**Testing**` block placed after the file blocks, one bullet per box, each quoting the box and naming what would drive it. It carries no severity and enters no count, and it is still something owed, so a pass carrying one takes `## Review` and the full body rather than either ✅ line. Say so on the summary line as `plus N testing question(s)`, since the three counts read as zero and would otherwise report the pass as silent.
+
+```markdown
+**Testing**
+
+- `- [ ] <the box as written>` names no capability the agent lacks. `sandbox/run.sh <arm>` drives it. Was there a reason to leave it?
+```
+
+Keep it to the boxes the check raised. Restating a box whose stated requirement holds teaches the branch author to skip the block.
+
+Every `## For the reviewer` bullet Step 3 read goes in a `**For the reviewer**` block placed after the Testing block, one bullet per request, each followed by its answer or, where the pass could not answer it, by what would settle it. It carries no severity and enters no count.
+
+An unanswered bullet is owed the same way an unanswered Testing box is, so a pass carrying one takes `## Review` and the full body rather than either ✅ line. A bullet the pass answered is not owed, since the answer is discharged in the same comment that carries it. A pass still posting a numeric summary line, because a finding, a Testing question, or an unanswered bullet already forces one, says so there as `plus N reviewer request(s)`. The all-answered close-out below carries the block in place of that line and needs no addition to it.
+
+```markdown
+**For the reviewer**
+
+- Confirm the 401 and 403 split reads correctly for the public API. Confirmed — `AuthService.authenticate()` returns 401 for an expired token and 403 for a missing scope, and both paths are covered under `## Testing`.
+```
+
+A pass carrying nothing at all takes `## Review closed` and a short body, with the footer line included either way. On a first pass, post `✅ No findings. Reviewed against project docs and the board.` On a later pass, post `✅ Prior findings addressed. Re-reviewed <short-sha>, N commits since the prior pass.`
+
+A pass carrying only minors is an ordinary finding-carrying pass, so it takes the open heading and the full shape rather than either short line, since the minors have to be readable and neither line reports them. A pass carrying only Testing questions, or only an unanswered reviewer request, takes the same route for the same reason. Keep whichever scope sentence the pass owes on the summary line:
+
+```markdown
+## Review
+
+0 critical, 0 should-fix, Z minor. Reviewed against project docs and the board.
+
+**`path/to/file.ext`**
+
+- **minor** ([line 12](<repo-url>/blob/<headRefOid>/path/to/file.ext#L12)): finding, and the fix it wants.
+
+🤖 Reviewed by Claude Code
+
+<!-- review-pr: commit=<headRefOid> read-at=<read-at> -->
+```
+
+A pass that closed by withdrawing a finding rather than by reading its fix takes neither ✅ line, per the withdrawal rule in Step 3. Both claim a fix landed, and the second names it, so posting either over a withdrawal credits work nobody did on the one comment a reader treats as the verdict. Write the withdrawal and the fact that settled it in place of the canned line, keeping the heading and the footer.
+
+A pass whose only content is a `## For the reviewer` block with every bullet answered, and that owes nothing else, takes the same shape: `## Review closed`, the block in place of the canned line, and the footer. The heading reports what the branch author still owes rather than what the pass did, and an answer discharged in the same comment owes nothing back.
+
+Post a close-out even when there is nothing to report. A review left with no closing comment reads as one nobody answered.

package/claude/skills/review-pr/references/key-changes.md

@@ -0,0 +1,16 @@
+---
+title: Key changes check
+description: How review-pr Step 3 tests what the pull request body's Key Changes section claims against the diff, reading each field the canon pr key-changes record carries and which one becomes a finding
+---
+
+# Test the Key Changes claims
+
+Part of Step 3 of `review-pr`. The session reads this file after the `## Testing` boxes and before the `## For the reviewer` bullets.
+
+Test what `## Key Changes` claims against the diff it describes, with `canon pr key-changes <number> --json`. This repository squash-merges, so that section becomes the commit message and the record on the trunk once the branch is gone, which is the same thing a stale ticked box corrupts. Branch on the record rather than on the exit code, which a shell function wrapping `canon` can flatten to zero.
+
+Read `unmet` as a `should-fix` finding under the same `**PR body**` block the stale box takes, one entry per path, quoting the bullet the record carries on `preview` and naming the `head` the comparison ran at. Read the bullet before filing it, since one class survives the reader: a bullet citing where something is defined while claiming an edit elsewhere, which puts a real path in the claim region and points the change at a locative the path does not name. Report that as the class rather than as a stale claim. A body is edited between pushes, so the reading is true at that commit and can be false a minute later. Read `unnamed` for yourself and raise nothing off the count. The class still covers a real omission and equally a generated asset or a regenerated index that earns no bullet, and the entries the reader can name as owing none are already held apart under `incidental`. Open the section and confirm no bullet names the file before putting a single one to the author, because this instruction has sent the question to three pull requests in one day over bullets that had named the files all along, and one of those authors added bullets nobody needed. Report `unresolved` and `incidental` nowhere: the first was judged in neither direction and the second owes no bullet, so neither says anything about the body.
+
+A `reason` of `no-claims` means the reader resolved no path out of a section that exists, which is the extractor failing over prose rather than the body being wrong. Say so and raise nothing. `no-section` is the body carrying no such heading, which is a finding only where the pull request template asks for one.
+
+Compose this on the body read Step 4 already performs rather than opening a second one. That step scans the title and body for a leaked phase label, and both reads answer from the same text at the same head.