@erclx/canon 5.41.0 → 5.43.0

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

@@ -15,11 +15,19 @@ Step 4 of `review-pr`. The threshold that picks the heading and decides the disp
 
 ## The body file and finding links
 
-Write the comment to `.canon/tmp/pr/review/body-<number>-<short-sha>.md` at the main worktree root, not the current worktree, which the rest of this step calls `<body-file>`. Resolve that root and send the write as a heredoc, both the way `session-worktree` states. The PR number stops two sessions reviewing different pull requests from overwriting each other between the write and the post, and the head commit stops a second pass overwriting the first one's body.
+Write the comment to `.canon/tmp/pr/review/body-<number>-<short-sha>.md` at the main worktree root, not the current worktree, which the rest of this step calls `<body-file>`. Resolve that root and send the write as a heredoc, both the way `session-worktree` states.
 
-Derive both segments from Step 1. Never pick a suffix by hand, and never reuse a name the folder already holds.
+- The PR number stops two sessions reviewing different pull requests from overwriting each other between the write and the post
+- The head commit stops a second pass overwriting the first one's body
+- Derive both segments from Step 1. Never pick a suffix by hand, and never reuse a name the folder already holds.
 
-When `<prior-oid>` from Step 2 equals `headRefOid`, the head repeats and the folder already holds `body-<number>-<short-sha>.md`. Add a third segment taking the id of the reply Step 2 resolved, giving `body-<number>-<short-sha>-r<comment-id>.md`, which is `<body-file>` on that path. That satisfies both prohibitions above rather than carving an exception into either. Step 2 already stopped the pass when that resolution came back empty, so reaching this line means the comment id is in hand.
+### A repeated head
+
+When `<prior-oid>` from Step 2 equals `headRefOid`, the folder already holds `body-<number>-<short-sha>.md`. Add a third segment taking the id of the reply Step 2 resolved, giving `body-<number>-<short-sha>-r<comment-id>.md` as `<body-file>`.
+
+That satisfies both prohibitions above rather than carving an exception into either. Step 2 already stopped the pass when that resolution came back empty, so reaching this line means the comment id is in hand.
+
+### Finding links
 
 A finding bound to a line links to it, so a reader skips the hunt:
 
