@erclx/canon 5.66.0 → 5.68.0

package/claude/skills/ui-record/references/take-craft.md

@@ -0,0 +1,99 @@
+---
+title: Take craft
+description: The filming rules a take plan follows, the frame-stepping limits, and the pointer and zoom rules the camera relies on, each with its source
+---
+
+# Take craft
+
+Read at Step 3 of `ui-record`, before writing the first beat. `canon take --help` carries every step kind, the target forms, and each refusal code, so this file carries the judgment and leaves the vocabulary to the verb.
+
+## Contents
+
+- [The plan](#the-plan)
+- [One action per take](#one-action-per-take)
+- [Frame-stepping limits](#frame-stepping-limits)
+- [Targets](#targets)
+- [The pointer](#the-pointer)
+- [The zoom](#the-zoom)
+- [Sources](#sources)
+
+## The plan
+
+A plan holds the approved beats in order. Each beat names its setup, which runs before the first kept frame, and its steps, which are filmed.
+
+```json
+{
+  "beats": [
+    {
+      "name": "Open the kit",
+      "setup": [{ "kind": "click", "target": "text=Design" }],
+      "steps": [
+        { "kind": "click", "target": "[aria-label='Open 01-kit']" },
+        { "kind": "wait", "ms": 900 }
+      ]
+    }
+  ]
+}
+```
+
+## One action per take
+
+- Film one action per beat, such as one click, one fill, or one scroll, so the edit can cut, reorder, or drop a beat without re-filming its neighbors
+- Keep a take as long as its beat. The verb opens and closes each one on a 0.6 s hold, which gives the edit a still to cut on, so add no hold of your own around the action.
+- Add a `wait` after an action whose result animates, loads, or settles, long enough for the result to finish on screen
+- Reach the beat's start state through `setup`, since every beat opens the page fresh and nothing a setup step does is filmed
+- Write the beat's `name` as the operator approved it, since it names the clip's folder
+
+## Frame-stepping limits
+
+A step beat runs the page on a virtual clock, one frame per step. Most pages film this way, and some inputs are known to stall it.
+
+- Typing films by stepping on a canvas board, though an earlier stepper stalled on it. Keep `fill` text short, and expect a fallback to the screencast for a beat whose frames stall past 2 s.
+- A scroll has not been proven under frame stepping, and a smooth scroll can jump. Give a scroll its own beat so a fallback costs that beat alone.
+- An animated GIF can freeze, so expect one to hold its first frame
+- Set `"route": "screencast"` on a beat known to stall, rather than paying for the stall before the fallback
+
+A fallback films the beat again from a fresh load, replaying its setup and the steps the stepper already ran. A beat whose steps persist in the app, such as a fill that renames something, would then start from the changed state, so set `"route": "screencast"` on it when it risks a stall.
+
+A screencast beat films in real time at 1920x1080, which goes soft at the 1.8x zoom. Tell the operator which beats ran that way.
+
+### Reading a take back
+
+Two rules hold once a beat is filmed.
+
+- A stepped still is 3840x2160 and opens at 2000 wide. Crop it for text too small to read there, with `ffmpeg -v error -y -i <dir>/still.jpg -vf crop=<w>:<h>:<x>:<y> <dir>/crop.png` on the still's own pixels.
+- Read when something happened from `log.json` and `camera.json`, both on the clip's clock, never from a clock printed in the page, which starts before the first kept frame
+
+## Targets
+
+- Prefer a stable attribute, such as an `aria-label`, a `data-testid`, or an `id`, over a position like `:nth-child`
+- Use `text=<words>` for a control whose only stable handle is its label
+- Use a `move` to a point only for a target the page reveals on hover, and follow it with the click
+- Read each target off the served page before writing it. The verb refuses `target-missing` rather than filming a guess, and a refusal costs a reload.
+
+## The pointer
+
+- Draw no pointer in the page. The edit draws one from the log at a constant size, and two pointers on one frame leave the viewer guessing which one acted.
+- Start from a state where the app paints no cursor of its own, since a painted one films into the clip and grows with every zoom
+- Check that each click lands inside its target's box on the closing still. The verb aims at the box's center, and an element covering it takes the click instead.
+
+## The zoom
+
+The camera track already carries the zoom, so these rules decide what to film for it to aim at.
+
+- Earn a zoom with an action. The camera aims only at clicks and typing, and a wait, a move, or a scroll aims nowhere, so a result too small to read needs a click on it.
+- Expect a scroll to end a zoom, since the content moves under the camera
+- Expect a target filling most of the view to get less zoom, and one filling the page to get none
+- The push reaches 90% of its depth in about 633 ms, inside the 1 s ceiling a push onto an action keeps
+
+## Sources
+
+| Rule                       | Source                                                                                                                                                   |
+| -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Zoom on a click            | Screen Studio's [auto zoom guide](https://screen.studio/guide/auto-zoom) keys its zoom on click positions                                                |
+| The 1 s ceiling            | Material Design 3's [duration tokens](https://m3.material.io/styles/motion/easing-and-duration/tokens-specs) end at 1000 ms, the top of the ambient band |
+| The 633 ms push            | Twelve moves in a Screen Studio clip reached 90% in a median of 667 ms, measured when the camera was tuned                                               |
+| The typing and scroll risk | Takes of a canvas design board filmed while the stepper was built                                                                                        |
+| Jumping scrolls and GIFs   | [hasuwini77/demo-reel#28](https://github.com/hasuwini77/demo-reel/pull/28), read through a search summary rather than the page                           |
+
+The pointer rules carry no number. One pointer and a click inside its box follow from the log recording each target's box.

package/docs/agents/records.md

@@ -28,6 +28,7 @@ printf '.canon/\n' >> .gitignore
 ```
 
 - `push` commits every top-level folder under `.canon/` except `tmp`, `ordinal-locks`, and `.records.git`, then pushes. New folders list under `added`.
+- `push` backs up a video workspace under `video/` without its media, skipping `takes/`, `renders/`, `snapshots/`, `node_modules/`, and any `.mp4`, `.webm`, or `.mov` file.
 - `pull` restores the folders on a new machine after the setup above. It refuses rather than overwrite records the history lacks.
 - `size` reports one row per folder, heaviest first, with file count, bytes, and growth over 7 and 30 days. After a `pull` every file reads as new.
 - `prune-tmp` lists scratch untouched for 14 days and deletes it only with `--write`. It never offers `tmp/handoff/` or `tmp/pr/poll/`.
@@ -58,4 +59,5 @@ Branch on `reason` in the `--json` record, not the exit code.
 
 - `canon records ordinal <kind> <slug> --claim`: reserve the next intake or groundwork ordinal
 - `canon records validate <kind> [record] --help`: where a record disagrees with its standard, plus a `structure` report that never sets the exit
+- `canon records validate sessions [stem]`: each session map's words against its cap, under a `length` report that never sets the exit
 - `canon records stale --help`: when the requirements and design records were last reviewed

package/docs/workflow/parallel-features.md

@@ -32,7 +32,7 @@ Assert the orchestrator role in one warm session with `canon:role-orchestrator`.
 
 - To pick otherwise, rewrite that line as `overridden at execution to <pick>,` plus the measurement, and add one line to the open task's `## Findings`
 
-- `canon records validate plans [plan]` reports a plan breaking its standard, plus `structure` misses that never set the exit, and takes `groundwork` and `intake`
+- `canon records validate plans [plan]` reports a plan breaking its standard, plus `structure` misses that never set the exit, and takes `groundwork`, `intake`, and `sessions`
 - `canon records push` and `canon records pull` carry `.canon/` to and from a private repository. See [records](../agents/records.md).
 - `canon records size`, `canon records prune-tmp`, and `canon records stale canonical` report folder size, idle scratch, and releases since the requirements and design records were last read
 - `canon tasks archive` moves a shipped plan to `.canon/plans/archive/` and retargets the task's `Plan:` line

package/docs/workflow/skill-map-on-request.md

@@ -19,6 +19,7 @@ These skills serve a request rather than a moment. With the [skill map](skill-ma
 | `canon:draw-figure`     | A figure or architecture view inside a doc        |
 | `canon:ci-workflow`     | A GitHub Actions workflow file                    |
 | `canon:design-identity` | A logo mark and social card                       |
+| `canon:ui-record`       | Real footage of the app for a video               |
 
 ## Answer a question at any point
 

package/docs/workflow/skill-map.md

@@ -55,6 +55,7 @@ Groups run in the order a project meets them. Every name `canon claude skills li
 | `canon:document-health` | Documents must answer for length and staleness |
 | `canon:ux-audit`        | To read UI source for missing states           |
 | `canon:ux-measure`      | To measure paint, processor, and layout cost   |
+| `canon:app-drive`       | To drive a built app with the operator         |
 
 ## Ship it
 

package/docs/workflow/visual-design-workflow.md

@@ -43,8 +43,9 @@ Run `canon drive --help` for the step kinds and the run file shape.
 Two reviews run beside each other and finish on their own clocks.
 
 - `canon:review-pr` reads the code and the stills in the evidence comment, and posts under `## Review`.
-- `canon:review-ui` never reads the diff. It drives each checklist box in the running app through the pinned `@playwright/cli` and posts under `## UI review`.
+- `canon:review-ui` never reads the diff. It drives each checklist box in the running app through `canon browser`, which runs the pinned `@playwright/cli`, and posts under `## UI review`.
 - Every box gets one verdict, being pass, fail, needs eyes, or not driven.
+- The pass refuses rather than download a browser. Install it once per machine with `canon browser install-browser chromium`.
 
 After the boxes, `review-ui` sweeps every route they reached:
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@erclx/canon",
   "type": "module",
-  "version": "5.66.0",
+  "version": "5.68.0",
   "description": "Runs your agent's work and keeps its code good, on one setup for every repo.",
   "license": "MIT",
   "bin": {
@@ -54,7 +54,9 @@
     "axe-core": "4.14.0",
     "commander": "^13.1.0",
     "execa": "^9.5.2",
-    "playwright-core": "1.64.1"
+    "pixelmatch": "8.0.0",
+    "playwright-core": "1.64.1",
+    "pngjs": "7.0.0"
   },
   "devDependencies": {
     "@astrojs/check": "^0.9.8",
@@ -66,6 +68,7 @@
     "@testing-library/jest-dom": "^6.9.1",
     "@types/bun": "^1.2.10",
     "@types/micromatch": "^4.0.10",
+    "@types/pngjs": "6.0.5",
     "astro": "^6.1.9",
     "husky": "^9.1.7",
     "micromatch": "^4.0.8",

package/src/audits/catalog.ts

@@ -451,7 +451,11 @@ function testOrderCounts(record: unknown): Record<string, number> | undefined {
   })
 }
 
-/** The record kinds `canon records validate` takes, and the corpus each reads. */
+/**
+ * The record kinds whose findings the aggregate counts, and the corpus each
+ * reads. `sessions` is left out because it reports length alone and never a
+ * finding, so a row for it would always count zero.
+ */
 const RECORD_KINDS: readonly (readonly [string, Corpus])[] = [
   ['plans', 'per-machine'],
   ['groundwork', 'per-machine'],

package/src/browser/agent-cli.ts

@@ -0,0 +1,68 @@
+/**
+ * The pinned agent browser CLI every skill driving a page reaches through
+ * `canon browser`, so every call in a run and every run on a machine reach one
+ * version. `open` is forced onto the bundled Chromium, since the CLI's default
+ * channel is a branded Chrome most machines lack, and it refuses rather than
+ * downloading when that browser is absent, since a dispatched reviewer that
+ * installs mid-pass spends its budget on the download.
+ */
+
+export const AGENT_CLI = '@playwright/cli@0.1.22'
+
+/**
+ * The Chromium revision that CLI version requires. It moves with the pin, and
+ * it is separate from the revision `INSTALL_BROWSER` fetches for the engine.
+ */
+export const CHROMIUM_REVISION = '1247'
+
+export const INSTALL_AGENT_BROWSER = 'canon browser install-browser chromium'
+
+export type AgentCall =
+  | { readonly kind: 'run'; readonly args: readonly string[] }
+  | { readonly kind: 'refused'; readonly message: string }
+
+/**
+ * Rewrites the caller's words into the child's, reading the revision only for
+ * `open`, the one verb that launches a browser. Global flags may lead the verb,
+ * as in `-s=<name> --raw open <url>`.
+ */
+export function planAgentCall(
+  args: readonly string[],
+  hasRevision: () => boolean,
+): AgentCall {
+  const verbAt = args.findIndex((arg) => !arg.startsWith('-'))
+  if (verbAt === -1 || args[verbAt] !== 'open') return { kind: 'run', args }
+
+  if (!hasRevision()) {
+    return {
+      kind: 'refused',
+      message: `Chromium revision ${CHROMIUM_REVISION} is not installed. Run once, outside the pass: ${INSTALL_AGENT_BROWSER}`,
+    }
+  }
+
+  const namesBrowser = args.some(
+    (arg) => arg === '--browser' || arg.startsWith('--browser='),
+  )
+  if (namesBrowser) return { kind: 'run', args }
+
+  return {
+    kind: 'run',
+    args: [
+      ...args.slice(0, verbAt + 1),
+      '--browser=chromium',
+      ...args.slice(verbAt + 1),
+    ],
+  }
+}
+
+/** Where Playwright keeps downloaded browsers, by its own lookup order. */
+export function browsersRoot(
+  env: Readonly<Record<string, string | undefined>>,
+  platform: string,
+  home: string,
+): string {
+  const override = env.PLAYWRIGHT_BROWSERS_PATH
+  if (override !== undefined && override !== '') return override
+  if (platform === 'darwin') return `${home}/Library/Caches/ms-playwright`
+  return `${home}/.cache/ms-playwright`
+}

package/src/claude/cases/workflow.ts

@@ -149,6 +149,26 @@ export const WORKFLOW_CASES: readonly SkillCase[] = [
     prompt: 'Tell me the paint and layout cost of this page right now.',
     expect: 'ux-measure',
   },
+  {
+    prompt:
+      'We just tagged the release. Spin up a copy of the build and use it with me as its users would, then file whatever breaks.',
+    expect: 'app-drive',
+  },
+  {
+    prompt:
+      'Before we plan the next wave, put the built app through every goal in the requirements with me and write up what we hit.',
+    expect: 'app-drive',
+  },
+  {
+    prompt:
+      'I need real footage of the board import flow for the launch video. Film it from our app so HyperFrames can zoom in on the clicks.',
+    expect: 'ui-record',
+  },
+  {
+    prompt:
+      'Shoot the takes for the storyboard we wrote, one clip per beat of the app doing its thing.',
+    expect: 'ui-record',
+  },
   {
     prompt:
       'I am building this branch for another session. What am I on the hook for, and what is off limits?',

package/src/cli/help.ts

@@ -42,6 +42,8 @@ export const COMMAND_GROUPS: { title: string; rows: CommandRow[] }[] = [
       ['serve [dir]', 'Serve a directory on localhost, print the link'],
       ['inventory [subj]', 'Report one computed property across every route'],
       ['drive <url> <run>', 'Walk a page through interactions, measure each'],
+      ['browser [args]', 'Drive the pinned agent browser CLI'],
+      ['take <url> <plan>', 'Film a web app with a click log and camera track'],
       ['transcripts <url>', 'Fetch a YouTube transcript with frontmatter'],
     ],
   },
@@ -100,6 +102,7 @@ const EXAMPLES = [
   'canon capture assets/captures/install.html --selector .window --out assets/frames',
   'canon inventory focus --json',
   'canon drive http://localhost:4173 run.json --json',
+  'canon take http://localhost:4173 plan.json --out takes --json',
   'pbpaste | canon feedback',
   'canon transcripts https://youtu.be/VIDEO_ID',
   'canon tasks --help --all',

package/src/cli.ts

@@ -14,6 +14,8 @@ import { register as capture } from '@/commands/capture'
 import { register as serve } from '@/commands/serve'
 import { register as inventory } from '@/commands/inventory'
 import { register as driver } from '@/commands/driver'
+import { register as browser } from '@/commands/browser'
+import { register as take } from '@/commands/take'
 import { register as feedback } from '@/commands/feedback'
 import { register as transcripts } from '@/commands/transcripts'
 import { register as tasks } from '@/commands/tasks'
@@ -78,6 +80,8 @@ capture(program)
 serve(program)
 inventory(program)
 driver(program)
+browser(program)
+take(program)
 feedback(program)
 transcripts(program)
 tasks(program)

package/src/commands/browser.ts

@@ -0,0 +1,102 @@
+import { spawn } from 'node:child_process'
+import { existsSync } from 'node:fs'
+import { constants, homedir } from 'node:os'
+import type { Command } from 'commander'
+import {
+  AGENT_CLI,
+  CHROMIUM_REVISION,
+  INSTALL_AGENT_BROWSER,
+  browsersRoot,
+  planAgentCall,
+} from '@/browser/agent-cli'
+
+/**
+ * Every byte on stdout and stderr belongs to the child, which skills read
+ * snapshot paths and `--raw eval` values off, so this verb frames nothing and
+ * marks its own refusals with a prefix rather than a record.
+ */
+const FORWARDED_SIGNALS = ['SIGINT', 'SIGTERM', 'SIGHUP'] as const
+
+export function register(program: Command): void {
+  program
+    .command('browser')
+    .description('Drive the pinned agent browser CLI')
+    .argument('[args...]', 'Words passed to the browser CLI untouched')
+    .helpOption('-h, --help', 'Show this help message')
+    .allowUnknownOption()
+    .allowExcessArguments(true)
+    .passThroughOptions()
+    .addHelpText(
+      'after',
+      [
+        '',
+        `Runs ${AGENT_CLI} through bunx in the current directory, so every`,
+        'skill driving a page reaches one version. Snapshots land under',
+        '.playwright-cli/ in the folder it runs in.',
+        '',
+        'open is forced onto the bundled Chromium unless the call names a',
+        `--browser, and refuses rather than downloading when revision ${CHROMIUM_REVISION}`,
+        'is absent. Install it once, outside any pass, with:',
+        `  ${INSTALL_AGENT_BROWSER}`,
+        '',
+        "Stdout, stderr, and the exit code are the browser CLI's. A refusal of",
+        "this verb's own reads 'canon browser:' on stderr.",
+        '',
+        'Exit codes:',
+        "  n  the browser CLI's own exit code",
+        '  1  refused, with the reason on stderr',
+        '',
+        'Examples:',
+        '  canon browser --version',
+        '  canon browser -s=canon-12 open http://localhost:4321',
+        '  canon browser -s=canon-12 --raw eval "document.title"',
+        '',
+      ].join('\n'),
+    )
+    .action(async (args: string[]) => {
+      process.exitCode = await runBrowser(args)
+    })
+}
+
+async function runBrowser(args: readonly string[]): Promise<number> {
+  if (Bun.which('bunx') === null) {
+    return refuse('bunx is not on PATH, so the pinned CLI cannot run')
+  }
+
+  const root = browsersRoot(process.env, process.platform, homedir())
+  const call = planAgentCall(args, () =>
+    existsSync(`${root}/chromium-${CHROMIUM_REVISION}`),
+  )
+  if (call.kind === 'refused') return refuse(call.message)
+
+  const child = spawn('bunx', ['-y', AGENT_CLI, ...call.args], {
+    stdio: 'inherit',
+  })
+  // A killed pass must not leave a browser running behind the parent, which a
+  // shell `exec` never had between the caller and the child.
+  const forward = (signal: NodeJS.Signals) => () => child.kill(signal)
+  const handlers = FORWARDED_SIGNALS.map((signal) => {
+    const handler = forward(signal)
+    process.on(signal, handler)
+    return [signal, handler] as const
+  })
+
+  try {
+    return await new Promise<number>((resolve) => {
+      child.on('error', (error) => {
+        process.stderr.write(`canon browser: ${error.message}\n`)
+        resolve(1)
+      })
+      child.on('exit', (code, signal) => {
+        resolve(code ?? 128 + (signal ? constants.signals[signal] : 0))
+      })
+    })
+  } finally {
+    for (const [signal, handler] of handlers) process.off(signal, handler)
+  }
+}
+
+function refuse(message: string): number {
+  process.stderr.write(`canon browser: ${message}\n`)
+  return 1
+}

package/src/commands/intake.ts

@@ -10,6 +10,14 @@ import {
   readFolder,
   type Selection,
 } from '@/intake/folder'
+import {
+  type BaselineOutcome,
+  type CheckOutcome,
+  checkDrive,
+  type DriveFindings,
+  type DriveRefused,
+  recordBaseline,
+} from '@/intake/drive-check'
 import { isUnread } from '@/intake/items'
 import {
   intro,
@@ -37,6 +45,12 @@ interface ListCommandOptions {
   readonly root?: string
 }
 
+interface DriveCheckCommandOptions {
+  readonly baseline?: boolean
+  readonly json?: boolean
+  readonly root?: string
+}
+
 interface AnswerCommandOptions {
   readonly cluster?: string
   readonly json?: boolean
@@ -143,6 +157,67 @@ export function register(program: Command): void {
     .action(async (slug: string, opts: AnswerCommandOptions) => {
       process.exitCode = await runAnswer(slug, opts)
     })
+
+  intake
+    .command('drive-check')
+    .description(
+      'Check an app drive against its goals, the checkout, and its evidence',
+    )
+    .argument('<slug>', 'Intake folder name, as in app-drive-1-0')
+    .helpOption('-h, --help', 'Show this help message')
+    .option(
+      '--baseline',
+      'Record the main checkout status before the drive, rather than check',
+    )
+    .option('--json', 'Emit a machine-readable record on stdout')
+    .option('--root <path>', 'Project root, defaulting to the main worktree')
+    .addHelpText(
+      'after',
+      [
+        '',
+        'With --baseline it stores the main checkout status at',
+        '.canon/tmp/app-drive/<slug>/baseline.json, any ordinal dropped from',
+        'the slug, so it runs before the intake folder exists. Without it, it',
+        'reads drive.json in the intake folder and fails the drive on:',
+        '  unmapped         a ## Goals bullet the record carries no entry for',
+        '  unreasoned       a goal marked not-driven with no reason',
+        '  unknown          an entry naming no goal the requirements hold',
+        '  changed          a checkout path that differs from the baseline',
+        '  strayEvidence    an evidence path outside the folder evidence/',
+        '  missingEvidence  an evidence path that holds no file',
+        '  worktreeLeft     the drive worktree the record names, still on disk',
+        '',
+        'A goal matches by its text with any bold label and trailing period',
+        'dropped. A changed path is named and never reverted.',
+        '',
+        'Read `reason` off the record: `recorded` for a baseline, `clean` or',
+        '`failed` for a check, and a refusal otherwise.',
+        '',
+        'Refusals, read off `reason`:',
+        '  no-intake        the project holds no intake folder',
+        '  no-folder        no folder matches the slug',
+        '  ambiguous-slug   a bare slug matches more than one folder',
+        '  bad-input        the slug could leave the scratch folder',
+        '  no-record        the folder carries no drive.json',
+        '  bad-record       drive.json does not parse or breaks its shape',
+        '  no-requirements  the project carries no requirements record',
+        '  no-baseline      no baseline was recorded for the slug',
+        '  unreadable-tree  git cannot read the main checkout status',
+        '',
+        'Exit codes:',
+        '  0  the baseline was recorded, or the drive is clean',
+        '  1  refused, with the reason on stderr or in the JSON record',
+        '  2  the drive failed, with every finding in the record',
+        '',
+        'Examples:',
+        '  canon intake drive-check app-drive-1-0 --baseline --json',
+        '  canon intake drive-check app-drive-1-0 --json',
+        '',
+      ].join('\n'),
+    )
+    .action(async (slug: string, opts: DriveCheckCommandOptions) => {
+      process.exitCode = await runDriveCheck(slug, opts)
+    })
 }
 
 function collectSelection(value: string, previous: string[]): string[] {
@@ -262,9 +337,23 @@ async function runAnswer(
   return reportAnswer(outcome, emitJson, root)
 }
 
+async function runDriveCheck(
+  slug: string,
+  opts: DriveCheckCommandOptions,
+): Promise<number> {
+  const emitJson = opts.json ?? false
+  const root = opts.root ?? (await mainWorktreeRoot())
+
+  if (opts.baseline) {
+    return reportBaseline(await recordBaseline(root, slug), emitJson, root)
+  }
+
+  return reportDriveCheck(await checkDrive(root, slug), emitJson, root)
+}
+
 function reportRefusal(
   title: string,
-  refused: IntakeRefused,
+  refused: IntakeRefused | DriveRefused,
   emitJson: boolean,
   root: string,
 ): number {
@@ -421,3 +510,94 @@ function reportAnswer(
 
   return 0
 }
+
+function reportBaseline(
+  outcome: BaselineOutcome,
+  emitJson: boolean,
+  root: string,
+): number {
+  if (!outcome.ok) {
+    return reportRefusal('canon intake drive-check', outcome, emitJson, root)
+  }
+
+  const path = relative(root, outcome.path)
+
+  if (emitJson) {
+    process.stdout.write(
+      `${JSON.stringify({
+        ok: true,
+        root,
+        slug: outcome.slug,
+        reason: 'recorded',
+        baseline: path,
+        entries: outcome.entries,
+      })}\n`,
+    )
+    return 0
+  }
+
+  intro('canon intake drive-check')
+  logStep('Baseline')
+  logInfo(`Recorded ${outcome.entries} status line(s).`)
+  logAdd(path)
+  outro()
+
+  return 0
+}
+
+const FINDING_LABELS: Record<keyof DriveFindings, string> = {
+  unmapped: 'Goals with no entry',
+  unreasoned: 'Goals not driven, with no reason',
+  unknown: 'Entries naming no goal',
+  changed: 'Changed in the checkout',
+  strayEvidence: 'Evidence outside evidence/',
+  missingEvidence: 'Evidence holding no file',
+  worktreeLeft: 'Drive worktree still on disk',
+}
+
+function reportDriveCheck(
+  outcome: CheckOutcome,
+  emitJson: boolean,
+  root: string,
+): number {
+  if (!outcome.ok) {
+    return reportRefusal('canon intake drive-check', outcome, emitJson, root)
+  }
+
+  const code = outcome.reason === 'clean' ? 0 : 2
+
+  if (emitJson) {
+    process.stdout.write(
+      `${JSON.stringify({
+        ok: true,
+        root,
+        slug: outcome.slug,
+        reason: outcome.reason,
+        goals: outcome.goals,
+        findings: outcome.findings,
+      })}\n`,
+    )
+    return code
+  }
+
+  intro('canon intake drive-check')
+
+  if (outcome.reason === 'clean') {
+    logStep('Clean')
+    logInfo(
+      `${outcome.goals} goal(s) mapped, the checkout untouched, the evidence in place.`,
+    )
+    outro()
+    return code
+  }
+
+  for (const [key, label] of Object.entries(FINDING_LABELS)) {
+    const list = outcome.findings[key as keyof DriveFindings]
+    if (list.length === 0) continue
+    logStep(label)
+    for (const entry of list) logError(entry)
+  }
+  outro()
+
+  return code
+}