@erclx/canon 4.0.0

package/src/cli.ts

@@ -0,0 +1,200 @@
+#!/usr/bin/env bun
+
+import { Command } from 'commander'
+import { register as init } from '@/commands/init'
+import { register as sandbox } from '@/commands/sandbox'
+import { register as sync } from '@/commands/sync'
+import { register as gov } from '@/commands/gov'
+import { register as standards } from '@/commands/standards'
+import { register as snippets } from '@/commands/snippets'
+import { register as tooling } from '@/commands/tooling'
+import { register as claude } from '@/commands/claude'
+import { register as wiki } from '@/commands/wiki'
+import { register as indexes } from '@/commands/indexes'
+import { register as docs } from '@/commands/docs'
+import { register as design } from '@/commands/design'
+import { register as slides } from '@/commands/slides'
+import { register as capture } from '@/commands/capture'
+import { register as serve } from '@/commands/serve'
+import { register as demo } from '@/commands/demo'
+import { register as inventory } from '@/commands/inventory'
+import { register as feedback } from '@/commands/feedback'
+import { register as transcripts } from '@/commands/transcripts'
+import { register as tasks } from '@/commands/tasks'
+import { register as intake } from '@/commands/intake'
+import { register as teach } from '@/commands/teach'
+import { register as comments } from '@/commands/comments'
+import { register as context } from '@/commands/context'
+import { register as markdown } from '@/commands/markdown'
+import { register as migrate } from '@/commands/migrate'
+import { register as records } from '@/commands/records'
+import { register as sessions } from '@/commands/sessions'
+import { register as worktrees } from '@/commands/worktrees'
+import { register as audits } from '@/commands/audits'
+import { register as gate } from '@/commands/gate'
+import { register as secrets } from '@/commands/secrets'
+import { register as deps } from '@/commands/deps'
+import { register as labels } from '@/commands/labels'
+import { register as autoship } from '@/commands/autoship'
+import { register as pr } from '@/commands/pr'
+import { register as census } from '@/commands/census'
+import { register as targets } from '@/commands/targets'
+import { register as upgrade } from '@/commands/upgrade'
+import { readInstalled, UNKNOWN_LABEL } from '@/version/installed'
+import { palette } from '@/ui'
+
+function showHelp(): void {
+  // The help text is the one framed surface written to stdout, so it asks
+  // about that stream rather than the stderr every other writer here uses.
+  const { GREY, NC, WHITE } = palette(process.stdout)
+  const lines = [
+    `${GREY}┌${NC}`,
+    `${GREY}├${NC} ${WHITE}Usage:${NC} canon [command]`,
+    `${GREY}│${NC}`,
+    `${GREY}│${NC}  ${WHITE}Commands:${NC}`,
+    `${GREY}│${NC}    init [path]        ${GREY}# Bootstrap a project with toolkit domains${NC}`,
+    `${GREY}│${NC}    sync [path]        ${GREY}# Sync all installed domains in a project${NC}`,
+    `${GREY}│${NC}    sandbox [cat:cmd]  ${GREY}# Provision and run sandbox scenarios${NC}`,
+    `${GREY}│${NC}    gov [command]      ${GREY}# Governance commands (install, sync)${NC}`,
+    `${GREY}│${NC}    standards [cmd]    ${GREY}# Standards commands (install, sync, list, <name>)${NC}`,
+    `${GREY}│${NC}    snippets [cmd]     ${GREY}# Snippets commands (create, list)${NC}`,
+    `${GREY}│${NC}    tooling [cmd]      ${GREY}# Manage tooling stacks (sync, ref, create)${NC}`,
+    `${GREY}│${NC}    claude [cmd]       ${GREY}# Claude workflow (init, sync, setup)${NC}`,
+    `${GREY}│${NC}    wiki [cmd]         ${GREY}# Wiki commands (init)${NC}`,
+    `${GREY}│${NC}    indexes [cmd]      ${GREY}# Regenerate index.md files (regen)${NC}`,
+    `${GREY}│${NC}    docs [cmd|topic]   ${GREY}# Emit toolkit reference docs (list, <topic>)${NC}`,
+    `${GREY}│${NC}    design [cmd]       ${GREY}# Design system commands (render)${NC}`,
+    `${GREY}│${NC}    slides [cmd]       ${GREY}# Slide deck commands (render, list)${NC}`,
+    `${GREY}│${NC}    capture [source]   ${GREY}# Render HTML capture sources to PNG${NC}`,
+    `${GREY}│${NC}    serve [dir]        ${GREY}# Serve a directory over localhost and print the preview link${NC}`,
+    `${GREY}│${NC}    demo [cmd]         ${GREY}# Record a running app (compile, run)${NC}`,
+    `${GREY}│${NC}    inventory [subj]   ${GREY}# Report one computed property across every route${NC}`,
+    `${GREY}│${NC}    feedback           ${GREY}# Write toolkit feedback from stdin to .claude/review/feedback/${NC}`,
+    `${GREY}│${NC}    transcripts <url>  ${GREY}# Fetch a YouTube transcript with metadata frontmatter${NC}`,
+    `${GREY}│${NC}    tasks [cmd]        ${GREY}# Task board commands (archive)${NC}`,
+    `${GREY}│${NC}    intake [cmd]       ${GREY}# Intake folders under .claude/intake/ (list, answer)${NC}`,
+    `${GREY}│${NC}    teach [cmd]        ${GREY}# Learning workspaces under .claude/teach/ (list, open, resource, glossary)${NC}`,
+    `${GREY}│${NC}    comments [cmd]     ${GREY}# Measure comment density and trend (scan)${NC}`,
+    `${GREY}│${NC}    context [cmd]      ${GREY}# Report context folder health (audit)${NC}`,
+    `${GREY}│${NC}    markdown [cmd]     ${GREY}# Report markdown against the attribute standards (audit)${NC}`,
+    `${GREY}│${NC}    records [cmd]      ${GREY}# Session records under .claude/ (validate, size, push, pull)${NC}`,
+    `${GREY}│${NC}    sessions [cmd]     ${GREY}# Resolve live sessions to worktree and branch (list)${NC}`,
+    `${GREY}│${NC}    targets [cmd]      ${GREY}# Report the projects this toolkit installed into (list, pulls)${NC}`,
+    `${GREY}│${NC}    worktrees [cmd]    ${GREY}# Report which worktrees are reclaimable (list)${NC}`,
+    `${GREY}│${NC}    secrets [cmd]      ${GREY}# Read the shipped tree for credential-shaped values (scan)${NC}`,
+    `${GREY}│${NC}    deps [cmd]         ${GREY}# Read the resolved dependency set for advisories (audit)${NC}`,
+    `${GREY}│${NC}    labels [cmd]       ${GREY}# Read a changed set against the pull request label map (audit)${NC}`,
+    `${GREY}│${NC}    autoship [cmd]     ${GREY}# Decide whether a changed set needs the review pass (classify)${NC}`,
+    `${GREY}│${NC}    pr [cmd]           ${GREY}# Read a pull request body against its own diff (key-changes)${NC}`,
+    `${GREY}│${NC}    census [path]      ${GREY}# Report tracked file count, extension breakdown, and line totals${NC}`,
+    `${GREY}│${NC}    audits [cmd]       ${GREY}# Run every health check as one set (run, list)${NC}`,
+    `${GREY}│${NC}    gate [cmd]         ${GREY}# Run the merge gate stage by stage (run)${NC}`,
+    `${GREY}│${NC}    upgrade            ${GREY}# Reinstall the CLI globally with the manager that installed it${NC}`,
+    `${GREY}│${NC}`,
+    `${GREY}│${NC}  ${WHITE}Sandbox:${NC}`,
+    `${GREY}│${NC}    canon sandbox             ${GREY}# Interactive scenario picker${NC}`,
+    `${GREY}│${NC}    canon sandbox git:commit  ${GREY}# Run specific scenario${NC}`,
+    `${GREY}│${NC}    canon sandbox reset       ${GREY}# Reset sandbox to baseline${NC}`,
+    `${GREY}│${NC}    canon sandbox clean       ${GREY}# Wipe the sandbox${NC}`,
+    `${GREY}│${NC}`,
+    `${GREY}│${NC}  ${WHITE}Examples:${NC}`,
+    `${GREY}│${NC}    canon sync ../my-app`,
+    `${GREY}│${NC}    canon sandbox git:commit`,
+    `${GREY}│${NC}    canon gov install react`,
+    `${GREY}│${NC}    canon gov sync ../my-app`,
+    `${GREY}│${NC}    canon gov restated --json`,
+    `${GREY}│${NC}    canon standards markdown`,
+    `${GREY}│${NC}    canon snippets list`,
+    `${GREY}│${NC}    canon init ../my-app`,
+    `${GREY}│${NC}    canon tooling sync base`,
+    `${GREY}│${NC}    canon tooling create`,
+    `${GREY}│${NC}    canon claude init`,
+    `${GREY}│${NC}    canon indexes regen`,
+    `${GREY}│${NC}    canon indexes regen --dry-run --json`,
+    `${GREY}│${NC}    canon docs list --json`,
+    `${GREY}│${NC}    canon docs agents`,
+    `${GREY}│${NC}    canon design render`,
+    `${GREY}│${NC}    canon slides render`,
+    `${GREY}│${NC}    canon slides list --json`,
+    `${GREY}│${NC}    canon capture assets/install.html`,
+    `${GREY}│${NC}    canon serve .claude/teach`,
+    `${GREY}│${NC}    canon inventory focus --json`,
+    `${GREY}│${NC}    pbpaste | canon feedback`,
+    `${GREY}│${NC}    canon transcripts https://youtu.be/VIDEO_ID`,
+    `${GREY}│${NC}    canon tasks archive --pull-request 673 --json`,
+    `${GREY}│${NC}    canon intake list toolkit-overview --unread --json`,
+    `${GREY}│${NC}    canon teach list --json`,
+    `${GREY}│${NC}    canon comments scan src --json`,
+    `${GREY}│${NC}    canon context audit --json`,
+    `${GREY}│${NC}    canon markdown audit .claude/rules --json`,
+    `${GREY}│${NC}    canon records validate plans`,
+    `${GREY}│${NC}    canon records size --json`,
+    `${GREY}│${NC}    canon records push --json`,
+    `${GREY}│${NC}    canon sessions list --json`,
+    `${GREY}│${NC}    canon worktrees list --json`,
+    `${GREY}│${NC}    canon secrets scan --json`,
+    `${GREY}│${NC}    canon deps audit --json`,
+    `${GREY}│${NC}    canon labels audit --json`,
+    `${GREY}│${NC}    canon census --json`,
+    `${GREY}│${NC}    canon audits run --json`,
+    `${GREY}│${NC}    canon gate run --all --no-write`,
+    `${GREY}│${NC}    canon upgrade --json`,
+    `${GREY}└${NC}`,
+  ]
+  console.log(lines.join('\n'))
+}
+
+const program = new Command()
+program
+  .name('canon')
+  .version(readInstalled().version ?? UNKNOWN_LABEL)
+  .enablePositionalOptions()
+  .helpOption(false)
+program.action(() => showHelp())
+program.on('option:help', () => {
+  showHelp()
+  process.exit(0)
+})
+program.option('-h, --help', 'Show help')
+
+init(program)
+sandbox(program)
+sync(program)
+gov(program)
+standards(program)
+snippets(program)
+tooling(program)
+claude(program)
+wiki(program)
+indexes(program)
+docs(program)
+design(program)
+slides(program)
+capture(program)
+serve(program)
+demo(program)
+inventory(program)
+feedback(program)
+transcripts(program)
+tasks(program)
+intake(program)
+teach(program)
+comments(program)
+context(program)
+markdown(program)
+records(program)
+migrate(program)
+sessions(program)
+targets(program)
+worktrees(program)
+secrets(program)
+deps(program)
+labels(program)
+autoship(program)
+pr(program)
+census(program)
+audits(program)
+gate(program)
+upgrade(program)
+
+program.parse()

