@erclx/canon 5.41.0 → 5.42.0

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

@@ -33,15 +33,23 @@ A branch carrying merge commits of its own, such as a fan-in integrator's, rebas
 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
 
-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.
+### A hunk needing a decision
 
-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.
+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
+
+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.
+
+- 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
 

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

@@ -7,51 +7,68 @@ description: Which external review patterns this skill adopted, which it decline
 
 External sources were read and filtered rather than imported. This file is the record. A later session extending the skill adds to it rather than re-arguing an item already settled here.
 
+The `addyosmani/agent-skills` citations below all pin commit `addyosmani/agent-skills@2686b620`.
+
 ## Adopted
 
 ### Design and scope
 
 **The design procedure.** The nine ordered steps under the design axis draw on four sources, each restated without a language, a framework, or a transport so the walk holds on any stack.
 
-- Ousterhout's deep modules, information hiding, and pass-through methods ([A Philosophy of Software Design](https://web.stanford.edu/~ouster/cgi-bin/book.php)): the step asking what each unit hides and flagging a unit that passes its arguments straight through.
-- Parnas's criterion that a module boundary hides a decision likely to change ([On the Criteria To Be Used in Decomposing Systems into Modules](https://dl.acm.org/doi/10.1145/361598.361623)): the opening step naming the next likely change and counting what it touches.
-- Beck's design rules as Fowler records them, especially no duplication and fewest elements ([BeckDesignRules](https://martinfowler.com/bliki/BeckDesignRules.html)): the one-place step and the step matching each pattern to a problem the code has today.
-- Google's reviewer guide on design, complexity, and over-engineering ([What to look for in a code review](https://google.github.io/eng-practices/review/reviewer/looking-for.html)): the frame for the whole walk, and the reason a speculative abstraction is a finding.
+| Source                                                                                                                                                                               | Step it backs                                                                               |
+| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------- |
+| Ousterhout's deep modules, information hiding, and pass-through methods, [A Philosophy of Software Design](https://web.stanford.edu/~ouster/cgi-bin/book.php)                        | Asking what each unit hides, and flagging a unit that passes its arguments straight through |
+| Parnas's criterion that a boundary hides a decision likely to change, [On the Criteria To Be Used in Decomposing Systems into Modules](https://dl.acm.org/doi/10.1145/361598.361623) | The opening step, naming the next likely change and counting what it touches                |
+| Beck's design rules as Fowler records them, especially no duplication and fewest elements, [BeckDesignRules](https://martinfowler.com/bliki/BeckDesignRules.html)                    | The one-place step, and matching each pattern to a problem the code has today               |
+| Google's reviewer guide on design, complexity, and over-engineering, [What to look for in a code review](https://google.github.io/eng-practices/review/reviewer/looking-for.html)    | The frame for the whole walk, and the reason a speculative abstraction is a finding         |
 
 The procedure stays in the body rather than a reference, since every review reads the design axis and a reference would cost a read on every run.
 
-**Change sizing as a split.** Google's [small CLs](https://google.github.io/eng-practices/review/developer/small-cls.html) asks for one self-contained change. Adopted as the scope check that names a split when two concerns could land as two changes. From `addyosmani/agent-skills@2686b620`, `skills/code-review-and-quality/SKILL.md`, the same check.
+### Scope checks
 
-**Relocate versus reduce.** From the same `code-review-and-quality` skill: a refactor counts the concepts a reader must hold before and after. Adopted as the scope check that reports moved complexity as moved.
+Three scope checks come from outside sources, each adopted as one check.
 
-**Chesterton's Fence.** From `addyosmani/agent-skills@2686b620`, `skills/code-simplification/SKILL.md`: read why code exists before removing it. Adopted as the scope check that reads `git blame` and the commit that added a removed path before calling it dead.
+- **Change sizing as a split.** Google's [small CLs](https://google.github.io/eng-practices/review/developer/small-cls.html) and `skills/code-review-and-quality/SKILL.md` ask for one self-contained change, so the check names a split when two concerns could land apart.
+- **Relocate versus reduce.** The same `code-review-and-quality` skill counts the concepts a reader holds before and after a refactor, so moved complexity reports as moved.
+- **Chesterton's Fence.** `skills/code-simplification/SKILL.md` reads why code exists before removing it, so the check reads `git blame` and the adding commit before calling a path dead.
 
 ### Guard the bar
 