@@ -27,13 +35,23 @@ A finding bound to a line links to it, so a reader skips the hunt:
 - **should-fix** ([line 12](<repo-url>/blob/<headRefOid>/<path>#L12)): what breaks and the fix
 ```
 
-A finding that spans lines anchors to the span as `#L12-L14`, with no spaces and no en dash, and a single-line finding anchors as `#L12`. Take the line number from the file read at `<headRefOid>`, `git show <headRefOid>:<path>`, never from another checkout. The URL carries the full 40-character `<headRefOid>`, never `<short-sha>`, `HEAD`, or the branch name, so the link survives a push. A later pass restating an open finding links it again at its own `<headRefOid>` rather than copying the old bullet.
+- A span anchors as `#L12-L14`, with no spaces and no en dash, and a single line as `#L12`
+- Take the line number from the file read at `<headRefOid>`, `git show <headRefOid>:<path>`, never from another checkout
+- The URL carries the full 40-character `<headRefOid>`, never `<short-sha>`, `HEAD`, or the branch name, so the link survives a push
+- A later pass restating an open finding links it again at its own `<headRefOid>` rather than copying the old bullet
+
+### Findings with no link
+
+Four findings take the plain bullet with no link, since the head holds no line number for them.
 
-Four findings take the plain bullet with no link: a `**PR body**` entry, a finding on a file the head deleted, a finding on a line the diff removed from a file that survives, since the head holds no number for it, and a finding about a whole file with no one line. A path holding a character a URL needs encoded, such as a space or `#`, is percent-encoded in the link or keeps the plain bullet. Keep the file block header a bare backticked path, so the section-marker reading in `${CLAUDE_SKILL_DIR}/../markdown-craft/references/markdown.md` does not change.
+- A `**PR body**` entry, and a finding about a whole file with no one line
+- A finding on a file the head deleted, or on a line the diff removed from a file that survives
+- A path holding a character a URL needs encoded, such as a space or `#`, is percent-encoded in the link or keeps the plain bullet
+- Keep the file block header a bare backticked path, so the section-marker reading in `${CLAUDE_SKILL_DIR}/../markdown-craft/references/markdown.md` holds
 
 ## The body shapes
 
-The comment is a rendered-for-human GitHub surface, so load the `write-human` skill for voice and word choice and follow `${CLAUDE_SKILL_DIR}/../markdown-craft/references/markdown.md` for punctuation: cut editorializing, and keep every sentence load-bearing. Match this shape on a first pass:
+The comment is a rendered-for-human GitHub surface, so load the `write-human` skill for voice and word choice and follow `${CLAUDE_SKILL_DIR}/../markdown-craft/references/markdown.md` for punctuation. Cut editorializing, and keep every sentence load-bearing. Match this shape on a first pass:
 
 ```markdown
 ## Review
@@ -54,10 +72,6 @@ X critical, Y should-fix, Z minor. Reviewed against project docs and the board.
 <!-- review-pr: commit=<headRefOid> read-at=<read-at> -->
 ```
 
-A stale ticked box goes in a `**PR body**` block, in place of a `**`path/to/file.ext`**` block and ahead of every one of those, since it precedes the code the diff carries rather than sitting inside it.
-
-Run `canon labels scan --title "<title>" --body "<body>" --head <headRefName>` against the PR under review, since Step 1 already holds all three and this pass is the last human-shaped gate before merge. A hit lands in the same `**PR body**` block, `should-fix`, naming each finding the scan returns: a token quoted from the title or body for a phase label, a board identifier, or a session link, and the broken rule's name, `structure`, a casing issue, or `length`, for a title-format hit. A heading in `sections.outside`, a heading in `sections.missing`, or a character in `bannedCharacters` is a hit of the same weight, naming the heading or the character. This reads the pull request being reviewed, distinct from the comment this pass is about to post, which the scan later in this step still covers.
-
 A later pass carrying findings keeps that shape and changes only the summary line:
 
 ```markdown
@@ -76,25 +90,43 @@ Re-reviewed `<short-sha>`, N commits since the prior pass. X critical, Y should-
 
 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`.
 
-Keying either half of the opening's threshold on the grade was measured wrong: across 8 findings on one archived pass, 3 were posted as minor and 2 of those were defects a worker fixed rather than recorded, so a floor at should-fix loses real fixes to a grade that runs low. Splitting the two halves so the dispatch fired lower than the heading was the other candidate, and it left a thread reading closed while work was owed on it. The Testing question was first written to sit outside both, which is that same split reached from the other side, and it left the one party who could answer the question with no route to it.
+### The PR body block
 
-The cost is that the merge decision no longer reads off the heading alone, since an open heading covers a minor as well as a critical. Take it from the counts on the summary line, which is where they already sit. No summary line reports the merge as unblocked under either heading, since a thread reading open cannot also report that nothing blocks it.
+A stale ticked box goes in a `**PR body**` block, ahead of every file block, since it precedes the code the diff carries rather than sitting inside it.
 
-A minor the dispatched worker declines is what needs a surface that survives the merge, rather than every minor, since one that gets fixed on the branch needs no durable record. Write a declined minor into the `## Findings` section of the task the branch closes, as a line opening with the bold source-and-date label from `${CLAUDE_SKILL_DIR}/../task-board/references/tasks.md`, which is where the queue-refill sweep already routes a finding that changes another task. A declined finding left on the thread alone is lost the moment the pull request merges.
+Run `canon labels scan --title "<title>" --body "<body>" --head <headRefName>` against the PR under review, since Step 1 already holds all three and this pass is the last human-shaped gate before merge. A hit lands in the same block as a `should-fix`.
 
-Read the state off the most recent review comment rather than off the presence of a closed one. A close-out does not close the pull request, so a commit pushed after it gets its own pass, and that pass reopens the review under `## Review` when it raises a finding of any grade.
+- Name the token quoted from the title or body for a phase label, a board identifier, or a session link
+- Name the broken rule, being `structure`, a casing issue, or `length`, for a title-format hit
+- A heading in `sections.outside` or `sections.missing`, or a character in `bannedCharacters`, is a hit of the same weight, naming the heading or the character
+- This reads the pull request under review, distinct from the comment this pass posts, which the scan later in this step covers
 
-Do not append the PR number to either heading, which GitHub already renders above the comment.
+### Why the threshold ignores the grade
 
-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`.
+Keying either half of the opening's threshold on the grade was measured wrong. Across 8 findings on one archived pass, 3 were posted as minor and 2 of those were defects a worker fixed, so a floor at should-fix loses real fixes to a grade that runs low.
+
+- Firing the dispatch lower than the heading left a thread reading closed while work was owed on it
+- A Testing question sitting outside both is the same split, and it left the one party who could answer it with no route
+- The cost is that the merge decision reads off the summary line's counts rather than the heading, since an open heading covers a minor and a critical alike
+- No summary line reports the merge as unblocked under either heading, since a thread reading open cannot also report that nothing blocks it
+
+### Declined minors and reopening
 
-Budget the body. State each finding as the failure and the fix in two or three sentences, not a paragraph of reasoning.
+A minor the dispatched worker declines needs a surface that survives the merge, since one fixed on the branch needs no record and one left on the thread is lost at merge. Write it into the `## Findings` section of the task the branch closes.
 
-Omit files with no findings. Do not lecture on process. The integration, contract, and consumer lenses stay, but as findings, not asides.
+- Open the line with the bold source-and-date label from `${CLAUDE_SKILL_DIR}/../task-board/references/tasks.md`, where the queue-refill sweep already routes such a finding
+- Read the state off the most recent review comment rather than off the presence of a closed one
+- A close-out does not close the pull request, so a later commit gets its own pass, which reopens under `## Review` on a finding of any grade
 
-The `What is right` section is optional, capped at three bullets, and included only when it changes the merge decision. Drop it otherwise and let the summary line carry the approval.
+### Summary line and budget
 
-Close the body with `🤖 Reviewed by Claude Code` on its own line so the review reads as an independent machine pass, not a human sign-off.
+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
+- 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
+- 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
 
@@ -106,26 +138,46 @@ End every body with this line, carrying `<headRefOid>` and `<read-at>` from Step
 <!-- review-pr: commit=<headRefOid> read-at=<read-at> -->
 ```
 
-Every body this step writes carries it, with no exception: the full body under either heading, both ✅ close-out lines, a withdrawal body, and the `PUT` rewrite in `close-out.md`. A body missing it reads as a pre-marker pass, so the next reader falls back to the stamps and the pass loses the coverage it actually had.
+Every body this step writes carries it, being the full body under either heading, both ✅ close-out lines, a withdrawal body, and the `PUT` rewrite in `close-out.md`. A body missing it reads as a pre-marker pass, so the next reader falls back to the stamps and the pass loses its coverage.
+
+- Last is load-bearing, since `canon pr review-state` reads the last non-empty line and searches nowhere else
+- That position also lets a finding quote the format safely, even in a fence, since a quotation is never the line the reader takes
+- Write it as an HTML comment, which GitHub renders as nothing, so a reader of the thread never meets it
+
+### Why the marker exists
+
+GitHub stamps `commit.oid` and `submittedAt` at submission, not at read. A push landing in the compose window moves both onto a commit this pass never opened, and the next pass reads it as covered.
 
-Last is load-bearing rather than tidy. `canon pr review-state` reads the last non-empty line and searches nowhere else, so a marker written above the footer is a marker the next pass does not see. That position is also what lets a finding quote the format safely, including inside a fenced block, since a quotation is never the line the reader takes.
+The marker is the read-time record those fields are not.
 
-It is what the review is scoped from. GitHub stamps `commit.oid` and `submittedAt` when a review is submitted, not when it was read, so a push landing in the compose window moves both onto a commit this pass never opened and the next pass reads that commit as covered. The marker is the read-time record those two fields are not, and `canon pr review-state` is the one place it is parsed, so Step 2 here and the orchestrator poll read one answer rather than each carrying a copy of the format.
+- `canon pr review-state` is the one place it is parsed, so Step 2 and the orchestrator poll read one answer rather than each copying the format
+- It is inert data, so `canon labels scan` has nothing to fire on
+- Confirm that against the posted body, since a phase label or board identifier inside a commit sha is not a shape either scan was written against
 
-Write it as a comment rather than as prose so a reader of the thread never meets it. HTML comments render as nothing on GitHub, which is why the fact travels here rather than in a footer line a person would have to be told to ignore.
+### The scans
 
-It is inert data, so the `publish.md` scan below and `canon labels scan` have nothing to fire on. Confirm that against the posted body rather than assuming it, since a phase label or a board identifier appearing inside a commit sha is not a shape either scan was written against.
+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` against the body, which applies the rule in `${CLAUDE_SKILL_DIR}/../git-pr/references/publish.md`. Fix the body and scan again on a finding. 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.
+- 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
 
-A `PreToolUse` hook on `Bash` runs the same scan against the `-F body=@<file>` of the post below and denies the call on a hit, so the check holds whether or not this step ran it. The hook reads the file before the command runs, so write the body in an earlier call than the post, and pass it as a file rather than inline. This repository reads the same text again once posted, on `phase-label-gate.yml`'s `pull_request_review` trigger, which is what closes the gap for a review a person writes and posts by hand with no hook in front of it. That workflow now reaches every target on the `base` stack, seeded at `tooling/base/configs/.github/workflows/phase-label-gate.yml` invoking the published CLI rather than this checkout's own source tree, so a target's coverage extends past the hook to the same post-trigger re-read this repository gets.
+A `PreToolUse` hook on `Bash` runs the same scan against the `-F body=@<file>` of the post and denies the call on a hit, so the check holds whether or not this step ran. The hook reads the file before the command runs, so write the body in an earlier call and pass it as a file rather than inline.
 
-Do not run the command below when `<prior-heading>` from Step 2 reads `## Review closed` and this pass carries nothing owed. That pass replaces the standing comment rather than adding one, so read `${CLAUDE_SKILL_DIR}/references/close-out.md` instead of posting. Posting first and reaching that section afterward leaves two close-outs both naming the new head, which is worse than the pair the guard exists against.
+### The post-trigger re-read
+
+`phase-label-gate.yml` reads the same text again once posted, on its `pull_request_review` trigger, which covers a review a person posts by hand with no hook in front of it.
+
+- That workflow reaches every target on the `base` stack, seeded at `tooling/base/configs/.github/workflows/phase-label-gate.yml`
+- It invokes the published CLI rather than a checkout's own source tree, so a target gets the same re-read past the hook
+
+### The post
+
+Do not run the command below when `<prior-heading>` from Step 2 reads `## Review closed` and this pass carries nothing owed. Read `${CLAUDE_SKILL_DIR}/references/close-out.md` instead, since posting first leaves two close-outs both naming the new head.
 
 ```bash
 gh api -X POST 'repos/{owner}/{repo}/pulls/<number>/reviews' -f event=COMMENT -F body=@.canon/tmp/pr/review/body-<number>-<short-sha>.md --jq .html_url
 ```
 
-The post goes through the REST reviews endpoint rather than the `gh pr` review subcommand, which runs on GraphQL and fails where a cloud session's GitHub proxy refuses it. `event=COMMENT` submits the review as a comment, the same state the old `--comment` flag produced.
-
-A pass carrying nothing at all, a withdrawal, or only answered reviewer requests takes a close-out body, and a pass carrying only minors keeps the full shape, both per `${CLAUDE_SKILL_DIR}/references/body-variants.md`.
+- The post uses the REST reviews endpoint, since the `gh pr` review subcommand runs on GraphQL and fails where a cloud session's proxy refuses it
+- `event=COMMENT` submits the review as a comment, the same state the old `--comment` flag produced
+- A pass carrying nothing, a withdrawal, or only answered requests takes a close-out body, and only minors keep the full shape, per `${CLAUDE_SKILL_DIR}/references/body-variants.md`

package/claude/skills/review-pr/references/scope.md

@@ -7,27 +7,42 @@ description: Step 2 of review-pr, which finds the commit and verdict the prior p
 
 Step 2 of `review-pr`. The session reads this file on reaching that step, ahead of Step 3, so the unchanged-head stop below still fires before any review runs.
 
+## Find the prior pass
+
 Find the commit the last pass covered and the verdict it posted:
 
 ```bash
 canon pr review-state <number> --json
 ```
 
-The fields are `<prior-oid>` off `commit`, `<prior-heading>` off `heading`, and `<prior-at>` off `readAt // submittedAt`. The commit scopes the read below, the heading feeds the repeat guard at the end of this step, and the instant scopes the reply query further down, so one call answers all three rather than three reads of the same review. Branch on the record rather than on the exit code, which a shell function wrapping `canon` can flatten to zero.
+Take `<prior-oid>` off `commit`, `<prior-heading>` off `heading`, and `<prior-at>` off `readAt // submittedAt`. Branch on the record rather than on the exit code, which a shell function wrapping `canon` can flatten to zero.
+
+- The commit scopes the read below, the heading feeds the repeat guard at the end of this step, and the instant scopes the reply query
+- One call answers all three rather than three reads of the same review
+
+### Which stamp answered
+
+`source` says which stamp answered, and `marker` is the authority. Never read `commit_id` or `submitted_at` off the reviews listing here, since both are stamped at submission and a push between a pass's read and its post moves them onto a commit that pass never saw.
 
-`source` says which stamp answered. `marker` is the pass's own read-time record and is the authority. `fallback` is a pass posted before this mechanism shipped, so its commit is whatever the head was when GitHub recorded the review rather than what that session read, and a push inside its compose window is invisible. `none` is a thread carrying no pass at all.
+- `marker`: the pass's own read-time record
+- `fallback`: a pass posted before the marker shipped, whose commit is the head when GitHub recorded the review, so a push inside its compose window is invisible
+- `none`: a thread carrying no pass at all
 
-Do not read `commit_id` or `submitted_at` off the reviews listing here. Both are stamped at submission, so a push landing between a pass's read and its post moves them onto a commit that pass never saw, and this step then scopes the delta past it and reports it covered.
+### When the verb is missing
 
-A target whose CLI predates the verb meets a missing subcommand rather than a record. Fall back there to the REST read below, which reads the stamps and carries the defect above, and say the fallback answered so a reader can tell a marker read from a stamped one:
+A target whose CLI predates the verb meets a missing subcommand rather than a record. Fall back to this REST read, which reads the stamps and carries the defect above, and say the fallback answered so a reader can tell a marker read from a stamped one:
 
 ```bash
 gh api --paginate 'repos/{owner}/{repo}/pulls/<number>/reviews?per_page=100' --jq '.[] | select(.body // "" | split("\n")[0] | rtrimstr("\r") | . == "## Review" or . == "## Review closed") | ((.commit_id // "") + "\t" + (.body | split("\n")[0] | rtrimstr("\r")) + "\t" + (.submitted_at // ""))' | tail -n 1
 ```
 
-The three fields are `<prior-oid>`, `<prior-heading>`, and `<prior-at>`. The filter emits one line per matching review and `tail` keeps the newest, since `--paginate` runs the filter once per page and a `last` inside it would answer for each page rather than for the thread.
+The three fields are `<prior-oid>`, `<prior-heading>`, and `<prior-at>`.
 
-Match the first line for equality against the two headings this skill posts. A prefix test also matches `## Review response` and any heading merely starting with those words, which would scope the pass to whatever commit that comment carried. The `\r` trim covers a body composed in the GitHub web editor, which stores CRLF.
+- The filter emits one line per matching review and `tail` keeps the newest, since `--paginate` runs the filter once per page
+- Match the first line for equality, since a prefix test also matches `## Review response` and scopes the pass to that comment's commit
+- The `\r` trim covers a body composed in the GitHub web editor, which stores CRLF
+
+## A first pass
 
 A `source` of `none`, or an empty result from the fallback, is a first pass. Read the whole change:
 
@@ -39,7 +54,9 @@ gh api 'repos/{owner}/{repo}/pulls/<number>' -H 'Accept: application/vnd.github.
 gh api --paginate 'repos/{owner}/{repo}/pulls/<number>/files?per_page=100' --jq '.[].filename'
 ```
 
-Both reads go through REST, since the `gh pr` diff subcommand runs on GraphQL and a cloud session's GitHub proxy refuses it. The diff media type returns the same unified diff, and the paginated files listing returns every path rather than the first page.
+Both reads go through REST, since the `gh pr` diff subcommand runs on GraphQL and a cloud session's GitHub proxy refuses it. The diff media type returns the same unified diff, and the paginated listing returns every path rather than the first page.
+
+## A later pass
 
 A commit is a later pass. Fetch the pull request head so both commits are local:
 
@@ -47,7 +64,7 @@ A commit is a later pass. Fetch the pull request head so both commits are local:
 git fetch -q origin pull/<number>/head
 ```
 
-A failed fetch stops the skill: `❌ Could not fetch the PR head. Retry once the remote is reachable.` Do not fall through to the full pass. A fetch failure and a rebase both leave the prior commit unreachable, and the fallback below states a rebase as fact on the pull request, so conflating the two publishes a claim the skill never checked.
+A failed fetch stops the skill: `❌ Could not fetch the PR head. Retry once the remote is reachable.` Never fall through to the full pass, since a fetch failure and a rebase both leave the prior commit unreachable, and the fallback states a rebase as fact on the pull request.
 
 Then test that the prior commit still reaches the head:
 
@@ -55,30 +72,48 @@ Then test that the prior commit still reaches the head:
 git merge-base --is-ancestor <prior-oid> <headRefOid>
 ```
 
-On exit zero, review `<prior-oid>..<headRefOid>` and nothing else. `git diff` and `git log --oneline` over that range are the whole read, because the first pass already covered everything behind it. A non-zero exit means the branch was rebased or force-pushed, so the delta is undefined rather than empty. Fall back to the full pass above and say so in the body.
+- On exit zero, `git diff` and `git log --oneline` over `<prior-oid>..<headRefOid>` are the whole read, since the first pass covered everything behind it
+- A non-zero exit means a rebase or force-push, so the delta is undefined rather than empty. Fall back to the full pass and say so in the body.
+
+## An unchanged head
 
-A commit is its own ancestor, so an unchanged head passes that test too, with an empty range. When `<prior-oid>` equals `<headRefOid>`, decide whether this pass has anything to add before reading anything else, since the empty range itself cannot answer that:
+A commit is its own ancestor, so an unchanged head passes that test with an empty range. When `<prior-oid>` equals `<headRefOid>`, decide whether this pass has anything to add before reading anything else:
 
 ```bash
 gh api --paginate 'repos/{owner}/{repo}/issues/<number>/comments?per_page=100' --jq '.[] | select(.body // "" | split("\n")[0] | rtrimstr("\r") | . == "## Review response" or . == "## Rebase" or . == "## Post-review findings") | select(.created_at > "<prior-at>") | .id' | tail -n 1
 ```
 
-`<prior-at>` is the instant Step 2 resolved above, which is the prior pass's `readAt` where it wrote one. Reading `submittedAt` off the thread here instead is the same submission-time defect on the time axis: a reply posted inside that pass's compose window sorts before the stamp and reads as already answered, when in fact the pass had stopped reading before it landed.
+`<prior-at>` is the prior pass's `readAt` where it wrote one. Reading `submittedAt` here is the submission-time defect on the time axis, since a reply posted inside that pass's compose window would read as already answered.
+
+- Scope the replies to those newer than the prior pass, since an unscoped read hands a re-run after a close-out the filename its prior pass already wrote
+- The REST `id` is the number the thread displays in each comment's anchor
+- Keep `tail` outside the filter for the same per-page reason as the reviews read
+
+### No reply since the prior pass
+
+An empty result means the head is unchanged and this pass has nothing new to add. Stop here, before Step 3 or Step 4 run: `❌ The head is unchanged since the prior pass on <short-sha>. Nothing new to review.`
+
+This is the earliest point every path crosses. A stop inside Step 4's filename derivation would sit on a step reached only when composing a body, which a shortcut path can route around.
+
+### A response or rebase reply
+
+A non-empty result carries the comment id Step 4 needs for the third filename segment. A `## Review response` answers a finding already argued, and a `## Rebase` reports a stale branch resolved without one.
 
-Scope the replies to those newer than the prior pass, never to every reply the thread carries. A pass answering the newest reply and a pass answering an older one derive the same third segment (Step 4), so an unscoped read hands a re-run after a close-out the name its own prior pass already wrote. That is the collision this case exists to prevent, reached without a rebase or an error.
+- Read it for what the worker changed or accepted, and treat an accepted finding as closed rather than restating it
+- Skip the diff and file reads below. This is the entire read on a repeated head, since the empty range cannot say whether a prior finding landed.
 
-The REST `id` is the number the thread displays in each comment's anchor. Keep `tail` outside the filter for the same per-page reason as the reviews read above.
+### A post-review findings reply
 
-An empty result means no reply arrived since the prior pass, so the head is unchanged and this pass has nothing new to add. Stop here, before Step 3 or Step 4 run: `❌ The head is unchanged since the prior pass on <short-sha>. Nothing new to review.` This is the earliest point every path crosses, which is why the check sits here rather than inside Step 4's filename derivation. A path that decides there is nothing to add never reaches a step reached only when composing a body, so a stop written there is a stop a shortcut path can route around.
+A `## Post-review findings` reply asserts a new defect rather than answering one, and this pass is its first independent reader. Restating it unread repeats the worker's claim.
 
-A non-empty result carries the comment id Step 4 needs for the third filename segment. A `## Review response` or a `## Rebase` reply answers a finding already argued or reports a stale branch resolved without one, so read it for what the worker changed or accepted, treat an accepted finding as closed rather than restating it, and skip the diff and file reads below. This is the entire read on a repeated head for either heading, since the empty range above has nothing in it to say whether a prior finding landed and neither reply needs anything more to answer that.
+Read the file it names at `<headRefOid>`, the same `git show <headRefOid>:<path>` read Step 3 runs to confirm a ticked box, and confirm the defect before it becomes this pass's own finding.
 
-A `## Post-review findings` reply carries no argued finding behind it, since it asserts a new defect rather than answering one, and this pass is its first independent reader. Restating it as a finding without opening anything is repeating the worker's claim rather than checking it. Read the file the comment names at `<headRefOid>`, the same `git show <headRefOid>:<path>` read Step 3 already runs to confirm a ticked box, and confirm the defect before it becomes a finding of this pass's own.
+## A closed verdict on a moved head
 
-A moved head has its own way to add nothing, which the ancestor test cannot see. When `<prior-heading>` reads `## Review closed`, the standing verdict already reports the branch clear, so a pass over the new commits that raises nothing posts a comment saying what the one above it said.
+A moved head has its own way to add nothing, which the ancestor test cannot see. When `<prior-heading>` reads `## Review closed`, a pass over the new commits that raises nothing would repeat the standing verdict. It arises when a prior pass leaves a change to the author's call, the author makes it, and the delta has nothing left to say.
 
-The producing shape is narrow. A prior pass tells the author a change is their own call, the author makes it, and the delta reaching the next pass has nothing left to say by construction.
+Carry `<prior-heading>` into Step 4 and run Step 3 unchanged. This guard turns on what the pass carries, which is Step 3's output, so deciding ahead of the review would swallow the pass that does find something, the costlier error.
 
-Carry `<prior-heading>` into Step 4 and run Step 3 unchanged. This guard cannot stop the pass the way the unchanged-head stop above does, because that stop reads an empty range and this one turns on what the pass carries, which is Step 3's output. Deciding ahead of the review would swallow the pass that does find something, and that is the costlier error, so the rule is stated beside its sibling and executed where the heading is picked.
+## The read
 
 Read each changed file in scope. Skip deleted files. Run reads in parallel.

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

@@ -9,7 +9,8 @@ Part of Step 7 of `review-ui`, reached only on the branch `post.md` names. The b
 
 When the newest UI verdict from Step 1 reads `## UI review closed` at an older head and this pass closes too, the thread already holds this verdict. Replace the standing close rather than posting a second one beside it.
 
-Only a closed prior is replaced. A prior `## UI review` stays in the thread when this pass closes, so the close posts normally. A pass that owes anything posts under `## UI review` normally too, whatever the prior read, since a rewrite there would hide a failed box behind a heading that reads closed.
+- Only a closed prior is replaced, so after a prior `## UI review` this pass's close posts normally
+- A pass that owes anything posts under `## UI review` whatever the prior read, since a rewrite would hide a failed box behind a closed heading
 
 Resolve the standing close's numeric id off the REST listing, keeping the newest match across every page:
 
@@ -40,8 +41,9 @@ gh api -X PUT repos/{owner}/{repo}/pulls/<number>/reviews/<review-id> -F body=@<
 
 ## The marker
 
-The body ends on `<!-- review-ui: head=<head> -->` at the full head this pass drove, with no line below it. `PUT` leaves the review's `commit.oid` pinned at the head the close was first posted against, and the marker is what `resolveUiScope`, the lift gate, and the orchestrator poll read in its place. A body missing it reads as the pinned stamp, so the lift refuses `ui-behind` and the poll reports the close as behind.
+The body ends on `<!-- review-ui: head=<head> -->` at the full head this pass drove, with no line below it. `PUT` leaves the review's `commit.oid` pinned at the head the close was first posted against, so `resolveUiScope`, the lift gate, and the orchestrator poll read the marker in its place.
 
-`PUT` keeps the comment's timestamp and its place in the thread, so the poll's age test reads a rewritten close as old, the same reading the code review accepts. A submitted review cannot be deleted, which is why this rewrites the standing close rather than replacing it with a fresh one.
-
-The frames the standing verdict linked sit under their own pass stamp on the frames branch. The new body links this pass's frames, and the old images stay reachable by path.
+- A body missing it reads as the pinned stamp, so the lift refuses `ui-behind` and the poll reports the close as behind
+- `PUT` keeps the comment's timestamp and place, so the poll's age test reads a rewritten close as old, the reading the code review accepts
+- A submitted review cannot be deleted, which is why this rewrites the standing close rather than posting a fresh one
+- The standing verdict's frames sit under their own pass stamp on the frames branch, so the new body links this pass's frames and the old stay reachable by path

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

@@ -32,7 +32,16 @@ A box written before that format may carry no route, no width, and a verb such a
 - Text, presence, and attributes: `pw --raw eval "<expression>"`, quoting the value back.
 - Computed style: `getComputedStyle(<element>).<property>`.
 - Geometry and overflow: `getBoundingClientRect()`, and `scrollWidth` against `clientWidth` on `document.documentElement`.
-- A frame: `pw screenshot --filename=frames/<box-number>.png`, then open it with the file-reading tool before saying what it shows. A taste box takes the shot twice, once per theme, naming the theme in the file as `frames/<box-number>-<theme>.png`. Reach each theme through the page's own control when the box names one, and through `pw set-color-scheme <dark|light>` otherwise, then read the page's background before the shot to confirm it changed. A page that paints the same under both has no second theme to show, so the box is not driven, with the reason naming that. `pw clear-color-scheme` restores the default.
+- A frame: `pw screenshot --filename=frames/<box-number>.png`, then open it with the file-reading tool before saying what it shows.
+
+### Taste frames
+
+A taste box takes the shot twice, once per theme, naming the theme in the file as `frames/<box-number>-<theme>.png`.
+
+- Reach each theme through the page's own control when the box names one, and through `pw set-color-scheme <dark|light>` otherwise
+- Read the page's background before the shot to confirm the theme changed
+- A page painting the same under both has no second theme, so the box is not driven, with the reason naming that
+- `pw clear-color-scheme` restores the default
 
 ## The four verdicts
 
@@ -45,8 +54,19 @@ Each box takes exactly one.
 | needs eyes          | The box ends in `(taste)`                               | The dark and the light shot as a pair, each the matching evidence stem or a pushed frame's link, and what the frames showed, with nothing about whether it looks right |
 | not driven          | The state could not be reached                          | The reason, such as an unreachable address, a `(local only)` box on a hosted preview, or a target the snapshot does not hold                                           |
 
-A pass or fail resting on a frame carries one image at most, and never one the worker's evidence already shows. A needs-eyes box carries the pair, dark and light, since a taste call is made by comparing them. Match each theme separately: when a state and stem in the evidence record match the box's route, width, and that theme, the evidence names that stem and nothing is pushed for it, so a view with the dark shot in evidence pushes the light one alone. Otherwise the frame goes up through `canon pr frames` with `--theme`, and the `link` the record returned, which names the frame's path on the frames branch, goes in the box's own section of the body and never inside a folded block. Either way the words stay, describing the value or region judged, such as the element, its position, and the colors or text read, so a reader whose image fails to load can still check it.
+A fail names what was expected beside what was read. A not driven never reads as a fail, since it says the pass could not look rather than that the page is wrong. Its reason says whether the cause sits on the page or off it, since only a cause on the page opens the heading Step 7 picks.
 
-A push that refuses leaves the words alone, with the reason named. Never cite the local frame path. A path under `.canon/` is a board identifier the label scan rejects, and it resolves only on this machine.
+### Which image a verdict carries
 
-A fail names what was expected beside what was read. A not driven never reads as a fail, since it says the pass could not look rather than that the page is wrong. Its reason says whether the cause sits on the page or off it, since only a cause on the page opens the heading Step 7 picks.
+A pass or fail resting on a frame carries one image at most, and never one the worker's evidence already shows. A needs-eyes box carries the pair, dark and light, since a taste call is made by comparing them.
+
+- Match each theme separately. An evidence stem matching the box's route, width, and theme is named and nothing is pushed for it.
+- A view with the dark shot in evidence therefore pushes the light one alone
+- Otherwise push the frame through `canon pr frames` with `--theme`, and put the returned `link` in the box's own section, never inside a folded block
+
+### The words beside an image
+
+Either way the words stay, describing the value or region judged, such as the element, its position, and the colors or text read, so a reader whose image fails to load can still check it.
+
+- A push that refuses leaves the words alone, with the reason named
+- Never cite the local frame path, since a path under `.canon/` is a board identifier the label scan rejects and resolves only on this machine

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

@@ -14,7 +14,11 @@ The heading reports whether the branch owes anything, the way the code review's
 - `## UI review` when a box failed, the sweep found a console error or an overflow, or a box was not driven for a cause on the page, such as a target the snapshot does not hold.
 - `## UI review closed` otherwise.
 
-A needs-eyes box leaves the review closed, and so does a box not driven for a cause off the page: an address that did not answer, or a `(local only)` box on a hosted preview. Each is owed to the person who merges rather than to the branch, and no commit on the branch can settle it, so opening the heading would hold the draft mark at every head. Name each such box in the count line's not-driven count and in its Not driven entry. Do not append the pull request number, which GitHub already renders.
+A needs-eyes box leaves the review closed, and so does a box not driven for a cause off the page, such as an address that did not answer or a `(local only)` box on a hosted preview.
+
+- Each is owed to the person who merges, and no commit can settle it, so opening the heading would hold the draft mark at every head
+- Name each such box in the count line's not-driven count and in its Not driven entry
+- Do not append the pull request number, which GitHub already renders
 
 ## The body
 
@@ -74,15 +78,35 @@ Driven at `<short-sha>` on <address>, rendered by <renderer>.
 
 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.
 
-Each section is dropped when it holds no box, along with its heading. Order is fixed: Failed, Needs your eyes, Not driven, then the folded blocks. A box takes exactly one section, chosen by its verdict, so a box that fails and also ends in `(taste)` appears once, under Failed.
+- Drop each section holding no box, along with its heading. Order is fixed: Failed, Needs your eyes, Not driven, then the folded blocks.
+- A box takes exactly one section by its verdict, so a box that fails and also ends in `(taste)` appears once, under Failed
+- Quote page text in backticks as content, never as the pass's own words
+
+### A failed box
+
+A box in a section opens on its number and the box as written, in bold, with the reading beneath it in words. A failed box that rests on a read has no image.
+
+- A failed box resting on a frame shows it inline under its heading, the `![box <n>](link)` embed with the link exactly as `canon pr frames` returned it
+- That link names the frame's path on the frames branch, which stays put while other pull requests' frames are dropped and carries this pass's stamp
+- A later pass therefore never changes the image
+
+### A needs-eyes box
 
-A box in a section opens on its number and the box as written, in bold, with the reading beneath it in words. A failed box that rests on a frame shows that frame inline under its heading, the `![box <n>](link)` embed with the link exactly as `canon pr frames` returned it. It names the frame's path on the frames branch, which stays put while other pull requests' frames are dropped and carries this pass's stamp, so a later pass never changes the image. A failed box that rests on a read has no image.
+A needs-eyes box shows its dark and light shots in a two-cell table ahead of anything else it carries, since the operator decides from them without opening the app. A box whose evidence holds one theme still renders both cells.
 
-A needs-eyes box shows its dark and light shots in a two-cell table ahead of anything else it carries, since the operator decides from them without opening the app. A cell is either the `link` Step 5 pushed or, for a theme the worker's evidence already shows, the evidence image at `https://github.com/<owner>/<repo>/blob/<head>/<path>?raw=true`, with `<path>` the matching state item's `path` off the evidence record. A box whose evidence holds one theme still renders both cells, one evidence link and one pushed link. A push that refused leaves its cell holding the words `not shown, <reason>`, so the table keeps its shape, and the box's line names what the frame showed. Never cite the local frame path, since a path under `.canon/` is a board identifier the label scan rejects.
+- A cell is the `link` Step 5 pushed, or for a theme the worker's evidence shows, `https://github.com/<owner>/<repo>/blob/<head>/<path>?raw=true`
+- `<path>` there is the matching state item's `path` off the evidence record
+- A refused push leaves its cell reading `not shown, <reason>`, so the table keeps its shape, and the box's line names what the frame showed
+- Never cite the local frame path, since a path under `.canon/` is a board identifier the label scan rejects
 
-The Passed block holds one row per passed box, with each row's measurement and the evidence stem it matched in backticks, so every reading stays one click away. A pass that cites a stem links it as the evidence image at the form above when the record holds the item. Omit the block when nothing passed.
+### The folded blocks
 
-Omit the Sweep block when it found nothing, and the Guessed wording block when every box named its route and width, and drop the folded block when both are empty. Quote page text in backticks as content, never as the pass's own words.
+The Passed block holds one row per passed box, with its measurement and the evidence stem it matched in backticks, so every reading stays one click away. A row citing a stem links it as the evidence image in the form above when the record holds the item.
+
+- Omit the Passed block when nothing passed, and the Sweep block when it found nothing
+- Omit the Guessed wording block when every box named its route and width, and drop the folded block when both are empty
+
+### An all-pass body
 
 A pass where every box passed is the heading, the count line, the folded Passed block, and the marker, with no empty headings:
 
@@ -104,23 +128,27 @@ The count line and the sections beneath it hold the same totals, and Step 10's p
 
 ## The marker
 
-End every body on `<!-- review-ui: head=<head> -->`, carrying the full sha Step 1 resolved. A body that replaces a standing close by `PUT` carries it too, at the head this pass drove. The orchestrator's poll reads it off the last non-empty line to decide whether the verdict covers the current head, and the submission stamp cannot answer that, since GitHub stamps it with whatever the head is at the moment of posting.
+End every body on `<!-- review-ui: head=<head> -->`, carrying the full sha Step 1 resolved. A body that replaces a standing close by `PUT` carries it too, at the head this pass drove.
 
-## Posting
+The orchestrator's poll reads it off the last non-empty line to decide whether the verdict covers the current head. The submission stamp cannot answer that, since GitHub stamps it with whatever the head is at the moment of posting.
 
-Run `canon labels scan --body-file .canon/tmp/pr/review-ui/body-<number>-<short-sha>.md` against the body first, which applies the rule in `${CLAUDE_SKILL_DIR}/../git-pr/references/publish.md`, since nothing gates a file under `.canon/tmp/` before the review-event run does. Fix the body and scan again on a finding. Then post it as a review rather than an issue comment, since the poll reads the UI family off reviews:
+## Posting
 
-Do not run the post below when the newest verdict from Step 1 reads `## UI review closed` at an older head and this pass closes too. That pass replaces the standing close, so read `${CLAUDE_SKILL_DIR}/references/close-out.md` instead of posting. Posting first leaves two closes, both naming a head.
+Run `canon labels scan --body-file .canon/tmp/pr/review-ui/body-<number>-<short-sha>.md` against the body first, which applies the rule in `${CLAUDE_SKILL_DIR}/../git-pr/references/publish.md`. Nothing gates a file under `.canon/tmp/` before the review-event run does. Fix the body and scan again on a finding.
 
-Record the instant just before the post, in UTC, as `<posted-at>`. Step 9 keeps only review-event runs created after it, since the code review posts its own review on the same head and fires a run of the same gate.
+- Post it as a review rather than an issue comment, since the poll reads the UI family off reviews
+- Skip the post when Step 1's newest verdict reads `## UI review closed` at an older head and this pass closes too, and read `${CLAUDE_SKILL_DIR}/references/close-out.md` instead
+- Posting first in that case leaves two closes, both naming a head
+- Record the instant just before the post, in UTC, as `<posted-at>`, since Step 9 keeps only review-event runs created after it
+- The code review posts its own review on the same head and fires a run of the same gate, which is why that cutoff matters
 
 ```bash
 date -u +%Y-%m-%dT%H:%M:%SZ
 gh api -X POST 'repos/{owner}/{repo}/pulls/<number>/reviews' -f event=COMMENT -F body=@.canon/tmp/pr/review-ui/body-<number>-<short-sha>.md --jq .html_url
 ```
 
-The post goes through the REST reviews endpoint rather than the `gh pr` review subcommand, which runs on GraphQL and fails where a cloud session's GitHub proxy refuses it. `-F` reads the file into the body, where `-f` would post the path itself.
-
-The ticks come after the post, in Step 8, so the verdict and the ticks report the same `<head>`. The post never ticks, and a pass that stops before posting ticks nothing.
+The post goes through the REST reviews endpoint, since the `gh pr` review subcommand runs on GraphQL and fails where a cloud session's GitHub proxy refuses it.
 
-Never pass `event=APPROVE` or `event=REQUEST_CHANGES`, which carry a state the poll does not read and a weight this pass has not earned.
+- `-F` reads the file into the body, where `-f` would post the path itself
+- The ticks come after the post, in Step 8, so the verdict and the ticks report the same `<head>`. A pass that stops before posting ticks nothing.
+- Never pass `event=APPROVE` or `event=REQUEST_CHANGES`, which carry a state the poll does not read and a weight this pass has not earned

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

@@ -132,6 +132,8 @@ A worker is a separate process the controller can steer, and scope reaches it th
 - Do not edit tracked files from this session, at any size. The boundary offers no proportionality exception and nothing enforces it.
 - Do not hand a worker anything but a plan, which carries exact diffs only when already known and otherwise states scope and open questions
 
+A late ask about a building row is a follow-up filed through `task-board`, with the ask as its origin and the running task cited in the intro. Amend the plan only on the operator's word, naming the re-review cost, and message the worker.
+
 The tracked-file boundary collides with `CLAUDE.md`, which says to handle a small edit immediately, and this rule wins wherever the two meet. A session that writes a change cannot review it independently afterwards, which is the separation `review-pr` exists to supply.
 
 ### Filing a row