@erclx/canon 5.40.0 → 5.42.0

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

@@ -11,25 +11,45 @@ Each number in the body traces to a source here, read through the `search-craft`
 
 Field: subtitling and captioning. Authorities: broadcasters' and streamers' published subtitle guidelines, and the captioning program that sets educational practice.
 
-**On screen for 5/6 of a second to 7 seconds, two lines, 42 characters a line.** Netflix's [Timed Text Style Guide: General Requirements](https://partnerhelp.netflixstudios.com/hc/en-us/articles/215758617-Timed-Text-Style-Guide-General-Requirements) states a minimum of 5/6 of a second (20 frames at 24 fps) and a maximum of 7 seconds per event, and its [English (USA) guide](https://partnerhelp.netflixstudios.com/hc/en-us/articles/217350977-English-USA-Timed-Text-Style-Guide) states 42 characters a line and two lines at most.
+| Rule                                       | Source                                                                                                                                                                                                     |
+| ------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| On screen for 5/6 of a second to 7 seconds | Netflix's [Timed Text Style Guide: General Requirements](https://partnerhelp.netflixstudios.com/hc/en-us/articles/215758617-Timed-Text-Style-Guide-General-Requirements), a minimum of 20 frames at 24 fps |
+| Two lines, 42 characters a line            | Netflix's [English (USA) guide](https://partnerhelp.netflixstudios.com/hc/en-us/articles/217350977-English-USA-Timed-Text-Style-Guide)                                                                     |
+| 20 characters per second, 17 for children  | The same English (USA) guide, adult and children's programs respectively                                                                                                                                   |
+| Never over what the frame is about         | The DCMP [Captioning Tip Sheet](https://dcmp.org/learn/225-captioning-tip-sheet): "Placement must not interfere with existing visuals/graphics."                                                           |
 
-**20 characters per second, 17 for children.** The same English (USA) guide, adult and children's programs respectively.
+### Start on the first frame of the action
 
-**Start on the first frame of the action.** Netflix's [Subtitle Timing Guidelines](https://partnerhelp.netflixstudios.com/hc/en-us/articles/360051554394-Timed-Text-Style-Guide-Subtitle-Timing-Guidelines) put a subtitle's in-time on the first frame of its audio. A software video's caption names an action rather than a line of speech, so the body keys the in-time on the action's first frame.
+Netflix's [Subtitle Timing Guidelines](https://partnerhelp.netflixstudios.com/hc/en-us/articles/360051554394-Timed-Text-Style-Guide-Subtitle-Timing-Guidelines) put a subtitle's in-time on the first frame of its audio. A software video's caption names an action rather than a line of speech, so the body keys the in-time on the action's first frame.
 
-**Never over what the frame is about.** The DCMP [Captioning Tip Sheet](https://dcmp.org/learn/225-captioning-tip-sheet): "Placement must not interfere with existing visuals/graphics."
+### Captions name what the frame shows
 
-**Captions name what the frame shows.** No source states this for a software video. It is the operator's read of an unguided render whose caption narrated the whole flow, kept because the timing rules above already assume a caption tied to one moment.
+No source states this for a software video. It is the operator's read of an unguided render whose caption narrated the whole flow, kept because the timing rules above already assume a caption tied to one moment.
 
 ## Zoom
 
 Fields: interface motion design, and screen recording practice. Authorities: design systems that publish motion specs, and the reference documentation of a screen recording tool.
 
-**A push onto an action no faster than HyperFrames' floor, never past 1 second.** HyperFrames' `viewport-change` rule states a zoom of 1.0 to 2.0 seconds and gives its reason beside the value: "under 0.8s teleports, over 2.5s drags". The body keeps that floor by pointing at the rule rather than restating it. The 1 second ceiling has two grounds. Measured: an unguided render pushed in over 2.2 seconds and a second over 1.4 seconds, and the operator judged both slow, so the range's lower half already reads slow on a push onto a click. Published: Material Design 3's [easing and duration tokens](https://m3.material.io/styles/motion/easing-and-duration/tokens-specs) end their scale at 1000 ms, the top of the extra-long band they reserve for ambient transitions, so no input-driven transition in that system runs longer.
+### A push onto an action stays under 1 second
 
-**Zoom on a click.** Screen Studio's [auto zoom guide](https://screen.studio/guide/auto-zoom) keys its zoom on click positions and zooms nowhere a click did not occur.
+The floor is HyperFrames'. Its `viewport-change` rule states a zoom of 1.0 to 2.0 seconds with the reason beside it, "under 0.8s teleports, over 2.5s drags", and the body points at the rule rather than restating it.
 
-**Conflict, and the pick.** HyperFrames' range and the measured renders disagree on the push onto an action, and the body takes the overlap: HyperFrames' teleport floor below, and 1 second above, which sits inside HyperFrames' range at its fast end. HyperFrames' full range stays with an ambient reveal, which matches Material's own split between input-driven and ambient motion. A tighter band was considered and declined. Material puts large expressive transitions at 450 to 600 ms, and Nielsen Norman Group's [animation duration article](https://www.nngroup.com/articles/animation-duration/) calls 400 ms "very slow", but both write for an interface a user waits on, which a video viewer is not, and that band sits below HyperFrames' stated teleport floor with nothing measured to show it reads right. Narrow the band once a composed demo is compared against the unguided renders.
+- Measured: an unguided render pushed in over 2.2 seconds and a second over 1.4 seconds, and the operator judged both slow, so the range's lower half already reads slow on a push onto a click
+- Published: Material Design 3's [easing and duration tokens](https://m3.material.io/styles/motion/easing-and-duration/tokens-specs) end at 1000 ms, the top of a band reserved for ambient transitions, so no input-driven transition there runs longer
+
+### Zoom on a click
+
+Screen Studio's [auto zoom guide](https://screen.studio/guide/auto-zoom) keys its zoom on click positions and zooms nowhere a click did not occur.
+
+### Conflict, and the pick
+
+HyperFrames' range and the measured renders disagree on the push onto an action. The body takes the overlap, HyperFrames' teleport floor below and 1 second above, which sits inside HyperFrames' range at its fast end.
+
+- HyperFrames' full range stays with an ambient reveal, matching Material's own split between input-driven and ambient motion
+- A tighter band was declined. Material puts large expressive transitions at 450 to 600 ms, and Nielsen Norman Group's [animation duration article](https://www.nngroup.com/articles/animation-duration/) calls 400 ms "very slow".
+- Both write for an interface a user waits on, which a video viewer is not, and that band sits below HyperFrames' teleport floor with nothing measured to show it reads right
+
+Narrow the band once a composed demo is compared against the unguided renders.
 
 ## Pointer
 
@@ -39,28 +59,52 @@ The two pointer rules in the body carry no number. One pointer on a frame and a
 
 Fields: web accessibility, and audio post-production. Authorities: the W3C's accessibility guidelines, and the audio engineering society's streaming recommendation.
 
-**Music at least 20 dB under the voice.** WCAG 2.1 [Success Criterion 1.4.7](https://www.w3.org/WAI/WCAG21/Understanding/low-or-no-background-audio.html): "The background sounds are at least 20 decibels lower than the foreground speech content, with the exception of occasional sounds that last for only one or two seconds."
+### Music at least 20 dB under the voice
+
+WCAG 2.1 [Success Criterion 1.4.7](https://www.w3.org/WAI/WCAG21/Understanding/low-or-no-background-audio.html) is the source, reading "The background sounds are at least 20 decibels lower than the foreground speech content, with the exception of occasional sounds that last for only one or two seconds."
+
+HyperFrames' `media-use` sets its narrated bed at a volume of 0.12, about 18 dB under a voice at full scale. The body takes WCAG's 20 dB, since it is the published floor and the bed default sits 2 dB short of it.
+
+### Overall loudness is delegated
 
-**Conflict, and the pick.** HyperFrames' `media-use` sets its narrated bed at a volume of 0.12, about 18 dB under a voice at full scale. The body takes WCAG's 20 dB, since it is the published floor and the bed default sits 2 dB short of it.
+The AES [TD1008](https://aes.org/wp-content/uploads/2024/01/20210924_TD1008_v3.13.pdf) streaming recommendation normalizes speech to -18 LUFS with a true peak no higher than -1 dBTP. `media-use` ships -14 and -16 LUFS targets for social and podcast delivery.
 
-**Overall loudness is delegated.** The AES [TD1008](https://aes.org/wp-content/uploads/2024/01/20210924_TD1008_v3.13.pdf) streaming recommendation normalizes speech to -18 LUFS with a true peak no higher than -1 dBTP, while `media-use` ships -14 and -16 LUFS targets for social and podcast delivery. The body states no overall target, since the right one depends on where the video is published and `media-use` owns that operation.
+The body states no overall target, since the right one depends on where the video is published and `media-use` owns that operation.
 
 ## Voiceover
 
 Field: captioning, for the reading ceiling a voiceover's captions inherit. Authority: the captioning program's presentation rate guidance.
 
-**At or under 160 words a minute when captioned.** The DCMP [Captioning Key: Presentation Rate](https://dcmp.org/learn/601-captioning-key---presentation-rate) caps upper-level captions at 160 words a minute. `hyperframes-creative`'s narration reference states 2.5 words a second, 150 a minute, which sits under the ceiling, so the two do not conflict. An open search of voiceover practitioners put explainers at 140 to 160 words a minute, which agrees.
+### At or under 160 words a minute when captioned
 
-Narration has no standards body for pace, and the scoped search found none, so the body sets only the ceiling captions impose and points at HyperFrames for the pace itself.
+The DCMP [Captioning Key: Presentation Rate](https://dcmp.org/learn/601-captioning-key---presentation-rate) caps upper-level captions at 160 words a minute.
+
+- `hyperframes-creative`'s narration reference states 2.5 words a second, 150 a minute, under the ceiling, so the two do not conflict
+- An open search of voiceover practitioners put explainers at 140 to 160 words a minute, which agrees
+- Narration has no standards body for pace, and the scoped search found none, so the body sets only the ceiling and points at HyperFrames for pace
 
 ## Declined
 
-**Restating HyperFrames' motion rules.** Ease variety, anchoring, click timing, the scale and dwell of a zoom, and title-safe margins are stated in HyperFrames' own skills, which update on their own cadence. A copy here goes stale on theirs.
+Each item below stays out of the body for the reason given.
+
+### Restating HyperFrames' motion rules
+
+Ease variety, anchoring, click timing, the scale and dwell of a zoom, and title-safe margins are stated in HyperFrames' own skills, which update on their own cadence. A copy here goes stale on theirs.
+
+### A loudness target in the body
+
+See Audio above.
+
+### Pointer smoothing and hiding at rest
+
+Screen Studio's [cursor guide](https://screen.studio/guide/cursor) smooths the pointer and hides it when idle, and its [guide to disabling smooth movement](https://screen.studio/guide/disable-smooth-mouse-movement) turns smoothing off for a dropdown menu.
+
+Both are recorder settings. A take is composed with its pointer baked into the frames, so a session composing from it cannot change either, and they belong to whatever records the take.
 
-**A loudness target in the body.** See Audio above.
+### Zoom out before a cut, and a sound effect only on a meaningful click
 
-**Pointer smoothing and hiding at rest.** Screen Studio's [cursor guide](https://screen.studio/guide/cursor) smooths the pointer and hides it when idle, and its [guide to disabling smooth movement](https://screen.studio/guide/disable-smooth-mouse-movement) turns smoothing off for a dropdown menu. Declined because both are recorder settings. A take is composed with its pointer already baked into the frames, so a session composing from it cannot change either. They belong to whatever records the take.
+Neither has a source, and no operator read stands behind either, so both stay out until one does.
 
-**Zoom out before a cut, and a sound effect only on a click that changes something.** Neither has a source, and no operator read stands behind either, so both stay out until one does.
+### Vertical 9:16 framing
 
-**Vertical 9:16 framing.** Every video measured when this skill was written was landscape. Add it when a project asks for vertical video, with its safe areas sourced from the platform's own creator documentation.
+Every video measured when this skill was written was landscape. Add it when a project asks for vertical video, with its safe areas sourced from the platform's own creator documentation.

package/claude/skills/write-human/references/adopted.md

@@ -11,23 +11,34 @@ Neither was imported wholesale, and one measurement settles why. Read this befor
 
 ## What was adopted
 
-Roughly half the pattern catalog had no counterpart in this corpus, and six of those patterns are now in `machine-tells.md`: rule-of-three, synonym cycling, false ranges, inline-header lists, adverb propping, and passive voice with an unnamed actor. Each is a shape rather than a token, which is what kept it out of a ban list that matches words.
+Roughly half the pattern catalog had no counterpart in this corpus. Six of those patterns are now in `machine-tells.md`, each a shape rather than a token, which kept it out of a ban list that matches words.
+
+- Rule-of-three, synonym cycling, and false ranges
+- Inline-header lists, adverb propping, and passive voice with an unnamed actor
+
+### The density layer
 
 The density layer had no counterpart at all and is now `density.md`. Its useful half is the split between what a compression pass may cut and what it may not, since a terse register already instructs a session to cut and names nothing that has to survive.
 
-The ambiguity rules travel with that layer for the same reason. Compression is what creates the ambiguity, so a rule about pronouns and modifiers belongs beside the rule that shortened the sentence.
+The ambiguity rules travel with that layer. Compression creates the ambiguity, so a rule about pronouns and modifiers belongs beside the rule that shortened the sentence.
 
 ## What was declined
 
-- **The ban on abstract metaphor nouns.** The nouns it names are load-bearing terms in this corpus rather than decoration, and the count below is what decides it.
-- **Document mode as a selector.** The source has the writer pick a mode before drafting. In this corpus a document's shape is already fixed by the standard governing its type, so a mode selector adds a second authority over one question and the two will disagree.
-- **A voice register per surface.** One baseline covers every surface. A surface needing a warmer register states its own voice and claims the yield, which lifts voice alone and leaves the bans, the rhythm rules, and the tells in force.
+- **The ban on abstract metaphor nouns.** The nouns it names are load-bearing terms in this corpus rather than decoration, and the count below decides it.
+- **Document mode as a selector.** In this corpus the standard governing a document's type already fixes its shape, so a mode picked before drafting adds a second authority over one question.
+- **A voice register per surface.** One baseline covers every surface. A surface needing a warmer register states its own voice and claims the yield, which lifts voice alone.
+
+### The count behind the first
 
-The first of those three rests on a count. The source names `surface` among the nouns it bans, and tracked markdown in the authoring repository used `surface` 593 times, `harness` 95, `scaffolding` 17, and `primitive` 4. Adopting the item either rewrites established vocabulary across the corpus or is ignored in silence, and a reader arriving later cannot tell which happened.
+The source names `surface` among the nouns it bans. Tracked markdown in the authoring repository used `surface` 593 times, `harness` 95, `scaffolding` 17, and `primitive` 4.
+
+Adopting the item either rewrites established vocabulary across the corpus or is ignored in silence, and a reader arriving later cannot tell which happened.
 
 ## What moved in from the markdown standard
 
-The marketing words and vague qualifiers under `## Voice` were a gated word set in the markdown standard until the audit narrowed to characters. A word ban catches the token and misses the habit behind it, so a writer swaps `robust` for a synonym and the claim stays unproven. The list now lives here as guidance a reader applies, and this body is its one copy, since no command reads it and a second copy would drift with nothing comparing the two.
+The marketing words and vague qualifiers under `## Voice` were a gated word set in the markdown standard until the audit narrowed to characters. A word ban catches the token and misses the habit, so a writer swaps `robust` for a synonym and the claim stays unproven.
+
+The list now lives here as guidance a reader applies. This body is its one copy, since no command reads it and a second copy would drift with nothing comparing the two.
 
 ## Where this diverges
 
@@ -37,4 +48,6 @@ The source material also prefers shorter sentences without bound. This skill mea
 
 ## The industry-guide record
 
-The cadence rules and the bans they pair with trace to three industry style guides, being Google's developer documentation style guide, Microsoft's writing style guide, and Apple's style guide. The authoring toolkit keeps the per-rule attributions and the dates each guide was read, and no install carries that record, so this file is the position a target reads.
+The cadence rules and the bans they pair with trace to three industry style guides, being Google's developer documentation style guide, Microsoft's writing style guide, and Apple's style guide.
+
+The authoring toolkit keeps the per-rule attributions and the dates each guide was read. No install carries that record, so this file is the position a target reads.

package/docs/workflow/parallel-features.md

@@ -11,7 +11,7 @@ Run independent features in parallel, one git worktree and one Claude Code sessi
 ## One worktree per feature
 
 - Invoke `canon:plan-feature` in each session. Plans land at `.canon/plans/feature-<slug>.md` at the main root.
-- `ui-checklist` writes a per-branch handoff at `tmp/handoff/ui-checklist/<slug>.md`, which `git-pr` posts and removes. The slug is the branch name minus its leading type segment.
+- `ui-checklist` writes a per-branch handoff at `tmp/handoff/ui-checklist/<slug>.md`, which `pr-evidence` posts and removes. The slug is the branch name minus its leading type segment.
 - Ship each worktree with `canon:git-ship`, or `canon:auto-ship` for a draft pull request
 - Only the operator or the controlling session readies a draft
 
@@ -41,6 +41,7 @@ Assert the orchestrator role in one warm session with `canon:role-orchestrator`.
 
 Merge order matters only when two branches touch the same file. Expect to rebase over `CLAUDE.md`, `tooling/**`, `canon/context/context-model.md`, `docs/agents/`, and any folder's `index.md`. Resolve an `index.md` conflict with `canon indexes regen` over the rebased tree.
 
+- **Fan-in.** Batches of one change sharing edge files ship as one pull request, opened by an integrator that merges each member branch. See `claude/skills/plan-feature/references/batches.md`.
 - **Merge order.** Merge the smallest hotspot footprint first, and a branch touching `CLAUDE.md` or a context entry last.
 - **Rebase.** The branch merging second runs `/review-address`, which trial-merges against `origin/main` and rebases. Push, then merge.
 - **Clean up.** Run `/git-worktree cleanup` to remove merged worktrees. To start fresh, `ExitWorktree(action: "keep")`, then `/session-worktree <new-name>`.

package/docs/workflow/skill-map.md

@@ -67,7 +67,7 @@ Groups run in the order a project meets them. Every name `canon claude skills li
 | `canon:docs-sync`     | A change left `README.md` or `docs/` stale    |
 | `canon:git-stage`     | Staged changes span several concerns          |
 | `canon:git-commit`    | Staged changes are one concern                |
-| `canon:git-branch`    | A branch name needs generating or renaming    |
+| `canon:git-branch`    | A branch needs creating, naming, or renaming  |
 | `canon:git-pr`        | A pull request needs a title and body         |
 
 ## After the pull request opens
@@ -78,6 +78,7 @@ Groups run in the order a project meets them. Every name `canon claude skills li
 | `canon:review-ui`      | Beside code review, to drive the checklist    |
 | `canon:review-address` | As the worker, to fix posted findings         |
 | `canon:git-followup`   | A small edit on a branch with an open PR      |
+| `canon:pr-evidence`    | A new head needs its screenshots re-posted    |
 | `canon:git-split`      | A branch carries unrelated commits            |
 | `canon:git-issue`      | Something belongs on the tracker              |
 | `canon:git-worktree`   | After a merge, to reclaim worktrees           |

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@erclx/canon",
   "type": "module",
-  "version": "5.40.0",
+  "version": "5.42.0",
   "description": "Runs your agent's work and keeps its code good, on one setup for every repo.",
   "license": "MIT",
   "bin": {

package/src/claude/cases/git.ts

@@ -6,6 +6,10 @@ export const GIT_CASES: readonly SkillCase[] = [
     prompt: 'Come up with a conventional name for this branch.',
     expect: 'git-branch',
   },
+  {
+    prompt: 'I am on main and about to start a feature, create its branch.',
+    expect: 'git-branch',
+  },
   {
     prompt: "Turn what's staged into one commit message.",
     expect: 'git-commit',

package/src/claude/cases/workflow.ts

@@ -81,6 +81,11 @@ export const WORKFLOW_CASES: readonly SkillCase[] = [
       'Open the preview for that pull request and click through each box on its visual checklist, then post what happened.',
     expect: 'review-ui',
   },
+  {
+    prompt:
+      'I pushed another commit to the open PR. Update the screenshot comparison on it so the reviewer sees the current head.',
+    expect: 'pr-evidence',
+  },
   {
     prompt:
       'The screencast draft is finished. Turn it into an actual video now.',

package/src/commands/pr.ts

@@ -57,6 +57,7 @@ import {
   pruneFramesWithLegacy,
   pushFrame,
   readFrame,
+  referenceSlug,
   type TreeEntry,
 } from '@/pr/frames'
 import { type HeadRefusal, resolveHead, resolveTip } from '@/pr/head'
@@ -106,7 +107,12 @@ import {
   reviewRowOf,
   selectBranchPull,
 } from '@/pr/rest'
-import { resolveReviewScope } from '@/pr/review-scope'
+import {
+  readReviewState,
+  type ReviewStateApi,
+  type ReviewStateRecord,
+  waitForReviews,
+} from '@/pr/review-state'
 import { PROJECT_ROOT } from '@/roots/project'
 import { intro, logInfo, logStep, logWarn, outro, plural } from '@/cli/ui'
 
@@ -139,6 +145,10 @@ interface LiftCommandOptions extends ReadOptions {
   readonly wait?: string
 }
 
+interface ReviewStateOptions extends ReadOptions {
+  readonly wait?: string
+}
+
 interface LocalOptions extends ReadOptions {
   readonly remove?: boolean
 }
@@ -184,6 +194,7 @@ const LOCAL_REFUSALS: Record<LocalRefusal | 'gh-failed', string> = {
 interface FramesOptions extends ReadOptions {
   readonly add?: string
   readonly box?: string
+  readonly reference?: string
   readonly head?: string
   readonly pass?: string
   readonly theme?: string
@@ -196,6 +207,7 @@ type FramesCommandRefusal =
   | 'bad-mode'
   | 'no-number'
   | 'bad-box'
+  | 'bad-reference'
   | 'bad-head'
   | 'bad-pass'
   | 'bad-theme'
@@ -212,13 +224,15 @@ const FRAMES_REFUSALS: Record<FramesCommandRefusal, string> = {
   'no-number':
     '--add and --drop write for one pull request, so name its number.',
   'bad-box':
-    '--add takes --box <n>, a positive whole number naming the checklist box.',
+    '--add takes --box <n>, a positive whole number naming the checklist box, or --reference <page>/<frame>, never both.',
+  'bad-reference':
+    '--reference takes <page>/<frame>, each half opening on a letter or digit and holding only letters, digits, dots, underscores, and dashes, with no `--` in either, so the capture files under a name that reads back as the frame.',
   'bad-head':
     '--head takes a commit sha, 7 to 40 lowercase hex characters. A branch name or a path would file the frame under a folder that names no commit.',
   'bad-pass':
     '--add takes --pass <stamp>, the instant the pass started in compact UTC such as 20261002T154450Z, so a second pass never replaces an earlier one.',
   'bad-theme':
-    '--theme takes dark or light and goes with --add, so a second shot of one box never replaces the first.',
+    '--theme takes dark or light and goes with --add --box, so a second shot of one box never replaces the first.',
   'bad-days': '--prune takes a positive whole number of days.',
   'unreadable-frame':
     'The file named by --add is missing, empty, or not a PNG, so it would embed as a broken image. Nothing is pushed.',
@@ -556,11 +570,17 @@ export function register(program: Command): void {
     })
 
   pr.command('review-state')
-    .description('Report the commit and instant the last review pass covered')
+    .description(
+      'Report what the last code review and UI review passes covered at the tip',
+    )
     .argument('[number]', 'Pull request to read, defaulting to this branch')
     .helpOption('-h, --help', 'Show this help message')
     .option('--root <path>', 'Repository to read, defaulting to the cwd')
     .option('--json', 'Add a machine-readable record on stdout')
+    .option(
+      '--wait <seconds>',
+      `Hold until a pass covers the tip in every bound family, default ${DEFAULT_WAIT_SECONDS}`,
+    )
     .addHelpText(
       'after',
       [
@@ -582,6 +602,31 @@ export function register(program: Command): void {
         '  fallback  a pass posted before the marker shipped, off GitHub stamps',
         '  none      the thread carries no pass, so the next one is a first pass',
         '',
+        'Those code review fields stay at the top level of the record. Beside',
+        'them, `head` is the branch tip read from the remote, and `review` and',
+        '`ui` carry each family at that tip:',
+        '  reason     the refusal `canon pr lift` gives the family, absent when',
+        '             its gate passes, read through the same gate function',
+        '  isCovered  a pass covers the tip: the gate passes, or the newest pass,',
+        '             open or unmarked, names the tip',
+        '',
+        '`ui` also carries the newest `## UI review` pass (`heading`, `state`,',
+        '`commit`, `source`), `isBound`, which is whether the evidence comment',
+        'carries a checklist, and `carriedFrom` or `paintedPaths` when the lift',
+        'carried a close forward or refused to. An unbound family reads covered.',
+        '',
+        'Both families post as pull request reviews, so this reads',
+        '`pulls/<n>/reviews` alone, as the lift does. Issue comments are not',
+        'read: neither review skill posts there, and a heading found only in a',
+        'comment would let a worker move on a pass the lift then refuses.',
+        '',
+        '`--wait <seconds>` holds until `isCovered` reads true in both families',
+        'or the deadline passes, re-reading the tip every 30 seconds so a push',
+        'moves what a pass must cover. The evidence is read once at the start.',
+        'The record then adds `reason`, `covered` or `timeout`, and',
+        '`waitedSeconds`. A wait past 600 seconds outlasts a foreground shell',
+        'call, so run it in the background.',
+        '',
         'Refusals, read off `reason`:',
         '  ambiguous-pull    two open pull requests share the branch against',
         '                    different bases, so name a number',
@@ -594,18 +639,22 @@ export function register(program: Command): void {
         '  gh-missing        `gh` is not on the path, so no pull request resolved',
         '  gh-failed         `gh` could not answer for this branch, so name a number',
         '  no-object-head    the pull request object reported no head commit',
+        '  bad-wait          --wait takes a whole number of seconds',
         '',
         'Exit codes:',
-        '  0  the thread was read, whether it carries a pass or not',
-        '  1  refused, with the reason on stderr or in the JSON record',
+        '  0  the thread was read, whether it carries a pass or not, or the',
+        '     wait ended covered',
+        '  1  refused, with the reason on stderr or in the JSON record, or the',
+        '     wait reached its deadline as `timeout`',
         '',
         'Examples:',
         '  canon pr review-state',
         '  canon pr review-state 1341 --json',
+        '  canon pr review-state 1341 --wait 1200 --json',
         '',
       ].join('\n'),
     )
-    .action(async (number: string | undefined, opts: ReadOptions) => {
+    .action(async (number: string | undefined, opts: ReviewStateOptions) => {
       process.exitCode = await runReviewState(number, opts)
     })
 
@@ -1011,6 +1060,10 @@ export function register(program: Command): void {
     .option('--json', 'Add a machine-readable record on stdout')
     .option('--add <file>', 'Push this PNG as a frame')
     .option('--box <n>', 'The checklist box the frame shows, with --add')
+    .option(
+      '--reference <address>',
+      'The design reference the capture shows, as <page>/<frame>, with --add in place of --box',
+    )
     .option(
       '--head <sha>',
       "The head the frame was driven at, with --add, defaulting to the pull request's",
@@ -1035,7 +1088,8 @@ export function register(program: Command): void {
         `An add writes only refs/heads/${FRAMES_BRANCH}, through the GitHub git data API,`,
         'so nothing is checked out and no other branch is touched. A frame lands',
         'at pr-<number>/<short-head>/<pass>/box-<n>.png, or box-<n>-<theme>.png',
-        'with --theme, and `link` names that',
+        'with --theme, or ref-<page>--<frame>.png for a design reference capture',
+        'passed as --reference <page>/<frame> in place of --box, and `link` names that',
         `path on ${FRAMES_BRANCH}, so it survives a rewrite that drops other pull`,
         'requests and resolves until its own pull request is dropped. The pass',
         'segment keeps a second pass at one head and box from replacing an image',
@@ -1056,10 +1110,11 @@ export function register(program: Command): void {
         '  ok                an add pushed, or a drop or prune finished',
         '  bad-mode          not exactly one of --add, --drop, --prune',
         '  no-number         --add or --drop named no pull request',
-        '  bad-box           --add without a positive --box',
+        '  bad-box           --add with both --box and --reference, or neither',
+        '  bad-reference     --reference is not <page>/<frame> in the safe name form',
         '  bad-head          --head is not 7 to 40 lowercase hex characters',
         '  bad-pass          --add without a compact UTC --pass stamp',
-        '  bad-theme         --theme is not dark or light, or no --add',
+        '  bad-theme         --theme is not dark or light, or no --add, or rides a --reference',
         '  bad-days          --prune without a positive number of days',
         '  unreadable-frame  the --add file is missing, empty, or not a PNG',
         '  read-only         GitHub refused the write, as on a fork token',
@@ -1807,13 +1862,21 @@ async function runChecks(
 
 async function runReviewState(
   number: string | undefined,
-  opts: ReadOptions,
+  opts: ReviewStateOptions,
 ): Promise<number> {
   const root = resolve(opts.root ?? process.cwd())
   const emitJson = opts.json ?? false
 
   intro('canon pr review-state')
 
+  let waitSeconds: number | undefined
+  if (opts.wait !== undefined) {
+    if (!/^\d+$/.test(opts.wait)) {
+      return refuseWith('bad-wait', LIFT_REFUSALS['bad-wait'], emitJson, root)
+    }
+    waitSeconds = Number(opts.wait)
+  }
+
   if (Bun.which('gh') === null) {
     return refuseWith('gh-missing', PULL_REFUSALS['gh-missing'], emitJson, root)
   }
@@ -1830,20 +1893,84 @@ async function runReviewState(
     )
   }
 
-  const reviews = await listReviews(root, resolved.number)
-  if (reviews.kind === 'refused') {
-    const reason =
-      reviews.reason === 'gh-failed' ? 'gh-failed' : 'reviews-unreadable'
-    return refuseWith(reason, PULL_REFUSALS[reason], emitJson, root)
+  const read = await readIdentity(root, resolved.number)
+  if (read.kind === 'refused') {
+    return refuseWith(read.reason, PULL_REFUSALS[read.reason], emitJson, root)
   }
 
-  const listing = { number: Number(resolved.number) }
-  const scope = resolveReviewScope({
-    reviews: reviews.rows.map(reviewRowOf),
-  })
+  // The module refuses every failed read as `gh-failed`. The api keeps each
+  // read's own reason, so a caller still tells an unreadable thread from an
+  // unreadable remote.
+  let failure: PullRefusal | HeadRefusal = 'gh-failed'
+  const git = gitRunner(root)
+  const api: ReviewStateApi = {
+    readTip: async () => {
+      const tip = await resolveTip(read.identity.branch, refReader(root))
+      if (tip.kind === 'read') return tip.tip
+      failure = tip.reason
+      return undefined
+    },
+    readReviews: async () => {
+      const reviews = await listReviews(root, resolved.number)
+      if (reviews.kind === 'read') return reviews.rows.map(reviewRowOf)
+      failure =
+        reviews.reason === 'gh-failed' ? 'gh-failed' : 'reviews-unreadable'
+      return undefined
+    },
+    readEvidence: () => readEvidenceGate(root, resolved.number),
+    readChanged: (from, to) => readChangedPaths(git, from, to),
+    sleep: (ms) => new Promise((done) => setTimeout(done, ms)),
+    now: () => Date.now(),
+  }
+
+  const painted = loadPaintedPatterns(root)
+  const wait =
+    waitSeconds === undefined
+      ? undefined
+      : await waitForReviews(api, { waitSeconds, painted })
+  const state = wait ?? (await readReviewState(api, painted))
+  if (state.kind === 'refused') {
+    return refuseWith(failure, PULL_REFUSALS[failure], emitJson, root)
+  }
+
+  const { record } = state
+  const pull = Number(resolved.number)
+  logReviewState(pull, record)
+  const waited =
+    wait?.kind === 'read'
+      ? { reason: wait.reason, waitedSeconds: wait.waitedSeconds }
+      : undefined
+  if (waited !== undefined) {
+    logStep(waited.reason === 'covered' ? 'Covered' : 'Timeout')
+    logInfo(
+      waited.reason === 'covered'
+        ? `a pass covers ${record.head.slice(0, 8)} in every bound family after ${waited.waitedSeconds}s`
+        : `no pass covered ${record.head.slice(0, 8)} in every bound family within ${waited.waitedSeconds}s`,
+    )
+  }
+
+  outro()
+
+  if (emitJson) {
+    const { scope, ...families } = record
+    process.stdout.write(
+      `${JSON.stringify({
+        root,
+        number: pull,
+        ...scope,
+        ...families,
+        ...waited,
+      })}\n`,
+    )
+  }
 
+  return waited?.reason === 'timeout' ? 1 : 0
+}
+
+function logReviewState(number: number, record: ReviewStateRecord): void {
+  const { scope } = record
   logStep('Scope')
-  logInfo(`#${listing.number}`)
+  logInfo(`#${number} at ${record.head.slice(0, 8)}`)
 
   if (scope.source === 'none') {
     logStep('First pass')
@@ -1863,19 +1990,17 @@ async function runReviewState(
     )
   }
 
-  outro()
-
-  if (emitJson) {
-    process.stdout.write(
-      `${JSON.stringify({
-        root,
-        number: listing.number,
-        ...scope,
-      })}\n`,
-    )
+  for (const [name, family] of [
+    ['review', record.review],
+    ['ui', record.ui],
+  ] as const) {
+    const line = `${name}: ${family.reason ?? 'clear'}, ${family.isCovered ? 'a pass covers the tip' : 'no pass covers the tip'}`
+    if (family.isCovered) logInfo(line)
+    else logWarn(line)
+  }
+  if (!record.ui.isBound) {
+    logInfo('ui: the evidence carries no checklist, so the family is unbound')
   }
-
-  return 0
 }
 
 interface PullFiles {
@@ -3084,10 +3209,18 @@ function framesArgumentRefusal(
   if (number === undefined || !POSITIVE_WHOLE.test(number)) return 'no-number'
   if (
     opts.add !== undefined &&
-    (opts.box === undefined || !POSITIVE_WHOLE.test(opts.box))
+    (opts.box === undefined) === (opts.reference === undefined)
   ) {
     return 'bad-box'
   }
+  if (opts.add !== undefined && opts.box !== undefined) {
+    if (!POSITIVE_WHOLE.test(opts.box)) return 'bad-box'
+  }
+  if (opts.reference !== undefined) {
+    if (opts.add === undefined || referenceSlug(opts.reference) === undefined) {
+      return 'bad-reference'
+    }
+  }
   if (opts.head !== undefined && !isFrameHead(opts.head)) return 'bad-head'
   if (
     opts.add !== undefined &&
@@ -3097,7 +3230,9 @@ function framesArgumentRefusal(
   }
   if (
     opts.theme !== undefined &&
-    (opts.add === undefined || !isFrameTheme(opts.theme))
+    (opts.add === undefined ||
+      opts.reference !== undefined ||
+      !isFrameTheme(opts.theme))
   ) {
     return 'bad-theme'
   }
@@ -3199,7 +3334,8 @@ async function runFrames(
   if (head === undefined || head === '') return refuseFrames('no-object-head')
   if (!isFrameHead(head)) return refuseFrames('bad-head')
 
-  const box = Number(opts.box)
+  const box = opts.box === undefined ? undefined : Number(opts.box)
+  const reference = opts.reference
   const pass = opts.pass ?? ''
   const theme = opts.theme as FrameTheme | undefined
   const result = await pushFrame(api, {
@@ -3207,6 +3343,7 @@ async function runFrames(
     head,
     pass,
     box,
+    reference,
     theme,
     bytes: bytes ?? new Uint8Array(),
   })
@@ -3215,7 +3352,7 @@ async function runFrames(
   return finish(
     {
       number: pull,
-      box,
+      ...(box === undefined ? { reference } : { box }),
       ...(theme === undefined ? {} : { theme }),
       head,
       pass,