-From `addyosmani/agent-skills@2686b620`, `skills/constraint-driven-development/SKILL.md`: a change must not pass by weakening the constraint it has to meet. Adopted as its own axis after tests, listing the moved threshold, the skipped or hollowed test, the inline suppression, the excluded path, the throwing stub, the empty catch, and the new config exception. The clause accepting a suppression whose stated reason holds is this skill's own, since a legitimate suppression with its reason beside it would otherwise report noise the procedures' filter then drops.
+From `skills/constraint-driven-development/SKILL.md`, a change must not pass by weakening the constraint it has to meet. Adopted as its own axis after tests.
+
+- It lists the moved threshold, the skipped or hollowed test, the inline suppression, the excluded path, the throwing stub, the empty catch, and the new config exception
+- The clause accepting a suppression whose stated reason holds is this skill's own, since a legitimate one would otherwise report noise the procedures then drop
 
 ### Performance
 
-From `addyosmani/agent-skills@2686b620`, `skills/code-review-and-quality/SKILL.md` for the axis itself, a call inside a loop and an unbounded fetch, and `skills/performance-optimization/SKILL.md` for keep or revert: measure before and after the same way, and a neutral result argues for removing the added complexity. The repeated-run requirement against noise is stated here so one run on each side reads as an anecdote.
+The axis itself, a call inside a loop and an unbounded fetch, comes from `skills/code-review-and-quality/SKILL.md`. Keep or revert comes from `skills/performance-optimization/SKILL.md`.
+
+- Measure before and after the same way, and a neutral result argues for removing the added complexity
+- The repeated-run requirement against noise is stated here, so one run on each side reads as an anecdote
 
 ### Security additions
 
-From `addyosmani/agent-skills@2686b620`, `skills/security-and-hardening/SKILL.md`: the threat model first and the derived-path rule. Adopted as the opening step of `references/security.md`, which names who supplies each input and what the code can reach before any class is read, and as the destructive-operations class, which asks for the empty-value collapse, the glob or symlink escape, the missing root check, and no read of what is there before the call. Both stay stack-neutral. No red run measures them, so they ship as lifts rather than as an answer to a miss.
+From `skills/security-and-hardening/SKILL.md`, the threat model first and the derived-path rule. Both stay stack-neutral, and no red run measures them, so they ship as lifts rather than as an answer to a miss.
+
+- The threat model is the opening step of `references/security.md`, naming who supplies each input and what the code can reach before any class is read
+- The derived-path rule is the destructive-operations class, asking for the empty-value collapse, the glob or symlink escape, the missing root check, and no read before the call
 
 ### Closing sections
 