package/src/commands/audits.ts

@@ -0,0 +1,350 @@
+import { execa } from 'execa'
+import type { Command } from 'commander'
+import {
+  BASELINE_REL,
+  type Baseline,
+  baselineFrom,
+  compareBaseline,
+  type Delta,
+  readBaseline,
+  writeBaseline,
+} from '@/audits/baseline'
+import { AUDITS, type AuditResult } from '@/audits/catalog'
+import {
+  exitCodeFor,
+  runAudits,
+  spawnAudit,
+  type Summary,
+  summarize,
+} from '@/audits/run'
+import { gitEnv } from '@/git-env'
+import { intro, logError, logInfo, logStep, logWarn, outro, plural } from '@/ui'
+import { currentWorktreeRoot } from '@/worktree'
+
+interface RunCommandOptions {
+  readonly json?: boolean
+  readonly record?: boolean
+  readonly root?: string
+}
+
+interface ListCommandOptions {
+  readonly json?: boolean
+}
+
+export function register(program: Command): void {
+  const audits = program
+    .command('audits')
+    .description('Run every health check this repository owns as one set')
+    .helpOption('-h, --help', 'Show this help message')
+
+  audits
+    .command('run')
+    .description(
+      'Run every audit, report per check under one verdict, and compare each count to the recorded baseline',
+    )
+    .helpOption('-h, --help', 'Show this help message')
+    .option('--json', 'Add a machine-readable record on stdout')
+    .option(
+      '--root <path>',
+      'Tree to measure, defaulting to the current worktree',
+    )
+    .option(
+      '--record',
+      `Write this run's tracked counts to ${BASELINE_REL} as the new baseline`,
+    )
+    .addHelpText(
+      'after',
+      [
+        '',
+        'Exit codes:',
+        '  0  every audit reported and none carried a finding that is a fact',
+        '  1  refused, with the reason on stderr',
+        '  2  an audit carries a finding that is a fact',
+        '  3  an audit did not report, so the run measured less than the set',
+        '',
+        'It gates on exactly what already gates a push and on nothing new:',
+        'an unresolved context citation, a banned character, word, or spelling,',
+        'and a skill folder carrying no REQUIREMENT.md. Every other measure is a',
+        'judgment a reader settles, and failing a push on one teaches',
+        'contributors to route around the stage.',
+        '',
+        'Exit 3 is a defect in the run rather than in the tree. An aggregate that',
+        'reports a pass over a set it did not finish measuring is the failure this',
+        'command exists against, so a verb that did not report takes its own code.',
+        '',
+        `The baseline at ${BASELINE_REL} holds the counts from the last recorded`,
+        'run, so a measure that reports rather than gates still costs something',
+        'when it grows. Only a tracked corpus is retained: a gitignored record',
+        "folder holds one machine's scratch, and its counts answer nobody else.",
+        '',
+        'Examples:',
+        '  canon audits run',
+        '  canon audits run --json',
+        '  canon audits run --record',
+        '',
+      ].join('\n'),
+    )
+    .action(async (opts: RunCommandOptions) => {
+      process.exitCode = await runAll(opts)
+    })
+
+  audits
+    .command('list')
+    .description(
+      'List every audit this command runs and what each one gates on',
+    )
+    .helpOption('-h, --help', 'Show this help message')
+    .option('--json', 'Emit JSON with the id, invocation, corpus, and gate')
+    .addHelpText(
+      'after',
+      [
+        '',
+        'Exit codes:',
+        '  0  the catalog was listed',
+        '',
+        'Examples:',
+        '  canon audits list',
+        '  canon audits list --json',
+        '',
+      ].join('\n'),
+    )
+    .action((opts: ListCommandOptions) => {
+      process.exitCode = runList(opts)
+    })
+}
+
+function runList(opts: ListCommandOptions): number {
+  if (opts.json) {
+    process.stdout.write(
+      `${JSON.stringify({
+        audits: AUDITS.map((audit) => ({
+          id: audit.id,
+          label: audit.label,
+          command: `canon ${audit.argv.join(' ')}`,
+          corpus: audit.corpus,
+          gates: audit.gatingExits.length > 0,
+        })),
+      })}\n`,
+    )
+    return 0
+  }
+
+  intro('canon audits list')
+  for (const audit of AUDITS) {
+    logStep(audit.label)
+    logInfo(`canon ${audit.argv.join(' ')}`)
+    logInfo(
+      `${audit.corpus} corpus, ${audit.gatingExits.length > 0 ? 'gates on a fact' : 'reports only'}`,
+    )
+  }
+  outro()
+  return 0
+}
+
+/**
+ * The day a record is stamped with, as `YYYY-MM-DD`.
+ *
+ * Local rather than UTC, because the stamp is read beside a commit date in a
+ * context entry and a run taken in the evening should not record tomorrow.
+ */
+function today(): string {
+  const now = new Date()
+  return [
+    now.getFullYear(),
+    String(now.getMonth() + 1).padStart(2, '0'),
+    String(now.getDate()).padStart(2, '0'),
+  ].join('-')
+}
+
+/**
+ * The commit the counts were read at, or `unknown` outside a repository.
+ *
+ * A target project can install this CLI without a git history behind it, and
+ * refusing there would withhold the whole report over a field that only makes
+ * the record reproducible.
+ */
+async function headCommit(root: string): Promise<string> {
+  const result = await execa('git', ['-C', root, 'rev-parse', 'HEAD'], {
+    reject: false,
+    env: gitEnv(),
+    extendEnv: false,
+  })
+  return result.exitCode === 0 ? result.stdout.trim() : 'unknown'
+}
+
+async function runAll(opts: RunCommandOptions): Promise<number> {
+  const emitJson = opts.json ?? false
+  const root = opts.root ?? (await currentWorktreeRoot())
+
+  let baseline: Baseline | undefined
+  try {
+    baseline = await readBaseline(root)
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error)
+    if (emitJson) {
+      process.stderr.write(`${message}\n`)
+      process.stdout.write(
+        `${JSON.stringify({ ok: false, reason: 'bad-baseline', message })}\n`,
+      )
+      return 1
+    }
+    intro('canon audits run')
+    logStep('Refused')
+    logError(message)
+    outro()
+    return 1
+  }
+
+  const results = await runAudits(AUDITS, spawnAudit(root))
+  const deltas = compareBaseline(baseline, results)
+  const summary = summarize(results, deltas)
+
+  let recorded: string | undefined
+  if (opts.record) {
+    const next = baselineFrom(results, {
+      recordedAt: today(),
+      commit: await headCommit(root),
+    })
+    recorded = await writeBaseline(root, next)
+  }
+
+  if (emitJson) {
+    process.stdout.write(
+      `${JSON.stringify({
+        ok: true,
+        root,
+        // Flat scalars, so a shell stage greps one out without a JSON parser.
+        // The nested arrays below carry the detail behind each number.
+        summary,
+        baseline: baseline
+          ? { recordedAt: baseline.recordedAt, commit: baseline.commit }
+          : undefined,
+        recorded,
+        audits: results,
+        deltas,
+      })}\n`,
+    )
+  } else {
+    report(results, deltas, baseline, recorded, summary)
+  }
+
+  return exitCodeFor(results)
+}
+
+/** The counts of one result, rendered as `key n` pairs a reader can scan. */
+function countLine(counts: Record<string, number>): string {
+  return Object.entries(counts)
+    .map(([key, value]) => `${key} ${value}`)
+    .join(', ')
+}
+
+/**
+ * The delta line for one audit, or nothing when there is no comparison to
+ * report. A first run says so rather than showing a delta of zero, since zero
+ * against an absent baseline says the same as a corpus that did not move.
+ */
+function deltaLine(delta: Delta): string | undefined {
+  if (
+    delta.kind === 'per-machine' ||
+    delta.kind === 'upstream' ||
+    delta.kind === 'unmeasured'
+  ) {
+    return undefined
+  }
+  if (delta.kind === 'unrecorded') return 'No recorded baseline to compare'
+
+  const parts = [
+    ...delta.moved.map(
+      ({ key, from, to, delta: moved }) =>
+        `${key} ${from} to ${to} (${moved > 0 ? '+' : ''}${moved})`,
+    ),
+    ...delta.added.map(({ key, to }) => `${key} ${to}, newly measured`),
+    ...delta.dropped.map(({ key, from }) => `${key} was ${from}, not measured`),
+  ]
+
+  return parts.length === 0 ? undefined : parts.join(', ')
+}
+
+function report(
+  results: readonly AuditResult[],
+  deltas: readonly Delta[],
+  baseline: Baseline | undefined,
+  recorded: string | undefined,
+  summary: Summary,
+): void {
+  const byId = new Map(deltas.map((delta) => [delta.id, delta]))
+
+  intro('canon audits run')
+
+  logStep('Baseline')
+  if (baseline === undefined) {
+    logWarn(`None recorded. Take one with canon audits run --record.`)
+  } else {
+    logInfo(`${baseline.recordedAt} at ${baseline.commit.slice(0, 8)}`)
+  }
+
+  for (const result of results) {
+    logStep(result.label)
+
+    if (result.status === 'absent') {
+      logInfo(`No corpus on this machine: ${result.reason ?? 'not found'}`)
+      continue
+    }
+
+    if (result.status === 'unmeasured') {
+      logWarn(`Did not report: ${result.reason ?? 'no reason given'}`)
+      continue
+    }
+
+    const counts = result.counts ?? {}
+    const line = countLine(counts)
+    if (result.status === 'finding') {
+      logError(line === '' ? 'A finding that is a fact' : line)
+    } else {
+      logInfo(line === '' ? 'Reported' : line)
+    }
+
+    if (!result.tracked) {
+      logInfo(
+        result.corpus === 'upstream'
+          ? 'Upstream index, so no baseline is kept and growth is not this tree'
+          : 'Per-machine corpus, so no baseline is kept',
+      )
+      continue
+    }
+
+    const moved = deltaLine(
+      byId.get(result.id) ?? { id: result.id, kind: 'unrecorded' },
+    )
+    if (moved !== undefined) logInfo(moved)
+  }
+
+  if (recorded !== undefined) {
+    logStep('Recorded')
+    logInfo(recorded)
+  }
+
+  logStep('Verdict')
+
+  if (summary.verdict === 'findings') {
+    logError(
+      `${plural(summary.facts, 'audit')} carrying a finding that is a fact. Fix what each names.`,
+    )
+  } else if (summary.verdict === 'incomplete') {
+    logError(
+      `${plural(summary.unmeasured, 'audit')} did not report, so this run measured less than the set.`,
+    )
+  } else if (summary.verdict === 'reported') {
+    logInfo('No fact. Every other finding is a judgment a reader settles.')
+  } else {
+    logInfo('Every audit reported and every count is zero.')
+  }
+
+  // Stated on every run, including a clean one. A count of what passed reads as
+  // a verdict on the whole set unless the run also says what it never reached.
+  logInfo(
+    `${summary.audited} of ${results.length} corpora measured, ${summary.absent} absent or unreachable from this machine`,
+  )
+
+  outro()
+}

