@erclx/canon 5.77.0 → 5.79.0

package/src/commands/pr.ts

@@ -43,6 +43,8 @@ import {
   isEvidencePath,
   PNG_HEADER_BYTES,
   readChecklistBoxes,
+  countDrivable,
+  type ChecklistBox,
   readOwed,
   readPngWidth,
   readUncaptured,
@@ -51,6 +53,7 @@ import {
   settleChecklist,
 } from '@/pr/evidence'
 import { isWithinTolerance } from '@/pr/pixels'
+import { REEL_MAX_BYTES } from '@/take/reel'
 import {
   dropFramesWithLegacy,
   FRAMES_BRANCH,
@@ -64,7 +67,6 @@ import {
   LEGACY_FRAMES_BRANCH,
   pruneFramesWithLegacy,
   pushFrame,
-  REEL_MAX_BYTES,
   readFrame,
   readReel,
   isDesignReference,
@@ -83,6 +85,7 @@ import {
   type PullState,
   readBaseStanding,
   readChangedPaths,
+  readsDrivableBox,
 } from '@/pr/lift'
 import { close, type CloseApi, type CloseRefusal } from '@/pr/close'
 import {
@@ -110,6 +113,7 @@ import {
   type LocalRefusal,
   type LocalRunner,
 } from '@/pr/local'
+import { linkKeyChanges } from '@/pr/links'
 import { KEY_CHANGES } from '@/pr/paths'
 import {
   findDeployWorkflow,
@@ -158,6 +162,7 @@ const GH_TIMEOUT_MS = 30_000
 const UNNAMED_PRINT_LIMIT = 10
 
 interface KeyChangesOptions {
+  readonly link?: boolean
   readonly body?: string
   readonly base?: string
   readonly root?: string
@@ -171,7 +176,8 @@ interface ReadOptions {
 
 interface EvidenceOptions extends ReadOptions {
   readonly preview?: string
-  readonly checklist?: string
+  /** A path to fold in, or false from `--no-checklist` to drop the carried one. */
+  readonly checklist?: string | false
   readonly local?: string
   readonly reel?: string
   readonly localSkip?: string
@@ -255,7 +261,7 @@ const TICK_REFUSALS: Record<TickReason | 'gh-failed', string> = {
   'no-box':
     'A named box is past the end of the checklist. Number boxes off `canon pr evidence --json`.',
   'taste-box':
-    'A named box ends in (taste), which no driver passes. Nothing was written.',
+    'A named box carries (taste) among its trailing markers, which no driver passes. Nothing was written.',
   'gh-failed':
     'gh could not read or edit the marked comment on this pull request.',
 }
@@ -275,7 +281,7 @@ const LOCAL_REFUSALS: Record<
     'Nothing listening inside this worktree served an HTML page. Start the dev server here and re-run to get a link.',
   unhealthy:
     'A page answered inside this worktree, but a health path it declares failed. Start what the page reaches and re-run to get a link.',
-  'invalid-config': `${LOCAL_CONFIG_REL} cannot be read, so no health path was checked and no link is given. Fix or delete it and re-run.`,
+  'invalid-config': `${LOCAL_CONFIG_REL} cannot be read, so no health path was checked and no link is given. Fix or delete it and re-run. health takes paths starting with /, and page-only takes folders relative to the repository.`,
   'no-listener-reader':
     'This machine offers neither lsof nor /proc, so no listening socket could be read. Nothing is posted.',
   'gh-failed':
@@ -438,7 +444,7 @@ type EvidenceRefusal =
 
 const EVIDENCE_REFUSALS: Record<EvidenceRefusal, string> = {
   'check-writes':
-    '--check is a read and renders no body, so it takes none of --preview, --local, --checklist, --reel, --local-skip, or --reel-skip. Run the check and the render as two calls.',
+    '--check is a read and renders no body, so it takes none of --preview, --local, --checklist, --no-checklist, --reel, --local-skip, or --reel-skip. Run the check and the render as two calls.',
   'gh-failed':
     'gh could not answer for this repository. Name the pull request number.',
   'unreadable-checklist':
@@ -499,13 +505,17 @@ export function register(program: Command): void {
     .helpOption('-h, --help', 'Show this help message')
     .option(
       '--body <path>',
-      'Read the body from a file rather than the API, ignoring any number',
+      'Read the body from a file rather than the API, ignoring any number except the one --link needs',
     )
     .option(
       '--base <ref>',
       'Far side of the range when --body supplies the body',
     )
     .option('--root <path>', 'Repository to read, defaulting to the cwd')
+    .option(
+      '--link',
+      `Print the body with each ## ${KEY_CHANGES} path linked to its diff, needing a number`,
+    )
     .option('--json', 'Add a machine-readable record on stdout')
     .addHelpText(
       'after',
@@ -534,6 +544,13 @@ export function register(program: Command): void {
         'points the change at a locative the path does not name. Read the bullet on',
         "the record's preview before filing an unmet path as a stale claim.",
         '',
+        '--link prints the body and nothing else, with every path the section',
+        'names that the diff changes written as a link to its row in the Files',
+        'tab. The anchor is `diff-` and the SHA-256 of the path. Pass the pull',
+        'request number, since the link needs it. It also rewrites the anchor',
+        'of a link opening another file, and a plain run reports that link as',
+        "mislinked when its label is a changed path and its anchor hashes another's.",
+        '',
         'Refusals, read off `reason`:',
         '  no-section          the body carries no `## Key changes` heading, so it',
         '                      claims nothing',
@@ -551,14 +568,18 @@ export function register(program: Command): void {
         '  gh-missing          `gh` is not on the path, so no pull request could be',
         '                      resolved',
         '  gh-failed           `gh` could not answer for this repository or branch',
+        '  no-number           --link was given with no pull request number',
+        '  no-repo-url         --link could not read the repository address',
+        '  link-json           --link was given with --json, though it prints the body',
         '',
         'Exit codes:',
-        '  0  every claimed path is in the diff',
+        '  0  every claimed path is in the diff, and every link opens its own file',
         '  1  refused, with the reason on stderr or in the JSON record',
-        '  2  at least one claimed path is absent from the diff',
+        '  2  a claimed path is absent from the diff, or a link opens another file',
         '',
         'Examples:',
         '  canon pr key-changes',
+        '  canon pr key-changes 1265 --link --body .canon/tmp/body.md',
         '  canon pr key-changes 1265 --json',
         '  canon pr key-changes --body .canon/tmp/body.md --base origin/main',
         '',
@@ -709,9 +730,11 @@ export function register(program: Command): void {
         '',
         '`ui` also carries the newest `## UI review` pass (`heading`, `state`,',
         '`commit`, `source`), `isBound`, which is whether the evidence comment',
-        'carries a checklist, and `carriedFrom` when the lift carried a close',
-        'forward, or `drivenPaths` and the painted subset `paintedPaths` when it',
-        'refused to. An unbound family reads covered.',
+        'carries a checklist holding a box a driver can run or the newest UI',
+        'pass is open, so a checklist of taste boxes alone binds nothing until',
+        'a pass opens, and `carriedFrom` when the lift carried a close',
+        'forward, or `drivenPaths` and the painted subset `paintedPaths` when',
+        'it 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',
@@ -772,6 +795,10 @@ export function register(program: Command): void {
       '--checklist <path>',
       'Close the body with this visual checklist file, from canon:ui-checklist',
     )
+    .option(
+      '--no-checklist',
+      'Drop the checklist the marked comment carries, rendering the body without it',
+    )
     .option(
       '--local <url>',
       "Add this worktree's running server to the address line, from canon pr local",
@@ -809,8 +836,9 @@ export function register(program: Command): void {
         'Read `reason` on the JSON record before posting anything:',
         '  ok           a body was rendered, with `commentId` set when a marked',
         '               comment already exists and should be edited in place',
-        '  no-evidence  nothing in the diff carries an evidence/ segment, which',
-        '               is an ordinary, silent no-op rather than a refusal',
+        '  no-evidence  nothing in the diff carries an evidence/ segment and no',
+        '               painted path is uncaptured, which is an ordinary,',
+        '               silent no-op rather than a refusal',
         '  would-empty  the render holds no cases and the marked comment holds',
         '               some, so no body is printed and a person edits the comment',
         '',
@@ -853,6 +881,12 @@ export function register(program: Command): void {
         'branch with a checklist and no evidence image renders a marked body',
         'holding the checklist, so a later call finds and edits that comment.',
         '',
+        '--no-checklist drops the checklist the marked comment carries, so the',
+        'body renders without it and the record reports no checklist fields.',
+        'A marked comment holding a checklist still renders as ok rather than',
+        'no-evidence, so the comment is edited rather than left showing it.',
+        'Of --checklist and --no-checklist, the last one passed wins.',
+        '',
         '--local adds a **Local preview:** segment after any hosted one on the',
         'address line, or carries the line alone, and is carried forward the',
         'same way. It does not by itself turn no-evidence into ok, so a',
@@ -891,9 +925,13 @@ export function register(program: Command): void {
         '  checklist  the checklist between its delimiters, ticks included',
         '  boxes      each checklist box with its number, tick, stamp, and taste',
         '             mark, the numbering `canon pr tick` takes',
+        '  drivable   how many boxes a driver can run, every box but one whose',
+        '             trailing markers hold (taste), in any order. Zero binds no',
+        '             UI review, so `canon pr lift` and `review-state` leave the',
+        '             UI family unbound',
         'These come from the comment already posted, never from the flags this',
         'call passed. A checklist the caller posted raw after a refused render',
-        'carries no marker, so the record reports none of the three for it. An',
+        'carries no marker, so the record reports none of these for it. An',
         'unread thread refuses as gh-failed on both reasons rather than',
         'reporting the fields absent.',
         '',
@@ -907,6 +945,14 @@ export function register(program: Command): void {
         'unchecked rather than clean. It never adds to `owed`, since no step of',
         'the ship chain can take a capture.',
         '',
+        'A rendered body carries the list as an **Uncaptured:** line under the',
+        'addresses, each path in a code span. A non-empty list opens a comment',
+        'the way a checklist does, so a head whose only news is an uncaptured',
+        'path reports ok rather than no-evidence. The line is computed on every',
+        'render and never carried, so it drops once a capture empties the list',
+        'or a reel filmed at the head renders beside it. `canon pr lift`',
+        'refuses `painted-uncaptured` on the same list.',
+        '',
         '--check reads the same changed set and thread, renders no body, and',
         'reports what the ship chain still owes the pull request:',
         '  settled  nothing is owed',
@@ -917,8 +963,8 @@ export function register(program: Command): void {
         'request changed, and the marked comment carries no **Preview:**',
         'address. A failed deploy reads the same as a skipped one.',
         'The record carries `owed` and the same marked fields. --check refuses',
-        'with --preview, --local, --checklist, --reel, --local-skip, or',
-        '--reel-skip as check-writes.',
+        'with --preview, --local, --checklist, --no-checklist, --reel,',
+        '--local-skip, or --reel-skip as check-writes.',
         '',
         'Refusals, read off `reason`:',
         '  unreadable-checklist  --checklist named a path that could not be read,',
@@ -973,7 +1019,9 @@ export function register(program: Command): void {
         'they are read:',
         '  review    the newest `## Review` is closed at the head, off its marker',
         '  ui        the newest `## UI review` is closed at the head, bound only',
-        '            where `canon pr evidence --check` carries a checklist. A close',
+        '            where `canon pr evidence --check` carries a checklist whose',
+        '            `drivable` count is not zero, a missing count binding. An',
+        '            open UI review refuses `ui-open` whatever the count. A close',
         '            on an earlier commit still holds when it is an ancestor of the',
         '            head and every path changed since is one no box can observe,',
         '            being tests, stories, snapshots, markdown in the root and in',
@@ -984,7 +1032,19 @@ export function register(program: Command): void {
         '            a box drives behavior a `.ts` file holds too. A close whose',
         '            count line shows boxes not driven and none passed, failed,',
         '            or needing eyes refuses `ui-undriven`, carried or not',
-        '  evidence  the evidence check reads settled',
+        '  evidence  the evidence check reads settled, and every painted path',
+        '            it lists as `uncaptured` is covered. A reel the marked',
+        '            comment embeds at the head covers every path, and a',
+        '            `- **Waived capture:** `<path>`: <reason>` line outside a code',
+        '            fence covers the path it names as the list spells it. Only',
+        '            the newest `## Review` and the newest `## UI review` count,',
+        '            each closed by its own marker and not dismissed, so a pass',
+        '            must restate a waiver for it to hold on a later head. A',
+        '            review with no pass heading waives nothing. Any other path',
+        '            refuses `painted-uncaptured`,',
+        '            the gate entry naming what is left as `uncaptured` and what',
+        '            a review waived as `waived`, each sorted. An absent list,',
+        '            in a project whose base keeps no captures, passes',
         '  standing  the head is fresh against the base, not stale or conflicted',
         '  ci        every required check run on the tip passed, waited on up to --wait',
         '',
@@ -1014,7 +1074,8 @@ export function register(program: Command): void {
         '  lifted, already-ready, redrafted, clear (--check)',
         '  pull-closed, review-missing, review-open, review-unmarked,',
         '  review-behind, ui-missing, ui-open, ui-unmarked, ui-behind,',
-        '  ui-undriven, evidence-owed, standing-stale, standing-conflict, standing-unknown,',
+        '  ui-undriven, evidence-owed, painted-uncaptured, standing-stale,',
+        '  standing-conflict, standing-unknown,',
         '  ci-pending (--check), ci-failing, ci-conflicted, ci-timeout,',
         '  head-moved, gh-failed',
         '',
@@ -1257,6 +1318,15 @@ export function register(program: Command): void {
         "refusal names the lowest page port's first failing path. An absent",
         'file or an empty list checks the page alone.',
         '',
+        'A page served by a static server answers none of those paths, so',
+        'page-only = ["web"] lists repository-relative folders whose',
+        'listeners skip them and are found on the page probe alone. The match',
+        "reads the listener's working directory on whole path segments, so web",
+        'does not cover webapp, and a server started from the root with a',
+        'working-directory flag still takes the health check. Keep health',
+        'beside page-only until the binary a project runs carries this key,',
+        'since an older one refuses a file holding page-only alone.',
+        '',
         'A process in a sibling worktree, in the main checkout seen from a',
         'linked worktree, or in a linked worktree seen from the main checkout',
         'is never reported, since its server shows another branch. Sockets are',
@@ -1282,8 +1352,9 @@ export function register(program: Command): void {
         '  unhealthy           a page answered but a declared health path did',
         '                      not, with `port`, `path`, and `status`, which',
         '                      is null on a timeout',
-        '  invalid-config      canon/config/local.toml is not valid TOML, or',
-        '                      health is not a list of paths starting with /',
+        '  invalid-config      canon/config/local.toml is not valid TOML,',
+        '                      health is not a list of paths starting with /,',
+        '                      or page-only is not a list of relative folders',
         '  removed             --remove dropped the line',
         '  no-comment          --remove found no marked comment, a no-op',
         '  no-line             --remove found no address line, a no-op',
@@ -1367,7 +1438,7 @@ export function register(program: Command): void {
         '               nothing written, with `driven`, `head`, and `drivenPaths`',
         '  stale-head   --head is behind the tip with no readable linear gap,',
         '               as a force-push or a rebase leaves, nothing written',
-        '  taste-box    a named box ends in (taste), nothing written',
+        '  taste-box    a named box carries (taste), nothing written',
         '  no-box       a named number is past the checklist, nothing written',
         '  no-checklist the evidence comment carries no checklist',
         '  no-comment   no comment carries the evidence marker',
@@ -1821,6 +1892,8 @@ async function runKeyChanges(
   const root = resolve(opts.root ?? process.cwd())
   const emitJson = opts.json ?? false
 
+  if (opts.link === true) return runKeyChangesLink(number, opts, root)
+
   intro('canon pr key-changes')
 
   const source =
@@ -1905,6 +1978,14 @@ async function runKeyChanges(
     for (const claim of report.unresolved) logInfo(claim.path)
   }
 
+  if (report.mislinked.length > 0) {
+    logStep('Mislinked')
+    logWarn(
+      `${plural(report.mislinked.length, 'link')} open another file's diff than the path they name. Re-run with --link to print the body with them corrected.`,
+    )
+    for (const link of report.mislinked) logWarn(link.path)
+  }
+
   outro()
 
   if (emitJson) {
@@ -1922,11 +2003,71 @@ async function runKeyChanges(
         incidental: report.incidental,
         unresolved: report.unresolved,
         evidenceUnread: report.evidenceUnread,
+        mislinked: report.mislinked,
       })}\n`,
     )
   }
 
-  return report.unmet.length === 0 ? 0 : 2
+  return report.unmet.length === 0 && report.mislinked.length === 0 ? 0 : 2
+}
+
+/**
+ * Prints the body with each changed path in `## Key changes` linked to its
+ * diff, and nothing else, so stdout pipes straight into a body file.
+ *
+ * Skips the frame `intro` opens, which would land in the piped body. Refusals
+ * keep the framed shape on stdout like every other mode.
+ */
+async function runKeyChangesLink(
+  number: string | undefined,
+  opts: KeyChangesOptions,
+  root: string,
+): Promise<number> {
+  const emitJson = opts.json ?? false
+
+  if (emitJson) {
+    return refuseWith(
+      'link-json',
+      '--link prints the body itself, so it takes no --json record.',
+      emitJson,
+      root,
+    )
+  }
+
+  const source =
+    opts.body === undefined
+      ? await readFromApi(root, number)
+      : await readFromFile(root, process.cwd(), opts.body, opts.base)
+  if (source.kind === 'refused') return refuse(source.reason, emitJson, root)
+
+  const pull = number ?? source.source.number?.toString()
+  if (pull === undefined) {
+    return refuseWith(
+      'no-number',
+      'The link needs the pull request number, so pass it as the argument.',
+      emitJson,
+      root,
+    )
+  }
+
+  const url = await readRepoUrl(root)
+  if (url === undefined) {
+    return refuseWith(
+      'no-repo-url',
+      'gh could not read the repository address, so no link was built.',
+      emitJson,
+      root,
+    )
+  }
+
+  process.stdout.write(
+    linkKeyChanges(
+      source.source.body,
+      source.source.changed,
+      `${url}/pull/${pull}/files`,
+    ),
+  )
+  return 0
 }
 
 type IdentityRead =
@@ -2065,7 +2206,7 @@ async function listReviews(cwd: string, number: string) {
   return listPages<RestReview>(
     cwd,
     `repos/{owner}/{repo}/pulls/${number}/reviews`,
-    'id, body, commit_id, submitted_at',
+    'id, body, commit_id, submitted_at, state',
   )
 }
 
@@ -2439,7 +2580,9 @@ function logReviewState(number: number, record: ReviewStateRecord): void {
     else logWarn(line)
   }
   if (!record.ui.isBound) {
-    logInfo('ui: the evidence carries no checklist, so the family is unbound')
+    logInfo(
+      'ui: the evidence carries no box a driver can run, so the family is unbound',
+    )
   }
 }
 
@@ -2448,14 +2591,18 @@ interface PullFiles {
   readonly present: ReadonlyMap<string, boolean>
   /** Each path the pull request removed, which a deploy's push filter still counts. */
   readonly removed: readonly string[]
+  /** Each renamed path mapped to the path it sat at before the pull request. */
+  readonly renamedFrom: ReadonlyMap<string, string>
 }
 
 /**
  * The paths a pull request changed, read through the paginated files endpoint
  * so the set is the same from any checkout and never capped at the first
- * view. `renamed` and `copied` count as added, since the new path has no
- * counterpart at the merge base. Returns undefined when the read fails, which
- * refuses rather than rendering a short set.
+ * view. `copied` counts as added, since a copy leaves its source in place and
+ * has no single base. `renamed` counts as added in `present` too, so the
+ * changed set stays the same, and `renamedFrom` carries the old path of each
+ * rename for a reader that compares against the base. Returns undefined when
+ * the read fails, which refuses rather than rendering a short set.
  */
 async function listPullFiles(
   cwd: string,
@@ -2466,18 +2613,22 @@ async function listPullFiles(
     '--paginate',
     `repos/{owner}/{repo}/pulls/${number}/files`,
     '--jq',
-    '.[] | [.status, .filename] | @tsv',
+    '.[] | [.status, .filename, (.previous_filename // "")] | @tsv',
   ])
   if (stdout === null) return undefined
   const present = new Map<string, boolean>()
   const removed: string[] = []
+  const renamedFrom = new Map<string, string>()
   for (const line of stdout.split('\n').filter(Boolean)) {
-    const [status, path] = line.split('\t')
+    const [status, path, previous] = line.split('\t')
     if (status === undefined || path === undefined) continue
     if (status === 'removed') removed.push(path)
     else present.set(path, status !== 'modified' && status !== 'changed')
+    if (status === 'renamed' && previous !== undefined && previous !== '') {
+      renamedFrom.set(path, previous)
+    }
   }
-  return { present, removed }
+  return { present, removed, renamedFrom }
 }
 
 function everyChangedPath(files: PullFiles): string[] {
@@ -2625,13 +2776,14 @@ async function measureItem(
   head: string,
 ): Promise<MeasuredItem> {
   const headRead = await readImage(cwd, item.path, head)
+  const basePath = item.basePath ?? item.path
   const baseRead =
     item.added || base === undefined
       ? undefined
-      : await readImage(cwd, item.path, base)
+      : await readImage(cwd, basePath, base)
   const unread = [
     ...(headRead.kind === 'failed' ? [`head:${item.path}`] : []),
-    ...(baseRead?.kind === 'failed' ? [`base:${item.path}`] : []),
+    ...(baseRead?.kind === 'failed' ? [`base:${basePath}`] : []),
   ]
   const headBytes = headRead.kind === 'read' ? headRead.bytes : undefined
   const baseBytes = baseRead?.kind === 'read' ? baseRead.bytes : undefined
@@ -2645,6 +2797,9 @@ async function measureItem(
       ...(headBytes !== undefined &&
         baseBytes !== undefined && {
           withinTolerance: isWithinTolerance(baseBytes, headBytes),
+          ...(item.basePath !== undefined && {
+            identical: Buffer.from(baseBytes).equals(headBytes),
+          }),
         }),
     },
     unread,
@@ -2708,7 +2863,7 @@ async function runEvidence(
   // Read ahead of anything else, so a bad path refuses before a `gh` round
   // trip rather than after one.
   let suppliedChecklist: string | undefined
-  if (opts.checklist !== undefined) {
+  if (typeof opts.checklist === 'string') {
     suppliedChecklist = await readFile(resolve(root, opts.checklist), 'utf8')
       .then((text) => text.trim() || undefined)
       .catch(() => undefined)
@@ -2765,6 +2920,7 @@ async function runEvidence(
   const grouped = await groupEvidence(
     [...pullFiles.present.keys()],
     async (path) => pullFiles.present.get(path) === false,
+    pullFiles.renamedFrom,
   )
   const uncaptured = readUncaptured(
     everyChangedPath(pullFiles),
@@ -2794,7 +2950,10 @@ async function runEvidence(
   commentId = findEvidenceCommentId(comments)
   existingCases = findEvidenceCaseCount(comments)
   carriedPreview = findEvidencePreview(comments)
-  carriedChecklist = findEvidenceChecklist(comments)
+  // A dropped checklist is not carried, so neither the record nor the render
+  // shows it, while the marked comment holding it still counts below.
+  const postedChecklist = findEvidenceChecklist(comments)
+  carriedChecklist = opts.checklist === false ? undefined : postedChecklist
   carriedLocal = findEvidenceLocal(comments)
   const carriedReel = findEvidenceReel(comments)
 
@@ -2804,10 +2963,7 @@ async function runEvidence(
     ...(carriedPreview !== undefined && { preview: carriedPreview }),
     ...(carriedLocal !== undefined && { local: carriedLocal }),
     ...(carriedReel !== undefined && { reel: carriedReel }),
-    ...(carriedChecklist !== undefined && {
-      checklist: carriedChecklist,
-      boxes: readChecklistBoxes(carriedChecklist),
-    }),
+    ...(carriedChecklist !== undefined && checklistFields(carriedChecklist)),
   }
 
   // A deploy that resolves and does not build from any changed path makes a
@@ -2866,13 +3022,18 @@ async function runEvidence(
   // A checklist opens a comment on its own, so it always lands in the marked
   // comment a later call edits. A local address rides on a checklist or a
   // hosted preview and never opens one alone, so a docs-only branch with a
-  // server up posts nothing.
+  // server up posts nothing. An uncaptured painted path opens one too, so the
+  // gap the lift refuses on shows on the thread.
+  // A dropped checklist still opens a render, so the marked comment holding
+  // it is edited without the block rather than left showing it.
   const hasChecklist =
-    suppliedChecklist !== undefined || carriedChecklist !== undefined
+    suppliedChecklist !== undefined || postedChecklist !== undefined
+  const hasUncaptured = uncaptured !== undefined && uncaptured.length > 0
   if (
     grouped.kind === 'refused' &&
     opts.preview === undefined &&
-    !hasChecklist
+    !hasChecklist &&
+    !hasUncaptured
   ) {
     logStep('Skipped')
     logInfo(
@@ -2933,6 +3094,7 @@ async function runEvidence(
     local,
     reel,
     skips,
+    uncaptured,
   )
 
   const caseCount = states.reduce((n, s) => n + s.items.length, 0)
@@ -3030,6 +3192,16 @@ async function runEvidence(
   return 0
 }
 
+/** The record fields a checklist carries, with `drivable` counting the boxes a driver can run. */
+function checklistFields(checklist: string): {
+  checklist: string
+  boxes: ChecklistBox[]
+  drivable: number
+} {
+  const boxes = readChecklistBoxes(checklist)
+  return { checklist, boxes, drivable: countDrivable(boxes) }
+}
+
 async function readWorkflows(root: string): Promise<WorkflowFile[]> {
   const dir = join(root, '.github', 'workflows')
   if (!existsSync(dir)) return []
@@ -3350,6 +3522,7 @@ async function runLocal(opts: LocalOptions): Promise<number> {
     worktree,
     machineLocalRunner(),
     declaration.kind === 'paths' ? declaration.paths : [],
+    declaration.pageOnly,
   )
   if (result.kind === 'refused' && result.reason === 'unhealthy') {
     const { port, path, status } = result
@@ -3966,6 +4139,18 @@ async function readRepoName(root: string): Promise<string | undefined> {
   }
 }
 
+/** The repository's web address off the REST repository read, for the same reason as `readRepoName`. */
+async function readRepoUrl(root: string): Promise<string | undefined> {
+  const row = await gh(root, ['api', 'repos/{owner}/{repo}'])
+  if (row === null) return undefined
+  try {
+    const url = (JSON.parse(row) as { html_url?: unknown }).html_url
+    return typeof url === 'string' && url !== '' ? url : undefined
+  } catch {
+    return undefined
+  }
+}
+
 async function runFrames(
   number: string | undefined,
   opts: FramesOptions,
@@ -4122,7 +4307,7 @@ const LIFT_REFUSALS: Record<LiftRefusal | 'bad-wait' | 'gh-missing', string> = {
   'review-behind':
     'The newest code review closed on an earlier commit than the head.',
   'ui-missing':
-    'The evidence comment carries a checklist and no UI review has been posted.',
+    'The evidence comment carries a checklist holding a box a driver can run, and no UI review has been posted.',
   'ui-open': 'The newest UI review is open, so a box still owes a fix.',
   'ui-unmarked':
     'The newest UI review carries no head marker, so the commit it covers is a GitHub stamp this gate does not trust.',
@@ -4132,6 +4317,8 @@ const LIFT_REFUSALS: Record<LiftRefusal | 'bad-wait' | 'gh-missing', string> = {
     'The newest UI review closed having driven no box, so it looked at nothing. Re-drive the checklist on an address that answers.',
   'evidence-owed':
     'The evidence check reads owed, so the ship chain left a step undone.',
+  'painted-uncaptured':
+    'A painted path changed with no capture, no reel at the head, and no waiver in a review. Capture it, or have a review waive it.',
   'standing-stale':
     'The base moved under a path this branch writes since it branched, so CI measured a tree that is gone.',
   'standing-conflict': 'The head does not merge cleanly into the base.',
@@ -4235,7 +4422,14 @@ async function readEvidenceGate(
     .at(-1)
   if (last === undefined) return undefined
 
-  let record: { reason?: unknown; owed?: unknown; checklist?: unknown }
+  let record: {
+    reason?: unknown
+    owed?: unknown
+    checklist?: unknown
+    drivable?: unknown
+    uncaptured?: unknown
+    reel?: unknown
+  }
   try {
     record = JSON.parse(last)
   } catch {
@@ -4243,12 +4437,27 @@ async function readEvidenceGate(
   }
   if (record.reason !== 'settled' && record.reason !== 'owed') return undefined
 
+  const reelHead = readReelHead(record.reel)
   return {
     isSettled: record.reason === 'settled',
     owed: Array.isArray(record.owed) ? record.owed.map(String) : [],
-    hasChecklist:
-      typeof record.checklist === 'string' && record.checklist !== '',
+    hasDrivableBox: readsDrivableBox(record),
+    // Absent stays absent, since it means the base keeps no captures and
+    // the gate passes as it did before the list existed.
+    ...(Array.isArray(record.uncaptured) && {
+      uncaptured: record.uncaptured.map(String),
+    }),
+    ...(reelHead !== undefined && { reelHead }),
+  }
+}
+
+function readReelHead(reel: unknown): string | undefined {
+  if (typeof reel !== 'object' || reel === null || !('head' in reel)) {
+    return undefined
   }
+  return typeof reel.head === 'string' && reel.head !== ''
+    ? reel.head
+    : undefined
 }
 
 async function readChecksGate(