-The excuses, red flags, and closing checklist follow the practice skill shape every practice skill in this toolkit carries, taken from `addyosmani/agent-skills@2686b620`, [`docs/skill-anatomy.md`](https://github.com/addyosmani/agent-skills/blob/2686b620fc1fed2e8f60c704839c766b8594c6b6/docs/skill-anatomy.md). Each excuse row rebuts a reason a review stops at the hunk, such as passing tests against a test the diff skipped, rather than an objection nobody raised.
+The excuses, red flags, and closing checklist follow the shape every practice skill in this toolkit carries, from [`docs/skill-anatomy.md`](https://github.com/addyosmani/agent-skills/blob/2686b620fc1fed2e8f60c704839c766b8594c6b6/docs/skill-anatomy.md). Each excuse row rebuts a reason a review stops at the hunk, such as passing tests against a test the diff skipped.
 
 ## Declined
 
-**Google's approval standard.** "Approve a change once it definitely improves the overall code health" is a grading rule. Grading and posting belong to the procedures that load this skill, which each own a severity ladder, so the standard stays out of the body.
-
-**A fixed line count for sizing.** Google's small-CL page sets no hard limit, and one concern regularly runs past a hundred lines here. A number would fire on nearly every branch, so the split is stated by concern instead.
+Each item names what was declined and the reason it stays out.
 
-**Named structural remedies as a catalog.** A list of refactorings to propose reads as a menu a session fills in. A design finding states the cost, and the remedy is the author's.
+- **Google's approval standard.** "Approve a change once it definitely improves the overall code health" is a grading rule, and grading belongs to the procedures that load this skill.
+- **A fixed line count for sizing.** Google's page sets no hard limit, and one concern regularly runs past a hundred lines here, so the split is stated by concern.
+- **Named structural remedies as a catalog.** A list of refactorings reads as a menu a session fills in. A design finding states the cost, and the remedy is the author's.
+- **STRIDE and abuse-case tests as a procedure.** They belong to a design session, and the threat-model opening takes the one step a diff supports.
+- **The web and database tables from `performance-optimization`.** They name a stack, and the axis stays stack-neutral until a target asks for one.
 
-**A dependency upgrade reference.** From `addyosmani/agent-skills@2686b620`, `skills/code-review-and-quality/SKILL.md`: read the changelog across the range, one dependency per change, and the lockfile diff. Declined because the seeded upgrade is not a miss. The body without such a reference reported the planted major bump and the install script in the lockfile on the second of two runs, which passed the assertion naming them. Revisit when a run on a changed lockfile misses what a reference would have named.
+### A dependency upgrade reference
 
-**STRIDE and abuse-case tests as a procedure.** They belong to a design session rather than a diff read, and the threat-model opening in the security reference takes the one step a diff supports, naming who supplies each input.
+`skills/code-review-and-quality/SKILL.md` reads the changelog across the range, one dependency per change, and the lockfile diff. Declined because the seeded upgrade is not a miss. The body without such a reference reported the planted major bump and the lockfile install script on the second of two runs, passing the assertion.
 
-**The web and database tables from `performance-optimization`.** They name a stack, and the axis stays stack-neutral until a target asks for a per-stack reference.
+Revisit when a run on a changed lockfile misses what a reference would have named.

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

@@ -8,13 +8,48 @@ Before the classes, name from the diff who supplies each input and what the code
 
 ## Classes to check
 
-- **Shell and command injection.** A value from an argument, an environment variable, a file, or a network response reaching a shell: through `eval`, an unquoted expansion, a string built into a command, or a subprocess call that takes a single command string. Quoting the variable at the call site is the fix to look for.
-- **Path traversal in a file write.** A path built from outside input and written without being resolved and checked against the directory it must stay inside. A `..` segment, an absolute path, and a symlink inside the target each escape a naive join.
-- **Destructive operation on a derived path.** A delete, overwrite, move, or clean whose path is built from a variable, a config value, or a listing. Look for the empty or unset value that collapses it to a root, a glob or a symlink that carries it outside the folder it was meant for, no check that the resolved path sits at least one level below an expected root, and no read of what is there, owned by this tool or not, before the call. The fix to look for is resolve, require the root, then act. A write escaping its folder is path traversal. When a finding fits both, name the class whose fix applies.
-- **Secrets and personal data leaving the process.** A token, a key, a password, or personal data reaching a log line, an error message, a session transcript, a published page, a pull request comment, or a sync to a remote. Check what a debug line prints and what a verbose flag adds.
-- **Supply chain.** One-shot package execution of an unpinned version, which runs whatever the registry serves that day. A new dependency, and what its install scripts run. A lockfile that changes without a manifest change.
-- **Time of check to time of use on a file write.** An existence or permission check followed by a write to the same path in a later step, and a predictable name in a shared temporary directory. Another process can swap the path in between.
-- **Insecure defaults a consumer installs.** A config, a scaffold, or a seed that turns a check off, opens a port on every interface, grants a broad permission, or ships a placeholder secret. The consumer inherits the default without reading it.
+Each class names the sink, the path in, and the fix to look for.
+
+### Shell and command injection
+
+A value from an argument, an environment variable, a file, or a network response reaches a shell.
+
+- The paths in are `eval`, an unquoted expansion, a string built into a command, and a subprocess call taking a single command string
+- Quoting the variable at the call site is the fix to look for
+
+### Path traversal in a file write
+
+A path built from outside input is written without being resolved and checked against the directory it must stay inside. A `..` segment, an absolute path, and a symlink inside the target each escape a naive join.
+
+### Destructive operation on a derived path
+
+A delete, overwrite, move, or clean takes a path built from a variable, a config value, or a listing. The fix to look for is resolve, require the root, then act.
+
+- An empty or unset value that collapses the path to a root
+- A glob or a symlink that carries it outside the folder it was meant for
+- No check that the resolved path sits at least one level below an expected root
+- No read of what is there, owned by this tool or not, before the call
+- A write escaping its folder is path traversal. When a finding fits both, name the class whose fix applies.
+
+### Secrets and personal data leaving the process
+
+A token, a key, a password, or personal data reaches a log line, an error message, a session transcript, a published page, a pull request comment, or a sync to a remote. Check what a debug line prints and what a verbose flag adds.
+
+### Supply chain
+
+Three shapes bring in code nobody reviewed.
+
+- One-shot package execution of an unpinned version, which runs whatever the registry serves that day
+- A new dependency, and what its install scripts run
+- A lockfile that changes without a manifest change
+
+### Time of check to time of use on a file write
+
+An existence or permission check is followed by a write to the same path in a later step, or a predictable name sits in a shared temporary directory. Another process can swap the path in between.
+
+### Insecure defaults a consumer installs
+
+A config, a scaffold, or a seed turns a check off, opens a port on every interface, grants a broad permission, or ships a placeholder secret. The consumer inherits the default without reading it.
 
 ## Excluded
 

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

@@ -20,7 +20,13 @@ gh api --paginate 'repos/{owner}/{repo}/issues/<number>/comments?per_page=100' -
 
 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 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:
+Flag the change as shipping no screenshot when it paints and the pull request carries any of three comment shapes.
+
+- No marked comment at all
+- A marked comment with no comparison, meaning no `**Base:**` line and no `<details>` table
+- Only a checklist posted alone, since `## Evidence` opens every marked comment and the heading alone never means screenshots are present
+
+Then decide how to raise it by whether the project keeps captures, 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 +51,11 @@ 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, and a view or flat block whose cases are all added has no base column at all. A view row holds one case per theme cell, so a width row names two images where a flat row names one. Read the URL out of the `src=` of each `<img>`, or out of `![](` in a comment posted before the embed changed.
+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.
+
+- Read the URL out of the `src=` of each `<img>`, or out of `![](` in a comment posted before the embed changed
+- A `*(new)*` base cell has no before image, and a view or flat block whose cases are all added has no base column at all
+- A view row holds one case per theme cell, so a width row names two images where a flat row names one
 
 ## How many to open
 
@@ -59,21 +69,26 @@ A second theme earns a read only when the diff touches a color token. Name the s
 
 ## Comparing
 
-Check each opened image against the layout its checklist box claims, and check the tokens the image makes visible, being color, type scale, and spacing, against the stylesheet `canon/DESIGN.md`'s lead names, and its component rules against the record itself.
+Check each opened image against the layout its checklist box claims. A finding names the checklist box or design-file line the image breaks, never a taste.
 
-Read the width and theme from whatever the image path carries, and fix no width list, since which widths matter belongs to the project. Skip the design file comparison silently when the project has none.
-
-A finding names the checklist box or design-file line the image breaks, never a taste.
+- Check the visible tokens, being color, type scale, and spacing, against the stylesheet `canon/DESIGN.md`'s lead names
+- Check its component rules against the record itself, and skip the design file comparison silently when the project has none
+- Read the width and theme from whatever the image path carries, and fix no width list, since which widths matter belongs to the project
 
 ## The checklist
 
 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, 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.
+- 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 app and not the 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. 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
 
-A local review has no comment to read. Read each changed image under an `evidence/` path segment from the working tree, and its base side with `git show <base>:<path>`. Read the checklist handoff at `.canon/tmp/handoff/ui-checklist/<slug>.md` at the main worktree root when it exists. A painting change with no changed evidence image takes the flag from the first section, decided by the same `git ls-tree` test.
+A local review has no comment to read, so it reads the tree.
+
+- Read each changed image under an `evidence/` path segment from the working tree, and its base side with `git show <base>:<path>`
+- Read the checklist handoff at `.canon/tmp/handoff/ui-checklist/<slug>.md` at the main worktree root when it exists
+- A painting change with no changed evidence image takes the flag from the first section, decided by the same `git ls-tree` test

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

@@ -26,12 +26,12 @@ A thread then reads as `## Review`, the worker's `## Review response` from `revi
 
 Both headings anchor as a section distinct from human threads. The full set is eight headings across four families, stated here once so `role-orchestrator`'s poll and every reply-posting skill cite it rather than carry a copy.
 
-| Family   | Headings                                                     | Owner                                                                    |
-| -------- | ------------------------------------------------------------ | ------------------------------------------------------------------------ |
-| Review   | `## Review`, `## Review closed`                              | This skill alone                                                         |
-| Reply    | `## Review response`, `## Rebase`, `## Post-review findings` | `review-address`                                                         |
-| Evidence | `## Evidence`                                                | `canon pr evidence`, through `git-pr` and `git-followup`                 |
-| UI       | `## UI review`, `## UI review closed`                        | `review-ui`, posted as a review beside this one and read by nothing here |
+| Family   | Headings                                                     | Owner                                                                       |
+| -------- | ------------------------------------------------------------ | --------------------------------------------------------------------------- |
+| Review   | `## Review`, `## Review closed`                              | This skill alone                                                            |
+| Reply    | `## Review response`, `## Rebase`, `## Post-review findings` | `review-address`                                                            |
+| Evidence | `## Evidence`                                                | `canon pr evidence`, through `pr-evidence` from `git-pr` and `git-followup` |
+| UI       | `## UI review`, `## UI review closed`                        | `review-ui`, posted as a review beside this one and read by nothing here    |
 
 - The reply headings in order answer a finding, report a stale branch resolved without one, and carry a finding a worker produced after a close-out
 - `## Evidence` answers no comment on the thread, so the poll leaves it out of the unclassified count rather than reading it as a reply owing a re-review

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

@@ -7,7 +7,13 @@ description: The Testing and reviewer blocks a pass may carry, and the close-out
 
 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.
+## The testing block
+
+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 owed, so the pass 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 a silent pass
+- Keep it to the boxes the check raised, since restating a box whose stated requirement holds teaches the author to skip the block
 
 ```markdown
 **Testing**
@@ -15,11 +21,14 @@ A Testing box the Step 3 check raised goes in a `**Testing**` block placed after
 - `- [ ] <the box as written>` names no capability the agent lacks. `canon sandbox run <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.
+## The reviewer 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.
+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 is followed by its answer, or by what would settle it where the pass could not answer. 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.
+- An unanswered bullet is owed like an unanswered Testing box, so the pass takes `## Review` and the full body
+- An answered bullet is not owed, since the answer is discharged in the same comment that carries it
+- A pass already posting a numeric summary line adds `plus N reviewer request(s)` to it
+- The all-answered close-out below carries the block in place of that line and needs no addition
 
 ```markdown
 **For the reviewer**
@@ -27,9 +36,16 @@ An unanswered bullet is owed the same way an unanswered Testing box is, so a pas
 - 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.`
+## Close-out bodies
+
+A pass carrying nothing at all takes `## Review closed` and a short body, with the footer line included either way. Post a close-out even with nothing to report, since a review left with no closing comment reads as one nobody answered.
+
+- 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:
+### Only minors
+
+A pass carrying only minors is an ordinary finding-carrying pass, so it takes the open heading and the full shape, since neither short line reports the minors. A pass carrying only Testing questions or only an unanswered reviewer request takes the same route. Keep whichever scope sentence the pass owes on the summary line:
 
 ```markdown
 ## Review
@@ -45,8 +61,12 @@ A pass carrying only minors is an ordinary finding-carrying pass, so it takes th
 <!-- 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 withdrawal
+
+A pass that closed by withdrawing a finding rather than reading its fix takes neither ✅ line, per the withdrawal rule in Step 3. Both claim a fix landed, so either credits work nobody did on the 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.
+### Only answered reviewer requests
 
-Post a close-out even when there is nothing to report. A review left with no closing comment reads as one nobody answered.
+A pass whose only content is a `## For the reviewer` block with every bullet answered, owing nothing else, takes `## Review closed`, the block in place of the canned line, and the footer. The heading reports what the author still owes, and an answer discharged in the same comment owes nothing back.

package/claude/skills/review-pr/references/close-out.md

@@ -9,22 +9,37 @@ Part of Step 4 of `review-pr`, reached only on the branch `post.md` names. Every
 
 When `<prior-heading>` from Step 2 reads `## Review closed` and this pass carries nothing owed, the thread already holds this verdict. Replace the standing close-out rather than posting a second one beside it.
 
+## The rewrite
+
 Resolve its numeric id off the REST listing, keeping the newest match across every page:
 
 ```bash
 gh api --paginate 'repos/{owner}/{repo}/pulls/<number>/reviews?per_page=100' --jq '.[] | select((.body // "") | split("\n")[0] | rtrimstr("\r") == "## Review closed") | .id' | tail -n 1
 ```
 
-Write the replacement body to `<body-file>`, the name `post.md` already derived at the top of Step 4, keeping the heading and the footer and naming what this pass covered on the scope line in place of what the old one covered. Derive that name the same way whichever path reached here, since the guard reads `<prior-heading>` alone and a repeated head resolves the third segment as usual. The folder then gains a record of every covered head rather than losing the one the standing comment named. Then replace the comment:
+Write the replacement body to `<body-file>`, the name `post.md` already derived at the top of Step 4. Keep the heading and the footer, and name what this pass covered on the scope line in place of what the old one covered.
+
+- Derive that name the same way whichever path reached here, since the guard reads `<prior-heading>` alone and a repeated head resolves the third segment as usual
+- The folder then gains a record of every covered head rather than losing the one the standing comment named
 
 ```bash
 gh api -X PUT repos/{owner}/{repo}/pulls/<number>/reviews/<review-id> -F body=@<body-file>
 ```
 
-`PUT` keeps the comment's timestamp and its position in the thread, so the verdict stays where a reader already found it and the thread gains no second entry. A submitted review cannot be deleted, which is why this rewrites the standing comment rather than posting a fresh one.
+`PUT` keeps the comment's timestamp and its position in the thread, so the verdict stays where a reader already found it. A submitted review cannot be deleted, which is why this rewrites the standing comment rather than posting a fresh one.
+
+## When the guard fires
+
+The guard fires on `## Review closed` alone.
+
+- Two open passes carry different findings and both are worth reading, so a repeated `## Review` posts normally
+- A pass carrying anything owed posts normally under `## Review`, so a finding raised after a close-out is never swallowed by the guard
+
+## What the PUT leaves pinned
 
-The guard fires on `## Review closed` alone. Two open passes carry different findings and both are worth reading, so a repeated `## Review` posts normally. A pass carrying anything owed posts normally too, under `## Review`, which is what keeps a finding raised after a close-out from being swallowed by the guard that exists for a silent one.
+`PUT` leaves the review's `commit.oid` pinned at the commit the close-out was first submitted against. Step 2's `<prior-oid>` and the prior commit `poll.ts` derives would read too wide a range from it, and the poll's `SEEN` branch, firing on `prior` equalling the head, could never be reached.
 
-The rewrite used to cost the review's `commit.oid`, which `PUT` leaves pinned at the commit the standing close-out was first submitted against. Step 2's `<prior-oid>` and the prior commit `poll.ts` derives both read that field, so the next pass read a range wider than its delta, and the poll's `SEEN` branch, which fires on `prior` equalling the head, could never be reached at all: an out-of-band pass reported as `MOVED` for the rest of the pull request's life.
+The marker answers both, because `PUT` replaces the body and the marker is in it. It carries the commit this pass read, and every reader takes it in preference to the pinned field.
 
-The marker closes both, because `PUT` replaces the body and the marker is in it. The rewritten close-out carries the commit this pass read rather than the one the comment was first submitted against, and every reader now takes that in preference to the pinned field. The one thing `PUT` still cannot move is `submittedAt`, which stays at the original submission and is what the poll's age test reads, so a rewritten close-out ages from when it first landed rather than from when it was last rewritten. That is the correct reading for a thread waiting on a human, which is the question the age test asks.
+- `submittedAt` still stays at the original submission, and the poll's age test reads it
+- A rewritten close-out therefore ages from when it first landed, which is the right reading for a thread waiting on a human

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

@@ -7,10 +7,34 @@ description: How review-pr Step 3 tests what the pull request body's Key changes
 
 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.
+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 on the trunk once the branch is gone, the same record a stale ticked box corrupts.
 
-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.
+## Reading each field
 
-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.
+Branch on the record rather than on the exit code, which a shell function wrapping `canon` can flatten to zero. Each field the record carries takes its own reading.
+
+| Field        | Reading                                                                                                                             |
+| ------------ | ----------------------------------------------------------------------------------------------------------------------------------- |
+| `unmet`      | a `should-fix` finding under the `**PR body**` block the stale box takes, one per path, quoting the `preview` bullet and the `head` |
+| `unnamed`    | read for yourself and raise nothing off the count                                                                                   |
+| `unresolved` | reported nowhere, since it was judged in neither direction                                                                          |
+| `incidental` | reported nowhere, since it owes no bullet                                                                                           |
+
+### Before filing an unmet path
+
+Read the bullet before filing it, since one class survives the reader. A bullet citing where something is defined while claiming an edit elsewhere puts a real path in the claim region, so report that as the class rather than as a stale claim.
+
+A body is edited between pushes, so the reading is true at the `head` it names and can be false a minute later.
+
+### Before raising an unnamed path
+
+The `unnamed` class covers a real omission and equally a generated asset or a regenerated index that earns no bullet. Open the section and confirm no bullet names the file before putting one to the author.
+
+This instruction once sent the question to three pull requests in one day over bullets that had named the files all along, and one author added bullets nobody needed.
+
+## Refusals
+
+- `no-claims` means the reader resolved no path out of a section that exists, the extractor failing over prose, so say so and raise nothing
+- `no-section` means the body carries no such heading, 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.