@erclx/canon 5.8.0 → 5.10.0

package/scripts/core/regen-hero.ts

@@ -0,0 +1,119 @@
+/**
+ * Fills every assets/captures/*.html.tmpl from the catalogs and the design
+ * source, writing the .html beside each one.
+ *
+ * The name says hero because the hero was the only template when it was written
+ * and every citation of it across docs/, canon/context/, and src/ spells that
+ * name. The loop below covers whatever templates the folder holds.
+ *
+ * Each catalog is read through the module its `canon` verb calls, so no child
+ * process runs and no stderr is discarded. The palette arrives from
+ * `buildDesignCss` without the component half, which is a scrollbar and a
+ * status marker a static capture frame renders neither of. The value builder
+ * and every guard live in `src/capture/frame-values.ts`, where tsc and vitest
+ * reach them.
+ *
+ * `--check` fills every template into a temp folder and discards it, so a
+ * renamed featured skill, an empty catalog, or an unresolved placeholder still
+ * fails a branch while no frame file changes. Frames are refreshed after a
+ * merge rather than committed by each branch.
+ *
+ * Only the HTML regenerates here. The PNG beside it is a chromium render whose
+ * bytes move with the browser version. Rebuild the images with
+ * `canon capture assets/captures --selector .window --out assets/evidence`
+ * after this script reports a change. That capture writes a .stamp beside each
+ * PNG, which records the digest of the markup it rendered and is what the Hero
+ * stage compares, so a frame's three files commit together. The frame carries
+ * no version, since `package.json` is bumped on main by the release tooling and
+ * embedding it would drift every open branch on the next release.
+ *
+ * Clone-only. This script reads the repository's own catalogs and
+ * `assets/captures`, which a registry install does not carry.
+ */
+import {
+  mkdirSync,
+  mkdtempSync,
+  readdirSync,
+  readFileSync,
+  rmSync,
+  writeFileSync,
+} from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+
+import {
+  buildFrameValues,
+  FrameError,
+  fillTemplate,
+} from '../../src/capture/frame-values'
+import { listSkills } from '../../src/claude/skills-list'
+import { countCommands } from '../../src/counts/catalogs'
+import { buildDesignCss } from '../../src/design/css'
+import { buildGovCatalog } from '../../src/gov/list'
+import { listStandardEntries } from '../../src/standards/list'
+import { buildStackSummaries } from '../../src/tooling/list'
+
+const root = new URL('../..', import.meta.url).pathname
+const assetDir = join(root, 'assets', 'captures')
+
+const [flag, ...extra] = process.argv.slice(2)
+if (flag !== undefined && flag !== '--check') {
+  console.error(`regen-hero: unknown argument ${flag}`)
+  process.exit(1)
+}
+if (extra.length > 0) {
+  console.error(`regen-hero: unknown argument ${extra[0]}`)
+  process.exit(1)
+}
+
+const outDir =
+  flag === '--check' ? mkdtempSync(join(tmpdir(), 'regen-hero-')) : assetDir
+
+function run(): void {
+  const templates = readdirSync(assetDir)
+    .filter((name) => name.endsWith('.html.tmpl'))
+    .sort()
+  if (templates.length === 0) {
+    throw new FrameError(`no templates under ${assetDir}`)
+  }
+
+  const tokenCss = buildDesignCss(undefined, { components: false })
+  if (!tokenCss.trim()) {
+    throw new FrameError(
+      'the design source emitted nothing, refusing to write an unstyled frame',
+    )
+  }
+
+  const { values, frames } = buildFrameValues({
+    skills: listSkills(root).map((entry) => entry.name),
+    gov: buildGovCatalog(root),
+    // The toolkit root only: a project-local standard would put a row in the
+    // hero the toolkit does not ship.
+    standards: listStandardEntries(root).filter((entry) =>
+      entry.source.startsWith('standards/'),
+    ),
+    toolingStacks: buildStackSummaries(root),
+    commandCount: countCommands(root) ?? 0,
+    tokenCss,
+    markSvg: readFileSync(join(root, 'assets', 'brand', 'mark.svg'), 'utf8'),
+  })
+
+  mkdirSync(outDir, { recursive: true })
+  for (const { template, out, tokens } of frames(templates)) {
+    const source = readFileSync(join(assetDir, template), 'utf8')
+    writeFileSync(
+      join(outDir, out),
+      fillTemplate(template, source, values, tokens),
+    )
+  }
+}
+
+try {
+  run()
+} catch (error) {
+  if (!(error instanceof FrameError)) throw error
+  console.error(`regen-hero: ${error.message}`)
+  process.exitCode = 1
+} finally {
+  if (outDir !== assetDir) rmSync(outDir, { recursive: true, force: true })
+}