package/src/commands/autoship.ts

@@ -0,0 +1,129 @@
+import type { Command } from 'commander'
+import {
+  type ClassifyRefusal,
+  type FailedTest,
+  classifyChanges,
+} from '@/autoship/classify'
+import { intro, logInfo, logStep, logWarn, outro, plural } from '@/ui'
+
+interface ClassifyOptions {
+  readonly json?: boolean
+}
+
+/** What a reader does about the one way the classification produced no reading. */
+const REFUSALS: Record<ClassifyRefusal, string> = {
+  'no-changes':
+    'No changed files were supplied, so there is no set to classify. Pass the set the ship chain already computed.',
+}
+
+/** Why each failed test sends the branch to review, in the reader's terms. */
+const TESTS: Record<FailedTest, string> = {
+  extension: 'is not prose, so this branch carries a change review reads',
+  'behavior-path':
+    'sits under a behavior path, so its prose states what an agent does',
+}
+
+export function register(program: Command): void {
+  const autoship = program
+    .command('autoship')
+    .description('Answer the decisions the ship chain used to make in prose')
+    .helpOption('-h, --help', 'Show this help message')
+
+  autoship
+    .command('classify')
+    .description('Decide whether a changed set needs the review pass')
+    .argument('[paths...]', 'Changed set to classify, as names')
+    .helpOption('-h, --help', 'Show this help message')
+    .option('--json', 'Add a machine-readable record on stdout')
+    .addHelpText(
+      'after',
+      [
+        '',
+        'Reads names only and never touches git, so the caller hands over the',
+        'set it already computed rather than paying for a second baseline that',
+        'can disagree with the first.',
+        '',
+        'The skip needs both tests to pass. Every name reads as prose, and no',
+        'name sits under a behavior path, which is where markdown states what',
+        'an agent does. One behavior file sends the whole branch to review,',
+        'since documentation shipped beside a behavior change does not cancel',
+        'it.',
+        '',
+        'An empty set refuses rather than skipping. Both tests are universally',
+        'quantified, so an empty set satisfies them vacuously, and reading that',
+        'as prose-only would route a branch past review for producing no output.',
+        '',
+        'Exit codes:',
+        '  0  prose-only, so the review pass can be skipped',
+        '  1  refused, with the reason on stderr or in the JSON record',
+        '  2  review is needed, with the file and the test it failed named',
+        '',
+        'Examples:',
+        '  canon autoship classify docs/index.md README.md',
+        '  canon autoship classify --json .claude/skills/deploy-check/SKILL.md',
+        '',
+      ].join('\n'),
+    )
+    .action((paths: string[], opts: ClassifyOptions) => {
+      process.exitCode = runClassify(paths, opts)
+    })
+}
+
+function runClassify(paths: string[], opts: ClassifyOptions): number {
+  const emitJson = opts.json ?? false
+  const result = classifyChanges(paths)
+
+  intro('canon autoship classify')
+
+  // The frame renders on stderr in both modes and the record goes to stdout
+  // alone, so an operator reading the terminal sees the refusal rather than a
+  // command that appeared to do nothing.
+  if (result.kind === 'refused') {
+    logStep('Refused')
+    logWarn(REFUSALS[result.reason])
+    outro()
+
+    if (emitJson) {
+      process.stdout.write(
+        `${JSON.stringify({
+          decision: 'refused',
+          reason: result.reason,
+          message: REFUSALS[result.reason],
+        })}\n`,
+      )
+    }
+    return 1
+  }
+
+  logStep('Scope')
+  logInfo(`${plural(paths.length, 'path')} supplied by the caller`)
+
+  if (result.kind === 'skip') {
+    logStep('Prose only')
+    logInfo('every path reads as prose and none states agent behavior')
+    outro()
+
+    if (emitJson) {
+      process.stdout.write(
+        `${JSON.stringify({ decision: 'skip', changed: paths })}\n`,
+      )
+    }
+    return 0
+  }
+
+  logStep('Review')
+  logWarn(`${result.file} ${TESTS[result.test]}.`)
+  outro()
+
+  if (emitJson) {
+    process.stdout.write(
+      `${JSON.stringify({
+        decision: 'review',
+        test: result.test,
+        file: result.file,
+        changed: paths,
+      })}\n`,
+    )
+  }
+  return 2
+}