@erclx/canon 5.58.0 → 5.59.0

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## [5.59.0](https://github.com/erclx/canon/compare/v5.58.0...v5.59.0) (2026-10-24)
+
+
+### Features
+
+* **cli:** name the release that retired a verb and find its callers ([#2662](https://github.com/erclx/canon/issues/2662)) ([32fddb5](https://github.com/erclx/canon/commit/32fddb5f8c363441fc18ffb4243c08a65a863a67))
+* **gov:** report rule coverage after gov sync ([#2660](https://github.com/erclx/canon/issues/2660)) ([c087965](https://github.com/erclx/canon/commit/c087965acd64249f8dfbe9ca1d98a7857621d380))
+* **pr:** compose bot pull request merge messages ([#2659](https://github.com/erclx/canon/issues/2659)) ([698991c](https://github.com/erclx/canon/commit/698991c71b6423279756f023c86cd2537ae46017))
+* **sandbox:** add a canon-feedback-triage anchor scenario ([#2656](https://github.com/erclx/canon/issues/2656)) ([ae45573](https://github.com/erclx/canon/commit/ae45573e2b385b97cdfbf300b4d1f9bb0f3db839))
+
+
+### Bug Fixes
+
+* **sync:** write the stamp in the formatter shape ([#2655](https://github.com/erclx/canon/issues/2655)) ([a34c5fb](https://github.com/erclx/canon/commit/a34c5fb2d18314ec31d83640be387057b68638a7))
+
 ## [5.58.0](https://github.com/erclx/canon/compare/v5.57.0...v5.58.0) (2026-10-24)
 
 

package/README.md

@@ -140,7 +140,7 @@ Bun, Git, and a shell are required, and the GitHub CLI is optional.
 - [Bun](https://bun.sh) for the CLI runtime and scripts
 - [Git](https://git-scm.com) with worktree support
 - [GitHub CLI](https://cli.github.com) (optional) for ship flows
-- Shell: `zsh` or bash 4+ (`brew install bash` on macOS).
+- Shell: `zsh`, since bootstrap appends its aliases to `~/.zshrc`.
 
 Clone the repo, then run the bootstrap script. It installs dependencies, links the CLI globally, and appends a marked block of Claude Code shell aliases to your `~/.zshrc`.
 

package/claude/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "canon",
   "description": "Runs your agent's work and keeps its code good, on one setup for every repo.",
-  "version": "5.58.0",
+  "version": "5.59.0",
   "author": {
     "name": "Eric Le",
     "url": "https://github.com/erclx"

package/claude/skills/target-update/SKILL.md

@@ -64,6 +64,8 @@ Target update: `<path>`, canon `<installed>` to `<running>`.
 
 **Migrations, in run order:** <each pending or refused entry from migrate status, with its verb>
 
+**Retired calls:** <each `retiredCallers` entry from migrate status, with its file, line, the release that retired the verb, and where the work went, or omitted when the list is empty>
+
 **Drift:** <each non-empty cause from sync --check, with its count and paths>
 
 **Where it lands:** <the linked worktree this run is already in, or the worktree `.claude/worktrees/<name>/` it will enter, or the branch it will create in place when the operator declines a worktree>
@@ -73,11 +75,13 @@ Target update: `<path>`, canon `<installed>` to `<running>`.
 **Commands, in order:** <the exact commands Steps 4 to 6 will run>
 ```
 
+A retired call is no migration, so no step here fixes it. Name it in the preview and leave the edit to the operator, who owns the script.
+
 Summarize the changelog for this project, not for the toolkit. Drop an entry that touches nothing the target holds, and lead with anything a migration or a sync will change.
 
 ### Nothing pending
 
-When the changelog range is empty, `migrate status` lists nothing pending or refused, and the drift lines hold nothing a step here would take, write nothing. Invoke `canon:target-check` and report the target current with its table.
+When the changelog range is empty, `migrate status` lists nothing pending or refused and no `retiredCallers`, and the drift lines hold nothing a step here would take, write nothing. Invoke `canon:target-check` and report the target current with its table.
 
 ### Take a branch after the go-ahead
 

package/docs/agents/install-and-sync.md

@@ -24,7 +24,7 @@ A flat installed-rule layout makes `gov sync` report "No governance surfaces fou
 
 ## Governance sync
 
-`canon gov sync [target]` updates what `.claude/rules/canon/` holds and adds nothing. `.claude/rules/project/` is never read, so put project rules there.
+`canon gov sync [target]` updates what `.claude/rules/canon/` holds and adds nothing. `.claude/rules/project/` is never read, so put project rules there. After an apply it lists each copied rule with its globs and matching file count, and `--json` puts `{ "coverage": [...] }` on stdout.
 
 - A rule the toolkit no longer ships is deleted, edited or not
 - A rule renamed in `governance/renames.toml` moves, and its local edits are dropped

package/docs/agents/migrate.md

@@ -38,6 +38,12 @@ kind: reference
 
 `status` runs each verb as a dry run and exits 2 while any is pending, with a refusal outranking that. Each entry's `verb` carries the flags its dry run used, so append `--write` to it. A clean entry can turn pending once an earlier one applies, so run it again after each `--write`.
 
+`status --json` also carries `retiredCallers`, the project calls to a verb a release retired.
+
+- Each entry has `file`, `line`, `verb`, `release`, and `movedTo`
+- The scan reads the workflow folder, the `package.json` scripts, `scripts/`, and the files those name, matching a command line or an argument list and never prose
+- A caller changes no exit code, since no `--write` fixes one, so edit the script by hand
+
 Three markers keep an old spelling on a line. Each also covers the nearest non-blank line, below it for `canon-keep-record-root` and above it for `canon-keep-surface-root`.
 
 | Marker                    | Keeps                                          |

package/docs/target/sync.md

@@ -43,10 +43,12 @@ Add `--json` for a machine-readable report and `--exit-code` to fail CI when a t
 ## Targeted
 
 - Seed docs such as `CLAUDE.md` and `canon/REQUIREMENTS.md`: merge by hand, keeping the project's customizations
-- Installed governance rules: `canon gov sync <path>`, which adds no new rules
+- Installed governance rules: `canon gov sync <path>`, which adds no new rules and reports coverage afterward
 - Tooling configs and seeds: read differences with `canon tooling diff <stack> <path>`, then `canon tooling sync <stack> <path> --write`, which overwrites golden configs and copies each seed once
 - Index regeneration: `canon indexes regen`
 
+After `canon gov sync` applies, it lists each rule it copied with its globs and how many project files match. A `ui/` rule adds a pointer to `/canon:ux-audit`. `--json` writes `{ "coverage": [{ "rule", "paths", "files", "ui" }] }` to stdout, empty when nothing was copied, with `files` null outside git. The report never changes the exit code.
+
 Try a scenario from [sandbox](../../canon/context/development/sandbox.md) before syncing a real project.
 
 ## Running sync from an agent session

package/docs/workflow/operating-model.md

@@ -36,7 +36,7 @@ Each role keeps to its own writes, and five rules cover how the roles meet.
 7. A pass posts `## Review` while anything is open and `## Review closed` when nothing is. The reviewer then runs `canon pr lift`.
 8. The human merges with `canon pr merge <number>`. The orchestrator tells any trailing worker whose files the merge touched to run `review-address`, which rebases.
 
-Each worker halts at the PR, and the merge stays a human gate. `canon pr merge` squashes with the body's Summary, Key changes, and Technical context as the message, and the seeded deny rule covers the forms an agent writes by default. The merge button stays for a bot's pull request, such as a dependency bump or a release.
+Each worker halts at the PR, and the merge stays a human gate. `canon pr merge` squashes with the body's Summary, Key changes, and Technical context as the message, and the seeded deny rule covers the forms an agent writes by default. A release-please or Dependabot pull request merges the same way, from the bot's own body.
 
 ## The review layer
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@erclx/canon",
   "type": "module",
-  "version": "5.58.0",
+  "version": "5.59.0",
   "description": "Runs your agent's work and keeps its code good, on one setup for every repo.",
   "license": "MIT",
   "bin": {
@@ -30,14 +30,14 @@
     "check:shell": "find scripts tooling claude .claude/hooks -name '*.sh' -exec shellcheck --severity=warning {} + && find .husky -maxdepth 1 -type f -exec shellcheck --severity=warning --shell=sh {} +",
     "check:lint": "oxlint --disable-nested-config --max-warnings 0",
     "check:types": "tsc --noEmit",
-    "check:install": "./scripts/core/install-check.sh",
+    "check:install": "bun scripts/core/install-check.ts",
     "test": "bun --bun vitest run",
     "prepare": "husky",
     "check": "bun src/cli.ts gate run",
     "check:ci": "bun src/cli.ts gate run --all",
     "update": "bun update --interactive && bun run check",
     "clean": "rm -rf node_modules && bun pm cache rm && bun install",
-    "bootstrap": "./scripts/core/bootstrap.sh",
+    "bootstrap": "bun scripts/core/bootstrap.ts",
     "canon:sandbox": "canon sandbox",
     "canon:sandbox:reset": "canon sandbox reset",
     "web:tokens": "bun src/cli.ts design css --no-components > web/src/styles/tokens.css.new && (echo '/* Generated by `canon design css --no-components`. Regenerate with `bun run web:tokens`. Do not hand-edit. */'; cat web/src/styles/tokens.css.new) > web/src/styles/tokens.css && rm web/src/styles/tokens.css.new",

package/scripts/core/bootstrap.ts

@@ -0,0 +1,120 @@
+/**
+ * Installs dependencies, links the canon CLI globally, and appends the marked
+ * alias block to the user's `.zshrc`, the only file this writes outside the
+ * repository. Runs on Bun alone, so a stock macOS bash 3.2 never enters it.
+ */
+import { appendFileSync, existsSync, readFileSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+import {
+  intro,
+  logAdd,
+  logError,
+  logInfo,
+  logStep,
+  logWarn,
+  outro,
+} from '../../src/cli/ui'
+
+const root = fileURLToPath(new URL('../..', import.meta.url)).replace(/\/$/, '')
+
+const MARKER_OPEN = '# >>> canon aliases >>>'
+const MARKER_CLOSE = '# <<< canon aliases <<<'
+
+function zshrcPath(): string {
+  const dir = process.env.ZDOTDIR
+  return join(dir !== undefined && dir !== '' ? dir : homedir(), '.zshrc')
+}
+
+/** `$TOOLKIT` stays a literal in the block, so the shell expands it on load. */
+function aliasBlock(): string {
+  return `${MARKER_OPEN}
+TOOLKIT="${root}"
+export CLAUDE_CODE_ENABLE_TODO_TOOLS=1
+
+alias cl='claude'
+alias clr='cl -r'
+alias clc='cl -c'
+alias clw='cl -w'
+alias cls='cl --model sonnet'
+
+alias clp='claude --plugin-dir $TOOLKIT/claude'
+alias clpc='clp -c'
+alias clps='clp --model sonnet'
+alias clpa='clp agents'
+alias clpac='clpa --cwd .'
+${MARKER_CLOSE}`
+}
+
+function run(step: string, cmd: string[]): void {
+  const result = Bun.spawnSync(cmd, {
+    cwd: root,
+    stdout: 'ignore',
+    stderr: 'pipe',
+  })
+  if (result.exitCode !== 0) {
+    throw new Error(`${step} failed: ${result.stderr.toString().trim()}`)
+  }
+}
+
+function installCli(): void {
+  logStep('Installing the canon CLI')
+  run('bun install', ['bun', 'install', '--cwd', root])
+  run('bun link', ['bun', 'link', '--cwd', root])
+  logInfo('Dependencies installed and canon linked')
+}
+
+function installAliases(): void {
+  const zshrc = zshrcPath()
+  logStep('Installing Claude Code shell aliases')
+  logInfo(
+    `This step manages a marked alias block in ${zshrc}, the only file outside the repo this script writes.`,
+  )
+  logInfo(
+    'Delete the block and its two marker comments to remove the aliases. Re-running never adds a second copy.',
+  )
+
+  const existing = existsSync(zshrc) ? readFileSync(zshrc, 'utf8') : ''
+  if (existing.includes(MARKER_OPEN)) {
+    logInfo(`Aliases already present in ${zshrc}, skipping`)
+    return
+  }
+  if (/^alias clp=/m.test(existing)) {
+    logWarn(
+      `An unmanaged clp alias is already in ${zshrc}. Leaving it untouched.`,
+    )
+    logWarn('Remove it and re-run to switch to the managed block.')
+    return
+  }
+
+  appendFileSync(zshrc, `\n${aliasBlock()}\n`)
+  logAdd(`Appended canon alias block to ${zshrc}`)
+  logInfo(`Run 'source ${zshrc}' or open a new shell to load them`)
+}
+
+function verifyCli(): void {
+  logStep('Verifying the install')
+  if (Bun.which('canon') !== null) {
+    logInfo('canon resolves on PATH')
+  } else {
+    logWarn(
+      'canon not on PATH yet. Ensure $BUN_INSTALL/bin is exported, then re-open your shell.',
+    )
+  }
+}
+
+intro('canon bootstrap')
+let failed = false
+try {
+  installCli()
+  installAliases()
+  verifyCli()
+} catch (error) {
+  failed = true
+  logError(error instanceof Error ? error.message : String(error))
+} finally {
+  outro()
+}
+process.exit(failed ? 1 : 0)

package/scripts/core/install-check.ts

@@ -0,0 +1,193 @@
+/**
+ * Verifies the published install path end to end: packs this repo, installs
+ * the tarball for production, and runs `canon init` from it into a fresh
+ * project. Runs on Bun alone.
+ */
+import { existsSync, mkdirSync, rmSync } from 'node:fs'
+import { join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+import {
+  intro,
+  logError,
+  logInfo,
+  logStep,
+  outro,
+  pipeOutput,
+} from '../../src/cli/ui'
+
+const root = fileURLToPath(new URL('../..', import.meta.url)).replace(/\/$/, '')
+const tmpRoot = join(root, '.canon/tmp/install-check')
+const packDir = join(tmpRoot, 'pack')
+const extractDir = join(tmpRoot, 'extract')
+const targetDir = join(tmpRoot, 'target')
+
+const HELP = `Usage: scripts/core/install-check.ts [--keep]
+
+Verifies the published install path end to end:
+  1. Packs this repo into a tarball at .canon/tmp/install-check/pack
+  2. Extracts it and asserts sandbox is absent from the tree
+  3. Runs bun install --production in the extracted tree
+  4. Runs the CLI with --help from the extracted tree to confirm it resolves
+  5. Scaffolds a fresh project in .canon/tmp/install-check/target
+  6. Runs canon init from the extracted package and asserts a scaffold landed
+
+Flags:
+  --keep    Keep the tmp tree on exit for inspection
+`
+
+/**
+ * Every domain canon init installs needs at least one path here. A domain with
+ * no assertion can truncate silently: init still exits 0 because run_domain
+ * catches a failed domain, and the gate stays green while the target is
+ * missing everything that domain provides.
+ *
+ * Authoring references name no path because they ship inside the plugin's
+ * skills rather than installing into a target. The two rule paths stand for
+ * the `claude` and `canon` groups `base` takes whole.
+ */
+const SCAFFOLD_PATHS = [
+  'CLAUDE.md',
+  '.claude',
+  'canon/context/index.md',
+  '.oxfmtrc.json',
+  '.lintstagedrc',
+  '.husky/pre-commit',
+  '.github/workflows/verify.yml',
+  'scripts/verify.ts',
+  '.claude/rules/canon/claude/output.md',
+  '.claude/rules/canon/canon/scratch.md',
+]
+
+const args = process.argv.slice(2)
+if (args.includes('--help') || args.includes('-h')) {
+  process.stdout.write(HELP)
+  process.exit(0)
+}
+const keep = args.includes('--keep')
+
+/** Runs a command to completion, showing its output inside the frame. */
+function run(
+  failure: string,
+  cmd: string[],
+  opts: { cwd?: string; show?: boolean } = {},
+): string {
+  const result = Bun.spawnSync(cmd, {
+    cwd: opts.cwd ?? root,
+    stdin: 'ignore',
+    stdout: 'pipe',
+    stderr: 'pipe',
+  })
+  const stdout = result.stdout.toString()
+  const output = `${stdout}${result.stderr.toString()}`.trim()
+  if (opts.show && output !== '') pipeOutput(output)
+  if (result.exitCode !== 0) {
+    if (!opts.show && output !== '') pipeOutput(output)
+    throw new Error(failure)
+  }
+  return stdout
+}
+
+function check(): void {
+  logStep('Assert excluded path exists in source')
+  // An absence check over a path the source tree no longer holds passes on
+  // nothing, so the excluded tree has to exist here before its absence below
+  // can mean the publish left it out.
+  if (!existsSync(join(root, 'sandbox/exempt.toml'))) {
+    throw new Error(
+      'sandbox/exempt.toml is missing from the source tree, so the absence check below would pass on nothing',
+    )
+  }
+  logInfo('Present: sandbox/exempt.toml')
+
+  logStep('Pack')
+  const packed = run('bun pm pack failed', [
+    'bun',
+    'pm',
+    'pack',
+    '--quiet',
+    '--ignore-scripts',
+    '--destination',
+    packDir,
+  ])
+  const tarball = packed.trim().split('\n').pop() ?? ''
+  logInfo(`Packed to ${tarball}`)
+
+  logStep('Extract')
+  run('tar extract failed', [
+    'tar',
+    '-xzf',
+    tarball,
+    '-C',
+    extractDir,
+    '--strip-components=1',
+  ])
+  logInfo(`Extracted to ${extractDir}`)
+
+  logStep('Assert excluded path is absent')
+  if (existsSync(join(extractDir, 'sandbox'))) {
+    throw new Error(
+      'sandbox shipped in the tarball, and the files field in package.json leaves it out',
+    )
+  }
+  logInfo('Absent: sandbox')
+
+  logStep('Install dependencies (production)')
+  run(
+    'bun install --production failed',
+    ['bun', 'install', '--production', '--ignore-scripts', '--silent'],
+    { cwd: extractDir, show: true },
+  )
+  logInfo('Dependencies installed without devDependencies')
+
+  logStep('Confirm CLI runs')
+  run('canon --help failed', ['bun', 'run', 'src/cli.ts', '--help'], {
+    cwd: extractDir,
+  })
+  logInfo('canon --help ran clean from the extracted package')
+
+  logStep('Scaffold fresh project')
+  mkdirSync(targetDir, { recursive: true })
+  run('git init failed', ['git', 'init', '--quiet'], { cwd: targetDir })
+  logInfo(`Initialized git in ${targetDir}`)
+
+  logStep('Run canon init')
+  run(
+    'canon init failed',
+    ['bun', 'run', join(extractDir, 'src/cli.ts'), 'init', '--stack', 'base'],
+    { cwd: targetDir, show: true },
+  )
+  logInfo('canon init completed')
+
+  logStep('Assert scaffold')
+  for (const path of SCAFFOLD_PATHS) {
+    if (!existsSync(join(targetDir, path))) {
+      throw new Error(`Missing after canon init: ${path}`)
+    }
+    logInfo(`Found: ${path}`)
+  }
+
+  logStep('Verification passed')
+  logInfo('Manual check still needed: bun link and global canon invocation')
+}
+
+rmSync(tmpRoot, { recursive: true, force: true })
+mkdirSync(packDir, { recursive: true })
+mkdirSync(extractDir, { recursive: true })
+
+intro('Install verification')
+let failed = false
+try {
+  check()
+} catch (error) {
+  failed = true
+  logError(error instanceof Error ? error.message : String(error))
+} finally {
+  if (keep) {
+    logInfo(`Kept artifacts at ${tmpRoot}`)
+  } else {
+    rmSync(tmpRoot, { recursive: true, force: true })
+  }
+  outro()
+}
+process.exit(failed ? 1 : 0)

package/src/cli/retired.ts

@@ -0,0 +1,63 @@
+export interface RetiredVerb {
+  /** The words a caller types after `canon`, one for a group and two for a subcommand. */
+  readonly path: readonly string[]
+  /** The release that dropped the verb, from the changelog. */
+  readonly release: string
+  readonly movedTo: string
+}
+
+const DESIGN_MOVED =
+  'the design values now live in the stylesheet your canon/DESIGN.md lead names'
+
+/**
+ * Every verb a release dropped, with the release and where the work went. The
+ * router reads this ahead of the parser, and `canon migrate status` reads it to
+ * find project calls. A verb that returns leaves this table in the same change.
+ */
+export const RETIRED_VERBS: readonly RetiredVerb[] = [
+  {
+    path: ['canvas'],
+    release: '5.54.0',
+    movedTo: 'Frameboard, which carries the design board in its own repository',
+  },
+  { path: ['design', 'render'], release: '5.54.0', movedTo: DESIGN_MOVED },
+  { path: ['design', 'install'], release: '5.54.0', movedTo: DESIGN_MOVED },
+  { path: ['design', 'sync'], release: '5.54.0', movedTo: DESIGN_MOVED },
+  { path: ['design', 'fonts'], release: '5.54.0', movedTo: DESIGN_MOVED },
+  { path: ['design', 'list'], release: '5.54.0', movedTo: DESIGN_MOVED },
+  { path: ['design', 'add'], release: '5.54.0', movedTo: DESIGN_MOVED },
+  {
+    path: ['teach'],
+    release: '5.53.0',
+    movedTo: 'the canon:teach-craft skill',
+  },
+  {
+    path: ['slides'],
+    release: '5.53.0',
+    movedTo: 'the canon:teach-craft skill',
+  },
+  {
+    path: ['demo'],
+    release: '5.53.0',
+    movedTo: 'a tool built for composed video',
+  },
+]
+
+/**
+ * Matches the leading words of argv, stopping at the first option so a flag's
+ * value is never read as a verb name.
+ */
+export function findRetired(args: readonly string[]): RetiredVerb | undefined {
+  const words: string[] = []
+  for (const arg of args) {
+    if (arg.startsWith('-')) break
+    words.push(arg)
+  }
+  return RETIRED_VERBS.find((verb) =>
+    verb.path.every((word, index) => words[index] === word),
+  )
+}
+
+export function retiredMessage(verb: RetiredVerb): string {
+  return `error: 'canon ${verb.path.join(' ')}' was retired in v${verb.release}. The work moved to ${verb.movedTo}.`
+}

package/src/cli/ui.ts

@@ -90,9 +90,8 @@ export function intro(title: string): void {
 }
 
 /**
- * Timeline log levels matching `scripts/lib/ui.sh`, so a migrated command
- * prints the same frame as the bash it replaced. All output is stderr,
- * leaving stdout clean for JSON and lists.
+ * Timeline log levels for the framed output every command and `scripts/core/`
+ * script prints. All output is stderr, leaving stdout clean for JSON and lists.
  */
 export function logInfo(message: string): void {
   if (quiet) return
@@ -151,8 +150,7 @@ export function outroSuccess(message: string, detail?: string): void {
 }
 
 /**
- * Indents borrowed output inside an open frame, matching `pipe_output` in
- * `scripts/lib/ui.sh`. Used for a document the command did not compose itself,
+ * Indents borrowed output inside an open frame. Used for a document the command did not compose itself,
  * such as a pull request body or the output of a git mutation.
  */
 export function pipeOutput(text: string): void {

package/src/cli.ts

@@ -40,6 +40,7 @@ import { register as changelog } from '@/commands/changelog'
 import { readInstalled, UNKNOWN_LABEL } from '@/version/installed'
 import { renderHelp } from '@/cli/help'
 import { renderAll, routeHelp } from '@/cli/help-all'
+import { findRetired, retiredMessage } from '@/cli/retired'
 import { setQuiet } from '@/cli/ui'
 
 function showHelp(): void {
@@ -101,8 +102,13 @@ gate(program)
 upgrade(program)
 changelog(program)
 
-const route = routeHelp(program, process.argv.slice(2))
-if (route.kind === 'top') showHelp()
+const args = process.argv.slice(2)
+const retired = findRetired(args)
+const route = routeHelp(program, args)
+if (retired !== undefined) {
+  console.error(retiredMessage(retired))
+  process.exitCode = 1
+} else if (route.kind === 'top') showHelp()
 else if (route.kind === 'all') process.stdout.write(renderAll(route.command))
 else if (route.kind === 'unknown') {
   console.error(`error: unknown command '${route.name}'`)

package/src/commands/gov.ts

@@ -210,6 +210,7 @@ export function register(program: Command): void {
     .description('Update rules already installed under .claude/rules/canon/')
     .argument('[target]', 'Target directory', '.')
     .helpOption('-h, --help', 'Show this help message')
+    .option('--json', 'Emit the coverage record as JSON on stdout')
     .addHelpText(
       'after',
       [
@@ -219,17 +220,22 @@ export function register(program: Command): void {
         'It adds no new rule, which is `canon gov install`, and never touches',
         '.claude/rules/project/.',
         '',
+        'After an apply it lists each rule it copied with the globs it loads on',
+        'and how many files in the target match them. --json writes the same',
+        'list as { "coverage": [{ rule, paths, files, ui }] } on stdout, empty',
+        'when nothing was copied. The report never changes the exit code.',
+        '',
         'Exit codes:',
         '  0  synced, already up to date, or the prompt was cancelled',
         '  1  the target is missing or is the toolkit root',
         '',
       ].join('\n'),
     )
-    .action(async (target: string) => {
+    .action(async (target: string, opts: { json?: boolean }) => {
       process.exitCode = await runDomainSync(
         createGovAdapter(PROJECT_ROOT),
         target,
-        { protectedRoot: PROJECT_ROOT },
+        { protectedRoot: PROJECT_ROOT, json: opts.json },
       )
     })
 

package/src/commands/migrate.ts

@@ -1056,7 +1056,7 @@ async function runStatus(opts: StatusOptions): Promise<number> {
   const mismatch = checkoutMismatchWarning(process.cwd())
   if (mismatch !== undefined) logWarn(mismatch)
 
-  const report = await readMigrationStatus(cliRunner(root))
+  const report = await readMigrationStatus(cliRunner(root), root)
 
   if (opts.json) {
     process.stdout.write(
@@ -1071,6 +1071,12 @@ async function runStatus(opts: StatusOptions): Promise<number> {
     }
   }
 
+  for (const caller of report.retiredCallers) {
+    logWarn(
+      `Retired: ${caller.verb} at ${caller.file}:${caller.line}, retired in v${caller.release}, moved to ${caller.movedTo}`,
+    )
+  }
+
   if (report.pending === 0 && report.refused === 0) {
     logInfo('No migration is pending.')
   }

package/src/commands/pr.ts

@@ -935,7 +935,7 @@ export function register(program: Command): void {
 
   pr.command('merge')
     .description(
-      'Squash-merge a ready pull request with a message carrying only its Summary, Key changes, and Technical context',
+      "Squash-merge a ready pull request with a message carrying only the change: its Summary, Key changes, and Technical context, or a bot pull request's own changelog or package table",
     )
     .argument('[number]', 'Pull request to merge, defaulting to this branch')
     .helpOption('-h, --help', 'Show this help message')
@@ -955,6 +955,13 @@ export function register(program: Command): void {
         'UI pass line dropped. Technical context is optional. Testing, the',
         'reviewer requests, and every other section stay out of the trunk.',
         '',
+        'A release-please or Dependabot pull request is read off its head',
+        'branch, plus the release body opening or a bot author, and needs no',
+        'flag. A release composes to its changelog without the robot line, the',
+        'dividers, and the footer. Dependabot composes to its lead and package',
+        'table, cut at the first `Updates ` line or `<details>` block. A bot body with nothing left',
+        'refuses missing-summary.',
+        '',
         'Refusals are read before the one write, which sends the head it read',
         'as `sha`, so a push after the read refuses rather than merging. The',
         'verb reads the draft flag and not the reviews, since a ready pull',
@@ -4124,6 +4131,8 @@ function mergeApi(root: string, number: string): MergeApi {
           title: row.title,
           body: row.body ?? '',
           head: row.head.sha,
+          branch: row.head.ref ?? '',
+          isBotAuthor: row.user?.type === 'Bot',
         }
       } catch {
         return undefined