package/scripts/core/regen-web-favicon.ts

@@ -3,7 +3,7 @@
  * own colors in src/design/favicon.ts, apart from the page accent tokens.
  *
  * The page is the fourth surface to carry the mark as a favicon and the only
- * one that can answer for itself. `regen-hero.sh` and `src/design/render.ts`
+ * one that can answer for itself. `regen-hero.ts` and `src/design/render.ts`
  * each bake a single literal, because both embed the mark as a data URI and a
  * data URI has no CSS context. A file served at its own URL does have one, so
  * this copy carries a `prefers-color-scheme` branch and tracks the reader's

package/src/capture/frame-values.ts

@@ -0,0 +1,359 @@
+import type { GovCatalog } from '@/gov/list'
+import type { StackSummary } from '@/tooling/list'
+
+export const LISTED = 10
+
+/**
+ * The first seven are the method and exist nowhere else. The last three are
+ * recognizable on sight and are what keeps a column of chosen names from
+ * reading as an all-`claude-` catalog, which is the failure the sampler was
+ * written against.
+ */
+export const FEATURED_SKILLS = [
+  'plan-feature',
+  'plan-groundwork',
+  'plan-intake',
+  'role-orchestrator',
+  'auto-ship',
+  'review-pr',
+  'task-board',
+  'git-ship',
+  'target-setup',
+  'systematic-debugging',
+]
+
+/**
+ * A terminal frame sets `white-space: pre` at a fixed window width, so an
+ * overlong cell is clipped by the window edge rather than wrapped.
+ */
+const GLOB_WIDTH = 44
+
+/** A refusal the script prints as `regen-hero: <message>` and exits 1 on. */
+export class FrameError extends Error {}
+
+export interface StandardRow {
+  readonly name: string
+  readonly appliesTo?: readonly string[]
+}
+
+export interface FrameCatalogs {
+  readonly skills: readonly string[]
+  readonly gov: GovCatalog
+  readonly standards: readonly StandardRow[]
+  readonly toolingStacks: readonly StackSummary[]
+  readonly commandCount: number
+  readonly tokenCss: string
+  readonly markSvg: string
+}
+
+export interface Frame {
+  readonly template: string
+  readonly out: string
+  readonly tokens: string
+}
+
+export interface FrameValues {
+  readonly values: Readonly<Record<string, string>>
+  readonly frames: (templates: readonly string[]) => Frame[]
+}
+
+const escape = (value: string): string =>
+  value.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;')
+
+/**
+ * Even spacing across the sorted catalog rather than its first N, so a column
+ * whose names share a prefix does not read as a narrower catalog than the one
+ * that ships. Rules and standards sample. Skills do not, because the even step
+ * lands on the entries closest to commodity and on none of the workflow the
+ * toolkit exists to carry.
+ */
+export function sample<T>(items: readonly T[], listed = LISTED): T[] {
+  if (items.length <= listed) return [...items]
+  const step = items.length / listed
+  return Array.from({ length: listed }, (_, i) => items[Math.floor(i * step)])
+}
+
+/**
+ * A chosen name is maintained by hand where a sample never goes stale, so a
+ * rename has to fail the run rather than quietly shrink the column. The length
+ * is asserted because the `+N more` figure counts down from `LISTED` rather
+ * than from what this returns.
+ */
+export function featured(
+  names: readonly string[],
+  chosen: readonly string[],
+  listed = LISTED,
+): string[] {
+  if (chosen.length !== listed) {
+    throw new FrameError(`${chosen.length} featured skills, expected ${listed}`)
+  }
+  const catalog = new Set(names)
+  const missing = chosen.filter((name) => !catalog.has(name))
+  if (missing.length > 0) {
+    throw new FrameError(
+      `featured skills missing from the catalog: ${missing.join(', ')}`,
+    )
+  }
+  return [...chosen]
+}
+
+/**
+ * Truncating keeps the longest row inside the capture, and the ellipsis stops a
+ * clipped value from reading as the whole value.
+ */
+export function clip(value: string, width: number): string {
+  return value.length <= width ? value : `${value.slice(0, width - 1)}…`
+}
+
+/**
+ * Padding happens before escaping, since an entity is longer than the
+ * character it replaces and would push a column out of line.
+ */
+export function pad(value: string, width: number): string {
+  return value + ' '.repeat(Math.max(0, width - value.length))
+}
+
+const markup = (names: readonly string[]): string =>
+  names
+    .map((name) => `            <div class="entry">${escape(name)}</div>`)
+    .join('\n')
+
+const remaining = (names: readonly unknown[], listed = LISTED): string =>
+  String(Math.max(0, names.length - listed))
+
+const plural = (count: number, noun: string): string =>
+  `${count} ${noun}${count === 1 ? '' : 's'}`
+
+const frameRow = (cells: string): string =>
+  `<span class="frame">│</span> <span class="ok">✓</span> ${cells}`
+
+/** Rule names carry a numeric prefix that orders the load, not the identity. */
+const slug = (name: string): string => name.replace(/^\d+-/, '')
+
+/** Indented to the depth a rule inside the `<style>` block sits at. */
+const indentTokens = (css: string): string =>
+  css
+    .trimEnd()
+    .split('\n')
+    .map((line) => (line === '' ? '' : `      ${line}`))
+    .join('\n')
+
+/**
+ * The frames a README serves in both themes. The hero is a landing-page frame
+ * no README shows, so it stays dark.
+ */
+const LIGHT_TEMPLATES = new Set(['install.html.tmpl'])
+
+function lightTokens(tokenCss: string): string {
+  const roles = [...tokenCss.matchAll(/--color-light-([a-z-]+):/g)].map(
+    (match) => match[1],
+  )
+  if (roles.length === 0) {
+    throw new FrameError(
+      'token css carries no --color-light-* roles, refusing to write a light frame',
+    )
+  }
+  return [
+    tokenCss,
+    '',
+    '      :root {',
+    ...roles.map(
+      (role) => `        --color-${role}: var(--color-light-${role});`,
+    ),
+    '        --frame-shadow: rgb(0 0 0 / 16%);',
+    '      }',
+  ].join('\n')
+}
+
+function faviconUri(markSvg: string, tokenCss: string): string {
+  const accent = tokenCss.match(/--color-accent:\s*(#[0-9a-fA-F]{3,8})/)
+  if (!accent) {
+    throw new FrameError(
+      'token css carries no --color-accent value, refusing to write a colorless favicon',
+    )
+  }
+  const svg = markSvg
+    .replace(/<!--[\s\S]*?-->/, '')
+    .trim()
+    .replaceAll('currentColor', accent[1])
+  return `data:image/svg+xml,${encodeURIComponent(svg)}`
+}
+
+/**
+ * Builds the value map every template takes and the frame list a template set
+ * expands to. An empty array is well-formed, and the in-process readers return
+ * one quietly for a missing tree, so every catalog is refused when empty
+ * rather than shipping a frame claiming the domain has nothing in it.
+ */
+export function buildFrameValues(catalogs: FrameCatalogs): FrameValues {
+  const { gov, toolingStacks, standards, skills } = catalogs
+  const markSvg = catalogs.markSvg.trim()
+  if (!markSvg) {
+    throw new FrameError(
+      'assets/brand/mark.svg read empty, refusing to write a hero with no mark',
+    )
+  }
+  if (!catalogs.commandCount) {
+    throw new FrameError(
+      'the commands catalog read no commands, refusing to write a zeroed hero',
+    )
+  }
+
+  const tokenCss = indentTokens(catalogs.tokenCss)
+  const rules = gov.rules.map((entry) => slug(entry.name))
+  // A rule no stack names is opt-in behind `--add`, so featuring one advertises
+  // an entry no ordinary `canon gov install` delivers. The column samples the
+  // stack-reached subset while its count and remainder describe the whole.
+  const stacked = new Set(gov.stacks.flatMap((stack) => stack.rules))
+  const deliveredEntries = gov.rules.filter((entry) => stacked.has(entry.name))
+  const deliveredRules = deliveredEntries.map((entry) => slug(entry.name))
+  const standardNames = standards.map((entry) => entry.name)
+
+  for (const [label, list] of [
+    ['skills', skills],
+    ['rules', rules],
+    ['standards', standardNames],
+    ['tooling stacks', toolingStacks],
+    ['gov stacks', gov.stacks],
+    ['stack-delivered rules', deliveredRules],
+  ] as const) {
+    if (list.length === 0) {
+      throw new FrameError(
+        `the ${label} catalog is empty, refusing to write a zeroed hero`,
+      )
+    }
+  }
+
+  const govStackRows = gov.stacks
+    .map((stack) =>
+      frameRow(
+        `<span class="name">${escape(pad(stack.name, 17))}</span>` +
+          `<span class="muted">${escape(pad(plural(stack.rules.length, 'rule'), 11))}</span>` +
+          `<span class="muted">${escape(stack.extends ? `extends ${stack.extends}` : '')}</span>`,
+      ),
+    )
+    .join('\n')
+
+  // Each rule sits beside the glob that loads it rather than its description,
+  // since the glob is the mechanism a reader cannot otherwise see. A rule
+  // carrying no glob is not unscoped, it loads every session, and saying so is
+  // the contrast that makes the column mean anything.
+  const govRuleRows = sample(deliveredEntries)
+    .map((entry) => {
+      const globs = entry.paths ?? []
+      const scope =
+        globs.length > 0 ? clip(globs.join(' '), GLOB_WIDTH) : 'every session'
+      return frameRow(
+        `<span class="name">${escape(pad(slug(entry.name), 24))}</span>` +
+          `<span class="domain">${escape(pad(`[${entry.domain}]`, 12))}</span>` +
+          `<span class="muted">${escape(scope)}</span>`,
+      )
+    })
+    .join('\n')
+
+  // A standard either governs an artifact by path or is opened by name when a
+  // session decides it needs it. Naming the second is the contrast, since
+  // nothing else tells a reader the corpus installs into no project.
+  const standardRows = sample(standards)
+    .map((entry) => {
+      const applies = entry.appliesTo ?? []
+      const governs =
+        applies.length > 0
+          ? clip(applies.join(' '), GLOB_WIDTH)
+          : 'read by name'
+      return frameRow(
+        `<span class="name">${escape(pad(entry.name, 18))}</span>` +
+          `<span class="muted">${escape(governs)}</span>`,
+      )
+    })
+    .join('\n')
+
+  // A tooling stack is counted rather than listed, because what it lays down is
+  // dev dependencies, run scripts, and ignore groups rather than named entries.
+  // The inheritance is the part worth showing, since it is why a stack carrying
+  // two of its own arrives with far more than two.
+  const toolingStackRows = toolingStacks
+    .map((stack) =>
+      frameRow(
+        `<span class="name">${escape(pad(stack.name, 14))}</span>` +
+          `<span class="muted">${escape(pad(plural(stack.devDeps, 'dep'), 10))}</span>` +
+          `<span class="muted">${escape(pad(plural(stack.scripts, 'script'), 12))}</span>` +
+          `<span class="muted">${escape(stack.extends ? `extends ${stack.extends}` : '')}</span>`,
+      ),
+    )
+    .join('\n')
+
+  for (const [label, rows] of [
+    ['governance stack rows', govStackRows],
+    ['governance rule rows', govRuleRows],
+    ['standard rows', standardRows],
+    ['tooling stack rows', toolingStackRows],
+  ] as const) {
+    if (rows === '') {
+      throw new FrameError(
+        `the ${label} rendered empty, refusing to write a blank frame`,
+      )
+    }
+  }
+
+  const values: Record<string, string> = {
+    TOKENS: tokenCss,
+    GOV_STACK_ROWS: govStackRows,
+    GOV_RULE_ROWS: govRuleRows,
+    STANDARD_ROWS: standardRows,
+    TOOLING_STACK_ROWS: toolingStackRows,
+    SKILL_COUNT: String(skills.length),
+    RULE_COUNT: String(rules.length),
+    STANDARD_COUNT: String(standardNames.length),
+    GOV_STACK_COUNT: String(gov.stacks.length),
+    TOOLING_STACK_COUNT: String(toolingStacks.length),
+    COMMAND_COUNT: String(catalogs.commandCount),
+    MARK_SVG: markSvg,
+    FAVICON: faviconUri(markSvg, tokenCss),
+    SKILL_ENTRIES: markup(featured(skills, FEATURED_SKILLS)),
+    RULE_ENTRIES: markup(sample(deliveredRules)),
+    STANDARD_ENTRIES: markup(sample(standardNames)),
+    SKILL_MORE: remaining(skills),
+    RULE_MORE: remaining(rules),
+    STANDARD_MORE: remaining(standardNames),
+  }
+
+  const light = lightTokens(tokenCss)
+
+  return {
+    values,
+    frames: (templates) =>
+      templates.flatMap((template) => {
+        const base = template.replace(/\.html\.tmpl$/, '')
+        const dark = { template, out: `${base}.html`, tokens: tokenCss }
+        return LIGHT_TEMPLATES.has(template)
+          ? [dark, { template, out: `${base}-light.html`, tokens: light }]
+          : [dark]
+      }),
+  }
+}
+
+/**
+ * Every template takes the same value map, so one carrying no count
+ * placeholder simply resolves none of them. What a template must not do is name
+ * a placeholder nothing fills.
+ */
+export function fillTemplate(
+  template: string,
+  source: string,
+  values: Readonly<Record<string, string>>,
+  tokens: string,
+): string {
+  let html = source
+  for (const [key, value] of Object.entries({ ...values, TOKENS: tokens })) {
+    html = html.replaceAll(`{{${key}}}`, value)
+  }
+
+  const unresolved = html.match(/{{[A-Z_]+}}/g)
+  if (unresolved) {
+    throw new FrameError(
+      `${template} carries unresolved placeholders ${[...new Set(unresolved)].join(', ')}`,
+    )
+  }
+  return html
+}

package/src/claude/cases/misc.ts

@@ -69,6 +69,11 @@ export const MISC_CASES: readonly SkillCase[] = [
       "The e2e folder has specs and helpers mixed together and I'm adding two more, where should they go?",
     expect: 'codebase-layout',
   },
+  {
+    prompt:
+      "I'm adding a field to the JSON this command prints and renaming one flag, anything to watch?",
+    expect: 'api-design',
+  },
   {
     prompt: 'Does our github about text still match what the readme says?',
     expect: 'repo-metadata',

package/src/claude/skills-audit.ts

@@ -34,6 +34,9 @@ export const CORPORA: readonly string[] = [
 export const PRACTICE_SKILLS: readonly string[] = [
   join(SHIPPED_CORPUS, 'codebase-layout'),
   join(SHIPPED_CORPUS, 'test-craft'),
+  join(SHIPPED_CORPUS, 'review-craft'),
+  join(SHIPPED_CORPUS, 'systematic-debugging'),
+  join(SHIPPED_CORPUS, 'api-design'),
 ]
 
 /** The closing H2s a practice skill carries, matched exactly outside fences. */

package/src/cli.ts

@@ -30,6 +30,7 @@ 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 hooks } from '@/commands/hooks'
 import { register as audits } from '@/commands/audits'
 import { register as gate } from '@/commands/gate'
 import { register as secrets } from '@/commands/secrets'
@@ -91,6 +92,7 @@ migrate(program)
 sessions(program)
 targets(program)
 worktrees(program)
+hooks(program)
 secrets(program)
 deps(program)
 labels(program)

package/src/commands/claude.ts

@@ -111,7 +111,7 @@ interface PluginUpdateOptions {
 /**
  * `no-claude` and `no-plugin` name permanent conditions on a machine that
  * never carries the marketplace plugin at all, matching the `gh-missing` and
- * `no-repository` reasons `.husky/post-merge`'s other two steps already stay
+ * `no-repository` reasons the post-merge hook's other two steps already stay
  * quiet on forever rather than nagging a project that will never fix them.
  * Every other reason is a real defect and prints.
  */

package/src/commands/docs.ts

@@ -1,7 +1,6 @@
 import type { Command } from 'commander'
-import { registerPassThroughVerbs } from '@/commands/pass-through'
+import { type DocEntry, listDocs } from '@/docs/list'
 import { listTopics, readTopic, resolveTopic } from '@/docs/read'
-import { execScript } from '@/exec'
 import { checkoutMismatchWarning, PROJECT_ROOT } from '@/project-root'
 import { intro, logError, logInfo, logStep, logWarn, outro } from '@/ui'
 
@@ -22,19 +21,60 @@ export function register(program: Command): void {
         '',
       ].join('\n'),
     )
-    .action(async (topic: string | undefined) => {
-      if (topic === undefined) {
-        intro('canon docs')
-        await execScript('docs/list.sh', [])
-        return
-      }
-
-      process.exitCode = get(topic)
+    .action((topic: string | undefined) => {
+      process.exitCode = topic === undefined ? list({}) : get(topic)
     })
 
-  registerPassThroughVerbs(docs, 'docs', ['list'])
+  docs
+    .command('list')
+    .description('List the docs and domain context with their descriptions')
+    .helpOption('-h, --help', 'Show this help message')
+    .option('--json', 'Emit machine-readable JSON')
+    .action((opts: ListOptions) => {
+      process.exitCode = list(opts)
+    })
+}
+
+interface ListOptions {
+  readonly json?: boolean
 }
 
+/**
+ * The text listing is frame lines on stderr and the `--json` record is the one
+ * thing on stdout, so a caller piping it through a wrapper reads JSON alone.
+ * The frame opens after the `--json` branch and never wraps it.
+ */
+function list(opts: ListOptions): number {
+  const catalog = listDocs(PROJECT_ROOT)
+  const mismatch = checkoutMismatchWarning(process.cwd())
+
+  if (opts.json) {
+    if (mismatch !== undefined) logWarn(mismatch)
+    const docs: DocEntry[] = catalog.hasContext
+      ? [...catalog.docs, ...catalog.context]
+      : catalog.docs
+    process.stdout.write(`${JSON.stringify({ docs })}\n`)
+    return 0
+  }
+
+  intro('canon docs')
+  if (mismatch !== undefined) logWarn(mismatch)
+
+  logStep('Docs')
+  for (const entry of catalog.docs) logInfo(describeEntry(entry))
+
+  if (catalog.hasContext) {
+    logStep('Domain context')
+    for (const entry of catalog.context) logInfo(describeEntry(entry))
+  }
+
+  outro()
+  return 0
+}
+
+const describeEntry = (entry: DocEntry): string =>
+  `${entry.name} : ${entry.description}`
+
 /**
  * Writes the document body to stdout and every frame line to stderr, so a
  * caller capturing the output with `$(...)` receives the document alone.

package/src/commands/hooks.ts

@@ -0,0 +1,67 @@
+import type { Command } from 'commander'
+import {
+  readMergedSubjects,
+  runCanon,
+  runPostMerge,
+  STEP_VERBS,
+} from '@/hooks/post-merge'
+import { mainWorktreeRoot } from '@/worktree'
+
+interface PostMergeOptions {
+  readonly root?: string
+}
+
+export function register(program: Command): void {
+  const hooks = program
+    .command('hooks')
+    .description('Run the steps a git hook drives')
+    .helpOption('-h, --help', 'Show this help message')
+
+  hooks
+    .command('post-merge')
+    .description('Run the post-merge steps in order and report each in a line')
+    .helpOption('-h, --help', 'Show this help message')
+    .option(
+      '--root <path>',
+      'Main worktree root holding the board and the records',
+    )
+    .addHelpText(
+      'after',
+      [
+        '',
+        'Runs these steps in order, each a child call reading its --json record:',
+        ...Object.values(STEP_VERBS).map((verb) => `  canon ${verb.join(' ')}`),
+        '',
+        'The archive runs once per pull request number the merge brought in.',
+        'Lines go to stderr, and an ordinary merge prints nothing.',
+        '',
+        'The reclaim runs from the working directory with no root, so a pull',
+        'inside a linked worktree never removes the worktree it stands in.',
+        '',
+        'Environment:',
+        '  CANON_SKIP_RECLAIM=1        skip the worktree reclaim',
+        '  CANON_SKIP_UPGRADE=1        skip the CLI reinstall',
+        '  CANON_SKIP_PLUGIN_UPDATE=1  skip the plugin update',
+        '',
+        'Exit codes:',
+        '  0  always, since a hook failing aborts nothing useful',
+        '',
+        'Examples:',
+        '  canon hooks post-merge',
+        '  CANON_SKIP_UPGRADE=1 canon hooks post-merge --root "$root"',
+        '',
+      ].join('\n'),
+    )
+    .action(async (opts: PostMergeOptions) => {
+      const cwd = process.cwd()
+      await runPostMerge({
+        root: opts.root ?? (await mainWorktreeRoot()),
+        cwd,
+        subjects: await readMergedSubjects(cwd),
+        env: process.env,
+        run: runCanon,
+        write: (text) => process.stderr.write(text),
+      })
+      process.exitCode = 0
+    })
+}