@erclx/canon 5.46.0 → 5.47.0

package/claude/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "canon",
   "description": "Runs your agent's work and keeps its code good, on one setup for every repo.",
-  "version": "5.46.0",
+  "version": "5.47.0",
   "author": {
     "name": "Eric Le",
     "url": "https://github.com/erclx"

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

@@ -58,6 +58,7 @@ A missing tracking ref is not a guard, since an open pull request proves the bra
    - Read the live title and body with `gh api repos/{owner}/{repo}/pulls/<number> --jq '{html_url, title, body}'`. Update the body with `gh api -X PATCH repos/{owner}/{repo}/pulls/<number> -F body=@<file> --silent` when the new commit changes scope, writing the new body to `<file>` first, and the title with `gh api -X PATCH repos/{owner}/{repo}/pulls/<number> -f title="<title>" --silent` when the scope shifted enough to make it inaccurate.
    - A fix commit answering a review changes what shipped exactly as much as an ordinary followup does, so the sync cannot wait on the invocation or the comment count below.
    - A body a person edited by hand between rounds gets no special handling: judge it against the tree the same way regardless of who wrote it last, since a hand-edit the fix commit has made stale is the exact drift this sync exists to close.
+   - Carry a `UI pass` line marked `<!-- pr-ui-pass -->` into any rewritten body unchanged, since `canon pr tick` owns it and a dropped marker defeats the reset on a new head.
 8. Route on the invocation and the comment count for the reply alone.
    - When invoked with `reply-owned`, skip this step: the caller posts its own reply.
    - Otherwise, if the count is above zero, the followup addresses review feedback: write a one-line summary of the fix to `.canon/tmp/pr/followup/summary-<number>.md` in its own call, run `canon labels scan --body-file .canon/tmp/pr/followup/summary-<number>.md` against it, which applies the rule in `${CLAUDE_SKILL_DIR}/../git-pr/references/publish.md`, then post it with `gh api -X POST repos/{owner}/{repo}/issues/<number>/comments -F body=@.canon/tmp/pr/followup/summary-<number>.md --silent`. A hook on `Bash` runs the same scan on that body file and denies the post on a hit, and it refuses an inline `-f body=` value, so the body goes through a file. The `pull_request` check the git-pr surface carries triggers on a push or an open rather than a plain edit, so neither this comment nor the title and body step 7 synced reaches it.

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

@@ -7,13 +7,13 @@ description: What pull request generation is for, the gaps it closes, and what i
 
 ## Gap
 
-Without this skill, a pull request body is written from memory rather than the diff, so it describes the intent and omits what the work became. Testing boxes get ticked from intent, a second push errors or opens a duplicate, and banned characters survive into a body the hook never sees.
+Without this skill, a pull request body is written from memory rather than the diff, so it describes the intent and omits what the work became. Testing boxes get ticked from intent, a second push errors or opens a duplicate, and banned characters survive into a body the hook never sees. The body grows into a wall nothing measures.
 
 Every pull request lands unlabelled, so a merged list cannot be filtered by surface. A head-branch lookup resolves a reused name to the merged pull request and rewrites it. A pull request changing a rendered surface reaches review with no screenshots, and a hand-written `Closes` line closes an issue on a middle slice or misses one the task names.
 
 ## Must
 
-- The title and body come from the commits and the diff against main with lockfiles excluded, scanned for banned characters and phase labels, and every ticked box records a check this run executed
+- The title and body come from the commits and the lockfile-free diff against main, scanned for banned characters, phase labels, and density, and every ticked box records a check this run executed
 - A follow-up run edits the one open pull request on the current head and default base, resolved once, and every write first proves that pull request's head and open state
 - Closing lines come from `canon tasks closes`, one `Closes #NNN` per issue on the task's last slice only, with the scan failing a body that disagrees
 - Labels come from the paths the branch changed against a map the project declares, applied after the pull request exists, with a refused label reported

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

@@ -105,7 +105,7 @@ Drop `--closes` when the closes step skipped a refusal, since no list was decide
 
 ### Reading the scan
 
-Branch on the JSON record rather than the exit code, since a shell function wrapping `canon` can flatten a non-zero exit to 0. Stop and fix the title or body on any key below, and do not proceed to `### Final command` until a re-run comes back clean on all eight.
+Branch on the JSON record rather than the exit code, since a shell function wrapping `canon` can flatten a non-zero exit to 0. Stop and fix the title or body on any key below, and do not proceed to `### Final command` until a re-run comes back clean on all nine.
 
 | Key                 | Fix                                                                                  |
 | ------------------- | ------------------------------------------------------------------------------------ |
@@ -117,6 +117,7 @@ Branch on the JSON record rather than the exit code, since a shell function wrap
 | `sections`          | Rename or drop each heading in `outside`, and add each required heading in `missing` |
 | `missingClosures`   | Add a `Closes #NNN` line for each number listed                                      |
 | `strayClosures`     | Delete the closing keyword for each number listed                                    |
+| `density`           | Regroup or split the named section per `## Formatting` in `pr.md`, keeping each path |
 
 Leave `cutsRelease` and `semverTags` alone, since a release-please pull request legitimately carries version references its own fixed shape explains.
 

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

@@ -52,8 +52,17 @@ A body describes the new behavior and nothing the diff or the commits already sa
 
 ## Sections
 
-- `## Summary`: 1-2 sentences following `<Action Verb> <Direct Object> to <Result>`, expand for clarity if needed
-- `## Key changes`: name actual files, functions, or modules (e.g., `AuthService.verify()` not "auth handler"). Always use bullet points, never prose.
+- `## Summary`: one paragraph following `<Action Verb> <Direct Object> to <Result>`, then the closing lines
+- `## Key changes`: bullets only, one change each, naming actual files, functions, or modules (e.g., `AuthService.verify()` not "auth handler")
+- Name every changed path in a Key changes bullet. A trim may cut a clause and never a path, since `canon pr key-changes` reports a path no bullet claims.
+
+### Key changes groups
+
+Past 5 bullets, group Key changes under bold labels, 5 bullets a group at most.
+
+- A label sits on its own line, names the area a reviewer opens together, and ends with no period
+- Write a label in plain words, since a code span inside bold renders unbolded
+- Open each group on a bullet, never on prose
 
 ### Closing lines
 
@@ -61,10 +70,12 @@ The closing lines end `## Summary`, one `Closes #NNN` per issue and no trailing
 
 ### Context section
 
-`## Technical context` is optional and carries 1-2 lines of architectural reasoning explaining why, not what.
+`## Technical context` is optional and says why, naming the decisions the code can't show and any shortcoming of the approach.
 
 - Omit Technical context for docs, config, or trivial changes
-- Use bullet points for multiple reasons, one sentence for a single reason
+- Take one form per section, never bullets and paragraphs mixed
+- Use bullets when every reason fits one sentence under 200 characters
+- Otherwise write one paragraph per decision, opening on a bold lead-in that ends with a period and runs into the paragraph
 
 ### Testing section
 
@@ -72,6 +83,7 @@ The closing lines end `## Summary`, one `Closes #NNN` per issue and no trailing
 
 - Omit Testing for docs, config, or trivial sync changes
 - Use checkboxes, never prose. See Testing discipline for which box gets ticked.
+- Write one box per command, pointing at a test file rather than listing its cases
 
 ### Reviewer section and visuals
 
@@ -90,6 +102,8 @@ The closing lines end `## Summary`, one `Closes #NNN` per issue and no trailing
 - A ticked box describes the tree as it stands. A later commit removing or replacing what it names makes the box false.
 - The branch that made that commit corrects the box in the same pass, as with any other stale claim in the body
 
+Leave the `UI pass` line to `canon pr tick`, and carry it on a rewrite.
+
 ### Human-only boxes
 
 Leave a box unchecked only when a human is required, and name which human and why on the same line. The agent runs everything else.
@@ -110,6 +124,17 @@ A live agent session is never the human a box waits on.
 ## Formatting
 
 - End every bullet point with a period
+- Carry no H3 or H4 anywhere in a body. GitHub draws an H3 one step under an H2, so stacked H3s compete with the sections.
+- Group with a bold label or lead-in instead, in the forms the Sections rules above state
+
+### Density
+
+`canon labels scan` reports each section's density under `density`, naming the section, the kind, and the line in the whole body. Its help lists every limit.
+
+- Every section but Testing holds bullets to 200 characters and 5 in a row, and paragraphs to 350 characters and 2 in a row
+- Any section reports a `subheading`, and Technical context reports a `mixed-form`
+- A bold label alone on a line breaks a Key changes run, and a bold lead-in starts a new Technical context run
+- Fix a finding by regrouping or splitting, never by cutting a path
 
 ## Examples
 
@@ -122,19 +147,29 @@ Every section a body may carry, in order.
 
 <Action Verb> <Direct Object> to <Result>.
 
+Closes #<number>
+
 ## Key changes
 
+**<Area a reviewer opens together>**
+
 - <Verb> <specific component/file/function> (<reason if non-obvious>)
 - <Verb> <specific component/file/function>
 
+**<Next area>**
+
+- <Verb> <specific component/file/function>
+
 ## Technical context
 
-- <Architectural reasoning explaining why, not what>
+**<Decision in a few words>.** <Why this approach, what the code can't show, and any shortcoming>
+
+**<Next decision>.** <Why>
 
 ## Testing
 
 - [x] <Command run> <observed result>
-- [x] <Edge case verified> <what was observed>
+- [x] <Test file run> <observed result>
 - [ ] <Human-only check> (<which human, why>)
 
 ## For the reviewer
@@ -153,12 +188,20 @@ Update auth middleware to enforce jwt expiration checks. # imperative + direct o
 
 ## Key changes
 
+**Validation** # bold label on its own line, no period
+
 - Add `verifyExpiration()` to `src/auth/validators.ts`. # specific function + file path
+- Add the clock skew window to `src/auth/config.ts`. # one change per bullet
+
+**Session handling** # one label per area a reviewer opens together
+
 - Refactor `AuthService.authenticate()` to handle 401 codes. # named component + clear change
 
 ## Technical context
 
-- Migration to stateless session management for horizontal scalability. # why, not what
+**Stateless sessions.** Expiry lives in the token, so any instance can reject it without a shared store. # bold lead-in + why
+
+**Clock skew.** A 30-second window absorbs drift between instances, so a token can outlive its expiry by that much. # decision + shortcoming
 
 ## Testing
 
@@ -182,9 +225,17 @@ This PR updates the authentication system to be more robust. # "This PR" opener
 
 ## Key changes
 
+### Middleware # H3 inside a body
+
 - Updated auth middleware files # vague, no specific component, no period
 - The old system used to check tokens differently # describes historical behavior
 
+## Technical context
+
+- Tokens are stateless now. # a bullet
+
+The skew window trades precision for no shared store. # mixed with a paragraph in one section
+
 ## Testing
 
 - Tested manually # no specific command or case

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

@@ -88,33 +88,45 @@ Once the fixes are commits, re-run step 5's staleness test against the new head.
 
 ### Write the reply
 
-Write a summary reply to `.canon/tmp/pr/reply/reply-<number>.md`, keyed on the PR number so two sessions addressing different pull requests never overwrite each other. Load `write-human` for voice, follow `${CLAUDE_SKILL_DIR}/../markdown-craft/references/markdown.md`, and keep each mapping to a line or two.
+Write a summary reply to `.canon/tmp/pr/reply/reply-<number>.md`, keyed on the PR number so two sessions addressing different pull requests never overwrite each other. Load `write-human` for voice, follow `${CLAUDE_SKILL_DIR}/../markdown-craft/references/markdown.md`, and keep each mapping to one line.
 
 | Part     | Content                                                                                                                                        |
 | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
 | Heading  | `## Review response`, distinct from human threads and subordinate to the review's own `## Review`                                              |
 | Summary  | One sentence. After a step 5 rebase, say so and name files resolved by hand and those the regen rebuilt, since the next review is a full pass. |
-| Findings | One bullet per finding, opening with the bolded identifier, naming what changed or a one-line reason for a conscious-accept                    |
+| Findings | One line per finding under 200 characters, naming its outcome and the commit that carries it, in the shape below                               |
 | Docs     | Any `.claude/` docs refreshed as a result of the fixes                                                                                         |
 | Close    | `🤖 Addressed by Claude Code` on its own line, so the reply reads as a machine pass rather than a human sign-off                               |
 
+```markdown
+- **<severity>**, `<file>` line <n>: fixed in `<sha>`. <What now holds, in one sentence.>
+- **<severity>**, `<file>` line <n>: declined. <The fact that settled it.>
+```
+
+The commit carries the fix and its test, so the line names neither.
+
 A run the guard sent straight to step 5 has no findings to map, so it takes the `## Rebase` body in `${CLAUDE_SKILL_DIR}/references/rebase-only.md` instead. A run with findings skips that file.
 
 ### What a declined finding carries
 
-A finding this run declined carries the fact that settled it inside its own bullet, such as the plan question that answered it, a constraint the diff does not show, or a measurement the reviewer lacked. Left in the channel, that fact is lost when both sessions end.
+A finding this run declined carries the fact that settled it inside its own line, which may take a second sentence for it, such as the plan question that answered it, a constraint the diff does not show, or a measurement the reviewer lacked. Left in the channel, that fact is lost when both sessions end.
 
 The rule reaches a finding and nothing else. A correction to what the reviewing session believes about the world changes no finding here, so answer it wherever the dispatch reached this session and keep it off the comment.
 
 ### Scan and post
 
-Nothing tests the reply for either rule above. Follow `${CLAUDE_SKILL_DIR}/../git-pr/references/publish.md` and run its scan, which reads for banned characters and phase labels alone:
+Nothing tests the reply for either rule above. Follow `${CLAUDE_SKILL_DIR}/../git-pr/references/publish.md` and run its scan, which reads for banned characters and phase labels, and reports the reply's density:
 
 ```bash
-canon labels scan --body-file .canon/tmp/pr/reply/reply-<number>.md
+canon labels scan --body-file .canon/tmp/pr/reply/reply-<number>.md --json
 ```
 
-The hook skips `.canon/tmp/`, and the `pull_request` check reads only a pull request's own title and body, so this scan is the only gate on the reply. Fix any hit, then post and keep the `id` the POST answers with, since Step 7 edits this exact comment:
+The hook skips `.canon/tmp/`, and the `pull_request` check reads only a pull request's own title and body, so this scan is the only gate on the reply.
+
+- Fix any hit, and stop on a `density` entry too, shortening the line it names
+- Read the record rather than the exit, since density never sets the exit code
+
+Then post and keep the `id` the POST answers with, since Step 7 edits this exact comment:
 
 ```bash
 gh api -X POST 'repos/{owner}/{repo}/issues/<number>/comments' -F body=@.canon/tmp/pr/reply/reply-<number>.md --jq .id > .canon/tmp/pr/reply/reply-<number>.id

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

@@ -12,10 +12,13 @@ Outside the numbered flow of `review-address`. The session reads this file when
 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`
+- 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 --json`
+- Stop on a `density` entry as on any hit, since density never sets the exit code
 - 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
 
+Give each finding one line under 200 characters in the response's shape, naming its severity, its file and line, and what holds now or what was filed.
+
 `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

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

@@ -11,10 +11,22 @@ Read from Steps 6, 7, and 8 of `review-address` when the second guard sent the r
 
 A rebase-only run has no findings to map, so it takes a different body rather than an empty list. Open it with `## Rebase`, since nothing on the pull request is being responded to and `## Review response` claims a review this run never read.
 
-- State which half of the staleness test fired, being a branch that stopped merging or one `main` changed files under
-- Name what landed on `main`, then the files resolved by hand and those the regen rebuilt
+- Open on one sentence naming the commit rebased onto and what landed on `main`, and which half of the staleness test fired, being a branch that stopped merging or one `main` changed files under
+- Give one short line each to the files resolved by hand, those the regen rebuilt, and those replayed with no conflict, each under 200 characters
 - Close with `🤖 Addressed by Claude Code` on its own line, the same as a review response
 
+```markdown
+## Rebase
+
+Rebased onto main at `<short-sha>`, because <why>.
+
+- Resolved by hand: `<path>`. <What the resolution kept, in one sentence.>
+- Rebuilt by the regen: `<path>`, `<path>`
+- Replayed with no conflict: `<path>`
+
+🤖 Addressed by Claude Code
+```
+
 The heading stays outside the `## Review` family, so the close-out's equality test on the first line never matches it.
 
 ## Closing confirmation

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

@@ -123,11 +123,15 @@ Whether a human is genuinely required is a reading the author may hold a reason
 
 Read `## For the reviewer` the same way, bounded to the bullets under that heading. The Summary and Technical context carry the author's argument, and reading them while judging is what an independent pass exists to avoid.
 
-Answer each bullet in the body with no severity and no count. An unanswered request stays owed under the heading and dispatch, as an unanswered Testing box does, and an answered one is discharged in the same comment.
+Answer each bullet in the body with no severity and no count.
+
+- An unanswered request stays owed under the heading and dispatch, as an unanswered Testing box does
+- An answered one is discharged in the same comment
+- A request the diff answers against the author becomes a graded finding under the file that should have handled it, and enters the count, as an unconfirmed Review focus item does
 
 ### Review focus
 
-On a first pass, confirm each `**Review focus:**` item the plan names against the diff, since only the planning session's list names the inputs that would break the change. Report them in a `**Review focus**` block after `**For the reviewer**`, one bullet each naming what confirmed it.
+On a first pass, confirm each `**Review focus:**` item the plan names against the diff, since only the planning session's list names the inputs that would break the change. Report them folded under `<details>` after the reviewer block, with the count in its summary as `Review focus, N checked`, one bullet each naming the case and what confirmed it.
 
 - The block carries no severity and enters no count
 - An item the pass cannot confirm becomes a `should-fix` finding under the file that should have handled it, so a checked item reads apart from a skipped one
@@ -156,6 +160,9 @@ Read `${CLAUDE_SKILL_DIR}/references/post.md` for the body file name, the body s
 
 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.
 
+- Stop on a `density` entry in the body scan's record as on any other finding, and regroup or split the item it names before posting
+- Read the record rather than the exit, since the scan exits 0 on density alone
+
 ## Step 5: output
 
 ```plaintext

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

@@ -23,17 +23,21 @@ A Testing box the Step 3 check raised goes in a `**Testing**` block placed after
 
 ## 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 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.
+Every `## For the reviewer` bullet Step 3 read gets one bullet in the reviewer block, placed after the Testing block. It carries no severity and enters no count, and a request the pass answered against the author becomes a finding under its file block instead.
 
-- 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
+- It folds under `<details>` with the count in its summary, as the request shortened and the read or test that settled it
+- An unanswered bullet is owed like an unanswered Testing box, so it stays out of the fold in a `**For the reviewer**` block naming what would settle it, and the pass takes `## Review` and the full body
 - 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
+- The all-answered close-out below carries the folded block in place of that line and needs no addition
 
 ```markdown
-**For the reviewer**
+<details>
+<summary>For the reviewer, N confirmed</summary>
 
-- 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`.
+- The 401 and 403 split: `AuthService.authenticate()` returns 401 for an expired token and 403 for a missing scope
+
+</details>
 ```
 
 ## Close-out bodies
@@ -41,7 +45,23 @@ Every `## For the reviewer` bullet Step 3 read goes in a `**For the reviewer**`
 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.`
+- On a later pass, post the count line, then one line per prior finding, minors included, so a closed review always says what it closed
+
+```markdown
+## Review closed
+
+✅ N prior findings addressed at `<short-sha>`. Re-reviewed the N commits since the prior pass.
+
+- **<severity>**, `<path>`: what now holds, in one line
+
+🤖 Reviewed by Claude Code
+
+<!-- review-pr: commit=<headRefOid> read-at=<read-at> -->
+```
+
+- Each line names what holds now rather than the commit that fixed it, and stays under 200 characters
+- A prior finding this pass withdrew leaves the count, and its line names the fact that settled it rather than a fix, per the withdrawal rule below
+- A closing remark that fits no prior finding, such as a ticked Testing box, takes one line of its own after them
 
 ### Only minors
 
@@ -54,7 +74,8 @@ A pass carrying only minors is an ordinary finding-carrying pass, so it takes th
 
 **`path/to/file.ext`**
 
-- **minor** ([line 12](<repo-url>/blob/<headRefOid>/path/to/file.ext#L12)): finding, and the fix it wants.
+- **minor** ([line 12](<repo-url>/blob/<headRefOid>/path/to/file.ext#L12)): what breaks, in one sentence.
+  - Fix: the change
 
 🤖 Reviewed by Claude Code
 
@@ -69,4 +90,4 @@ Write the withdrawal and the fact that settled it in place of the canned line, k
 
 ### Only answered reviewer requests
 
-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.
+A pass whose only content is a `## For the reviewer` block with every bullet answered, owing nothing else, takes `## Review closed`, the folded 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/post.md

@@ -32,7 +32,7 @@ That satisfies both prohibitions above rather than carving an exception into eit
 A finding bound to a line links to it, so a reader skips the hunt:
 
 ```markdown
-- **should-fix** ([line 12](<repo-url>/blob/<headRefOid>/<path>#L12)): what breaks and the fix
+- **should-fix** ([line 12](<repo-url>/blob/<headRefOid>/<path>#L12)): what breaks, in one sentence
 ```
 
 - A span anchors as `#L12-L14`, with no spaces and no en dash, and a single line as `#L12`
@@ -60,12 +60,18 @@ X critical, Y should-fix, Z minor. Reviewed against project docs and the board.
 
 **`path/to/file.ext`**
 
-- **should-fix** ([line 12](<repo-url>/blob/<headRefOid>/path/to/file.ext#L12)): what breaks and the fix, in two or three sentences.
-- **minor** ([lines 30-34](<repo-url>/blob/<headRefOid>/path/to/file.ext#L30-L34)): finding.
+- **should-fix** ([line 12](<repo-url>/blob/<headRefOid>/path/to/file.ext#L12)): what breaks, in one sentence.
+  - one fact of evidence, with its link
+  - Fix: the change
+- **minor** ([lines 30-34](<repo-url>/blob/<headRefOid>/path/to/file.ext#L30-L34)): what breaks, in one sentence.
+  - Fix: the change
 
-**What is right**
+<details>
+<summary>Review focus, N checked</summary>
 
-- bounded confirmation.
+- the case: the test or read that covers it
+
+</details>
 
 🤖 Reviewed by Claude Code
 
@@ -81,14 +87,24 @@ Re-reviewed `<short-sha>`, N commits since the prior pass. X critical, Y should-
 
 **`path/to/file.ext`**
 
-- **should-fix** ([line 12](<repo-url>/blob/<headRefOid>/path/to/file.ext#L12)): what breaks and the fix, in two or three sentences.
+- **should-fix** ([line 12](<repo-url>/blob/<headRefOid>/path/to/file.ext#L12)): what breaks, in one sentence.
+  - Fix: the change
 
 🤖 Reviewed by Claude Code
 
 <!-- review-pr: commit=<headRefOid> read-at=<read-at> -->
 ```
 
-A Testing question or a `## For the reviewer` bullet Step 3 read takes its own block after the file blocks, per `${CLAUDE_SKILL_DIR}/references/body-variants.md`.
+### The finding shape
+
+A reader decides from the first line of a finding whether to open the rest, so the subject carries the failure alone.
+
+- The subject is one sentence under 200 characters, naming what breaks rather than how the pass found it
+- Each nested bullet carries one fact of evidence with its link, and the last one opens on `Fix:`
+- A nested bullet stays under 200 characters too, since `canon labels scan` measures it as a bullet of its own
+- A finding with nothing to add past its subject takes the `Fix:` bullet alone
+
+A Testing question or a `## For the reviewer` bullet Step 3 read takes its own block after the file blocks, per `${CLAUDE_SKILL_DIR}/references/body-variants.md`. A request or a focus case that fails leaves `<details>` and becomes a finding.
 
 ### The PR body block
 
@@ -123,9 +139,9 @@ A minor the dispatched worker declines needs a surface that survives the merge,
 Name the scope in every summary line after the first pass, since a reader cannot otherwise tell a narrow read from a full one. When the fallback in Step 2 fired, replace the commit count with `Re-reviewed the full change, the prior pass's commit is no longer on the branch`.
 
 - Do not append the PR number to either heading, which GitHub already renders above the comment
-- State each finding as the failure and the fix in two or three sentences, not a paragraph of reasoning
+- State each finding in the shape above, never as a paragraph of reasoning
 - Omit files with no findings and do not lecture on process. The integration, contract, and consumer lenses stay as findings, not asides.
-- `What is right` is optional, capped at three bullets, and included only when it changes the merge decision
+- Leave `What is right` out unless the author asked a direct question it answers, then cap it at three bullets
 - Close with `🤖 Reviewed by Claude Code` on its own line, so the review reads as an independent machine pass, not a human sign-off
 
 ## The marker, the scans, and the post
@@ -156,7 +172,10 @@ The marker is the read-time record those fields are not.
 
 ### The scans
 
-Before posting, run `canon labels scan --body-file .canon/tmp/pr/review/body-<number>-<short-sha>.md`, which applies the rule in `${CLAUDE_SKILL_DIR}/../git-pr/references/publish.md`. Fix the body and scan again on a finding.
+Before posting, run `canon labels scan --body-file .canon/tmp/pr/review/body-<number>-<short-sha>.md`, which applies the rule in `${CLAUDE_SKILL_DIR}/../git-pr/references/publish.md`. Pass `--json` and fix the body and scan again on a finding.
+
+- A `density` entry is a finding here, naming a subject or nested bullet past 200 characters, a run past 5 plain bullets, or a paragraph past its limits, by its line in the whole body
+- Density never sets the exit code, so the hook below lets the post through on it and this step is the one that stops
 
 - A finding phrased against an internal phase label is what the label half of the scan catches here
 - The call carries no `--title`, so the scan reads the text as a review

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

@@ -115,6 +115,7 @@ ${CLAUDE_SKILL_DIR}/scripts/pw.sh -s=<project>-<number> open <url>
 
 Read `${CLAUDE_SKILL_DIR}/references/driving.md` on reaching this step for how a box's line maps to calls, how each value is read, and the four verdicts with the evidence each one carries.
 
+- Make each box its own item on the session's task list, and tick it as its verdict lands. Skip it on a host that offers no list tool.
 - Give every box exactly one verdict, in checklist order, since skipping a box silently reads the same as passing it
 - Drive a box the pass could not place on a route or a width from the opened address at 1440 wide, and name the guess in the verdict
 - Never judge a box ending in `(taste)`. Drive to the state, capture both themes, and mark it needs eyes.

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

@@ -76,6 +76,8 @@ Driven at `<short-sha>` on <address>, rendered by <renderer>.
 <!-- review-ui: head=<head> -->
 ```
 
+The post takes the length limits alone, with a box's reason under 350 characters and split into the reading and its cause where it runs longer, and keeps its H3 verdict groups and tables.
+
 The body opens on its count line, in that order, so the operator reads what they owe before anything else. The second line carries the address, the head, and the renderer, and says the address was driven unverified when it came from the local rung or the launch.
 
 - Drop each section holding no box, along with its heading. Order is fixed: Failed, Needs your eyes, Not driven, then the folded blocks.

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

@@ -18,5 +18,8 @@ Number the boxes off the `boxes` field Step 2 kept. Leave a box that failed, nee
 The verb refuses a taste box and a head that is no longer the remote tip, writing nothing in either case. Branch on the record's `reason`, which reads `ticked` on success.
 
 - `stale-head`: a push landed while this pass drove. Report it on the `Ticks:` line of Step 10 and never retry at the new tip, since the boxes were driven at the old one.
+- `body-refused`: the comment is ticked and the body is not. Retry the same call once, then report the partial result on the `Ticks:` line rather than claiming both.
 - Any other refusal: report the `reason` on the `Ticks:` line and tick nothing further.
 - A binary whose `canon pr` lacks `tick` predates the verb. Report that on the `Ticks:` line and tick nothing.
+
+The same call also writes the one UI pass line in the body's `## Testing`, such as `UI pass, 17 of 17 boxes passed at <sha>, 1 taste box left to the operator`, so the operator sees the result without opening the evidence comment. Never edit that line by hand.

package/claude/skills/role-reviewer/REQUIREMENT.md

@@ -14,7 +14,7 @@ Each launch also restates the reviewer's bounds, though they belong to the role.
 ## Must
 
 - The role is asserted, with writes bounded to the comment and body file the pass posts, and the tracked file, branch, worktree, board, and commit named as outside them
-- Every file read a finding rests on goes through `git show <head>:<path>` at the resolved head, and launch-carried cross-branch facts are inputs
+- Every file read a finding rests on goes through `git show <head>:<path>` at the resolved head, and launch-carried cross-branch facts are inputs. A task list, if the host has one, tracks each step.
 - The fix, a draft lift by any route but `canon pr lift`, and the merge are refused whoever asks, naming each owner, and the lift runs after a close is posted
 - An open pass sends the worker the `review-address` dispatch and this session's id, else the controller the cause, and a close sends the lift's reason unless the other review is open or missing
 - A re-review stays with the reviewer that took the first pass while it is live, and a block is messaged before it becomes an interactive prompt

package/claude/skills/role-reviewer/SKILL.md

@@ -31,6 +31,8 @@ The session writes its comment and nothing tracked. Each kind of reviewer writes
 - Resolve `.canon/plans/`, `.canon/tasks/`, and `.canon/tmp/` at the main worktree root, and send the body file as a heredoc, the main-root route `session-worktree` states
 - Report a plan or task that fails to resolve there as unreadable, naming the path, rather than reviewing as though the branch had none
 
+Keep a task list from launch, one item per step of the pass, and tick each as it completes. Skip it on a host that offers no list tool, since the list is for the operator watching and not a gate.
+
 Review the pull request the launch named. Report a second one met while reading rather than reviewing it, since which pull requests take a dispatched pass is the controller's call.
 
 ## What to read and what to leave
@@ -59,6 +61,7 @@ Send it to the worker holding the branch as `review-pr` Step 5 returns an open `
 - Carry the pull request number, the heading, that step's count line verbatim, and this session's own sessionId for the worker's reply
 - Resolve the worker with `canon sessions list --branch <branch> --json`, where `<branch>` is the pull request's head branch
 - Send to it only when exactly one session comes back with its confidence reading `confirmed`
+  - Count a row reading `via: "listener"` as confirmed, since its messaging socket accepted a connection. Never read it as `via: "socket"`, which rests on a socket file existing alone.
 - On zero, on any other count or confidence, or on a refusal, send the same message to the controller, naming the cause the roster read gives
   - Say the roster rests on sockets from another pid namespace, so the worker may be live and unconfirmed, when a row reads `via: "socket"` or an empty roster carries a `foreignDead` count above zero
   - Say the roster rests on a pid answering alone, since start times could not be read, when the confidence reads `unverified` and no row reads `via: "socket"`

package/claude/skills/role-worker/REQUIREMENT.md

@@ -13,7 +13,7 @@ The channel fails on the worker's side. Blocks open prompts nobody is attached t
 
 ## Must
 
-- Session scratch resolves at the main worktree root, and a plan that fails to resolve is reported unreadable from there rather than absent
+- Session scratch resolves at the main worktree root, and a plan that fails to resolve is reported unreadable from there rather than absent. A task list, where the host has one, tracks each slice.
 - The announcement carries the number, branch, task, reach, any uncleared spend, and any row the build turned up, and a painted diff has its preview server running before the pull request opens
 - A block goes out as a message before it becomes a prompt, a fan-in member's done message carries its branch and head commit, and a review wait that times out reaches the controller
 - The plan's scope freezes at dispatch, and a late ask is sorted into a defect, a follow-up row, or an addition on the operator's word

package/claude/skills/role-worker/SKILL.md

@@ -23,6 +23,7 @@ This body states the role, the boundaries, and the channel, and starts no step o
 - Resolve `.canon/plans/`, `.canon/tasks/`, `.canon/review/`, and `.canon/ready/` at the main worktree root, never the linked worktree. Being gitignored, they are absent there rather than empty.
 - Report a plan that fails to resolve as unreadable from here, naming the main-root path. Reporting the task as having no plan is wrong about the world, and a reader cannot tell the two apart.
 - Build the plan the launch named. Never write a second one when the path fails to resolve, since a row citing a plan already has one.
+- Keep a task list from launch, one item per slice, and tick each as its slice lands. Skip it on a host that offers no list tool, since the list is for the operator watching and not a gate.
 
 ### Ready folders and the draft mark
 

package/claude/skills/task-board/references/decline.md

@@ -33,11 +33,11 @@ A successful decline returns one record whose fields match `canon tasks archive`
 | -------------------- | ------------------------------------------------------------------------ |
 | `from`, `to`         | The task's old and new path                                              |
 | `priorityRowRemoved` | Whether a `priority.md` row was dropped                                  |
-| `backlogRowRemoved`  | Whether a `backlog.md` row was dropped, a field archive lacks            |
+| `backlogRowRemoved`  | Whether a `backlog.md` row was dropped                                   |
 | `indexRegenerated`   | Whether the index was rewritten                                          |
 | `plans`              | A `from` and `to` per live plan the task last cited, empty if none moved |
 
-`backlogRowRemoved` is decline's own, since a task can be declined straight off `backlog.md` and archive never checks that file.
+A task can be declined straight off `backlog.md`, so decline checks that file as well as `priority.md`. Archive does the same and reports the same two fields.
 
 ## Step 3: route on a refusal
 

package/claude/skills/task-complete/references/archive.md

@@ -8,7 +8,7 @@ description: How task-complete confirms a task's work reached main, runs canon t
 The Archive mode of `task-complete`. The session reads this file when the request names a task file already shipped.
 
 - The `post-merge` git hook archives the task a merge closed, so a request here is usually one the hook could not resolve. Run the steps against whatever it left in place.
-- `canon tasks archive` moves the file, edits `priority.md`, and regenerates the index as one unit. The hook calls the same command, so a hand-rolled move drifts from the unattended path.
+- `canon tasks archive` moves the file, edits `priority.md` and `backlog.md`, and regenerates the index as one unit. The hook calls it too, so a hand-rolled move drifts from the unattended path.
 
 ## Step 1: confirm the work reached main
 
@@ -45,6 +45,7 @@ A successful archive returns one record naming what moved.
 | -------------------- | --------------------------------------------------------------------- |
 | `from`, `to`         | The task's old and new path                                           |
 | `priorityRowRemoved` | Whether a `priority.md` row was dropped                               |
+| `backlogRowRemoved`  | Whether a `backlog.md` bullet was dropped                             |
 | `indexRegenerated`   | Whether the index changed                                             |
 | `plans`              | A `from` and `to` per live plan the task last cited, in `Plan:` order |
 
@@ -80,4 +81,4 @@ Leave `TASK-ARCHIVE.md` alone when it is present in the archive folder. It recor
 
 ## Step 4: clear prose naming the task
 
-The command drops the row from `.canon/tasks/priority.md` and leaves prose alone. Remove any sentence that still names the archived task or counts the changed rows, since a stale count reads as board state.
+The command drops the row from `.canon/tasks/priority.md` and the bullet from `.canon/tasks/backlog.md`, and leaves prose alone. Remove any sentence that still names the archived task or counts the changed rows, since a stale count reads as board state.

package/claude/skills/ui-checklist/SKILL.md

@@ -23,11 +23,11 @@ An automatable change already covered by a test written during implementation is
 
 ## The checklist
 
-Group visual items by feature area. Use `- [ ]` checkbox syntax, and write each item as the action and the result a person is looking for, so a reviewer who did not build the change can run it.
+Group visual items under a bold label per feature area, at most five boxes a group, and split a larger area into two labels. Use `- [ ]` checkbox syntax, and write each item as the action and the result a person is looking for, so a reviewer who did not build the change can run it.
 
-```markdown
-**What to verify visually:**
+The evidence comment already heads the list with `## What to look at`, so the file opens on its first feature label with no heading line of its own.
 
+```markdown
 **<Feature area>**
 
 - [ ] <route>[, <width>]: <verb> <target> → <expected visual result>