@erclx/canon 4.67.0 → 4.69.0

package/src/claude/cases/{claude-workflow.ts → workflow.ts}

@@ -1,8 +1,8 @@
 import type { SkillCase } from '@/claude/skills-rank'
 
 /**
- * The `claude-*` skill family: feature planning, review, and the session
- * artifacts that coordinate work across sessions.
+ * The session workflow skills: feature planning, review, and the artifacts
+ * that coordinate work across sessions.
  *
  * Every positive is phrased away from its skill's own quoted trigger, since a
  * verbatim trigger passes by construction and proves nothing about a prompt in
@@ -10,33 +10,33 @@ import type { SkillCase } from '@/claude/skills-rank'
  * an explicit `Do NOT` boundary against each other, since a boundary in a
  * body does not reach the field a router reads.
  */
-export const CLAUDE_WORKFLOW_CASES: readonly SkillCase[] = [
+export const WORKFLOW_CASES: readonly SkillCase[] = [
   {
     prompt: 'Go fix everything the reviewer flagged on my open PR.',
-    expect: 'claude-address-review',
+    expect: 'review-address',
   },
   {
     prompt:
       'Run the whole implement, verify, review, and ship pipeline for the approved plan.',
-    expect: 'claude-autoship',
+    expect: 'auto-ship',
   },
   {
     prompt: "Pull together a design system from what's already in the app.",
-    expect: 'claude-design-extract',
+    expect: 'design-extract',
   },
   {
     prompt: 'Draw me a diagram of how the pieces of this system connect.',
-    expect: 'claude-diagram',
+    expect: 'draft-diagram',
   },
   {
     prompt:
       'Bring the internal planning docs under .claude up to date with what we decided this session.',
-    expect: 'claude-docs',
+    expect: 'docs-fold',
   },
   {
     prompt:
       'Sketch out a plan for adding this new capability before we touch any code.',
-    expect: 'claude-feature',
+    expect: 'plan-feature',
   },
   {
     prompt:
@@ -46,43 +46,43 @@ export const CLAUDE_WORKFLOW_CASES: readonly SkillCase[] = [
   {
     prompt:
       'We need to measure this properly before committing to an approach.',
-    expect: 'claude-groundwork',
+    expect: 'plan-groundwork',
   },
   {
     prompt: 'Take this pile of raw notes and turn it into filed items.',
-    expect: 'claude-intake',
+    expect: 'plan-intake',
   },
   {
     prompt: 'Walk me through the open intake items so I can decide on each.',
-    expect: 'claude-intake-answer',
+    expect: 'plan-intake-answer',
   },
   {
     prompt:
       "Draft a diff-based proposal for tightening this passage in the standard, don't just edit it.",
-    expect: 'claude-markdown-propose',
+    expect: 'markdown-propose',
   },
   {
     prompt: 'Pull the durable lessons out of this session before it ends.',
-    expect: 'claude-memory-capture',
+    expect: 'memory-capture',
   },
   {
     prompt:
       'Go through the memory folder and propose what to do with each entry.',
-    expect: 'claude-memory-review',
+    expect: 'memory-review',
   },
   {
     prompt:
       'Take on the orchestrator role and coordinate the parallel feature builds.',
-    expect: 'claude-orchestrate',
+    expect: 'role-orchestrator',
   },
   {
     prompt:
       'I am writing the plan for a row another session will build. What may I write, and where do I read what is already in flight?',
-    expect: 'claude-planner',
+    expect: 'role-planner',
   },
   {
     prompt: 'Post a formal review with findings on that open pull request.',
-    expect: 'claude-pr-review',
+    expect: 'review-pr',
   },
   {
     prompt:
@@ -92,7 +92,7 @@ export const CLAUDE_WORKFLOW_CASES: readonly SkillCase[] = [
   {
     prompt:
       'Look over everything that changed on this branch for bugs and edge cases.',
-    expect: 'claude-review',
+    expect: 'review-branch',
   },
   {
     prompt: 'Draft me a script with beats for a screencast recording.',
@@ -101,7 +101,7 @@ export const CLAUDE_WORKFLOW_CASES: readonly SkillCase[] = [
   {
     prompt:
       "Check whether my installed Claude seed docs have drifted from the toolkit's.",
-    expect: 'claude-seed-sync',
+    expect: 'seed-sync',
   },
   {
     prompt: 'Turn this topic into a slide deck I can render.',
@@ -110,37 +110,37 @@ export const CLAUDE_WORKFLOW_CASES: readonly SkillCase[] = [
   {
     prompt:
       'Check whether the markdown I changed violates any authoring standards.',
-    expect: 'claude-standards-audit',
+    expect: 'standards-audit',
   },
   {
     prompt: 'Open a new entry on the task board for this piece of work.',
-    expect: 'claude-tasks',
+    expect: 'task-board',
   },
   {
     prompt: 'Open a learning workspace so I can study this topic properly.',
-    expect: 'claude-teach',
+    expect: 'teach-workspace',
   },
   {
     prompt: 'Generate the Playwright tests I need after this UI change.',
-    expect: 'claude-ui-test',
+    expect: 'ui-test',
   },
   {
     prompt:
       'Look over the interface and tell me what feels unfinished or confusing.',
-    expect: 'claude-ux-audit',
+    expect: 'ux-audit',
   },
   {
     prompt: 'Tell me the paint and layout cost of this page right now.',
-    expect: 'claude-ux-measure',
+    expect: 'ux-measure',
   },
   {
     prompt:
       'I am building this branch for another session. What am I on the hook for, and what is off limits?',
-    expect: 'claude-worker',
+    expect: 'role-worker',
   },
   {
     prompt: 'Get me set up in a fresh Claude Code worktree for this branch.',
-    expect: 'claude-worktree',
+    expect: 'session-worktree',
   },
 
   // Negatives: pairs whose bodies already carry an explicit Do NOT boundary.
@@ -151,23 +151,23 @@ export const CLAUDE_WORKFLOW_CASES: readonly SkillCase[] = [
   },
   {
     prompt: 'Sort through this brain dump and write it up as findings.',
-    expect: 'claude-intake',
+    expect: 'plan-intake',
   },
   {
     prompt:
       "Go through what's still unanswered in the intake folder and decide.",
-    expect: 'claude-intake-answer',
+    expect: 'plan-intake-answer',
   },
   {
     prompt: 'Check this markdown against the house style rules.',
-    expect: 'claude-standards-audit',
+    expect: 'standards-audit',
   },
   {
     prompt: 'Find the rough, unfinished-feeling spots in this interface.',
-    expect: 'claude-ux-audit',
+    expect: 'ux-audit',
   },
   {
     prompt: 'Tell me the render cost of this page in the browser.',
-    expect: 'claude-ux-measure',
+    expect: 'ux-measure',
   },
 ]

package/src/claude/plugin-update.ts

@@ -0,0 +1,48 @@
+/** One row of `claude plugin list --json`, the fields this module reads. */
+export interface PluginInstall {
+  readonly id: string
+  readonly version: string
+}
+
+/**
+ * The plugin's own name, out of a `plugin.json` buffer. `undefined` on
+ * anything that fails to parse or carries no string `name`, so a caller
+ * refuses rather than matching against `undefined@`.
+ */
+export function readPluginName(manifest: string): string | undefined {
+  try {
+    const parsed = JSON.parse(manifest) as { name?: unknown }
+    return typeof parsed.name === 'string' ? parsed.name : undefined
+  } catch {
+    return undefined
+  }
+}
+
+export type MatchResult =
+  | { readonly kind: 'matched'; readonly install: PluginInstall }
+  | { readonly kind: 'none' }
+  | { readonly kind: 'many'; readonly installs: readonly PluginInstall[] }
+
+/**
+ * `id` is `<name>@<marketplace>`, so a name alone can match more than one row
+ * when the same plugin is installed from two marketplaces at once. Refusing
+ * that case rather than picking a row is the same move `readPluginName`
+ * makes: nothing here guesses at an ambiguity the caller can see plainly.
+ */
+export function matchInstall(
+  name: string,
+  installs: readonly PluginInstall[],
+): MatchResult {
+  const prefix = `${name}@`
+  const matches = installs.filter((install) => install.id.startsWith(prefix))
+
+  if (matches.length === 0) return { kind: 'none' }
+  if (matches.length > 1) return { kind: 'many', installs: matches }
+  return { kind: 'matched', install: matches[0] as PluginInstall }
+}
+
+export function updatedMessage(before: string, after: string): string {
+  return after === before
+    ? `Reinstalled ${after}, unchanged.`
+    : `Updated ${before} to ${after}.`
+}

package/src/commands/claude.ts

@@ -3,7 +3,16 @@ import { chmod, readFile } from 'node:fs/promises'
 import { homedir } from 'node:os'
 import { join, resolve } from 'node:path'
 import type { Command } from 'commander'
+import { execa } from 'execa'
+import { singleLine } from '@/commands/upgrade'
+import { gitEnv } from '@/git-env'
 import { claudeChain, pendingEntries, planGitignore } from '@/claude/gitignore'
+import {
+  matchInstall,
+  type PluginInstall,
+  readPluginName,
+  updatedMessage,
+} from '@/claude/plugin-update'
 import {
   applySeeds,
   countByScope,
@@ -90,6 +99,37 @@ interface SkillsDriftOptions {
   readonly json?: boolean
 }
 
+interface PluginUpdateOptions {
+  readonly json?: boolean
+}
+
+/**
+ * `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
+ * quiet on forever rather than nagging a project that will never fix them.
+ * Every other reason is a real defect and prints.
+ */
+type PluginUpdateReason =
+  | 'no-claude'
+  | 'no-manifest'
+  | 'no-name'
+  | 'list-failed'
+  | 'no-plugin'
+  | 'ambiguous'
+  | 'update-failed'
+  | 'after-list-failed'
+
+interface PluginUpdateRecord {
+  readonly root: string
+  readonly id?: string
+  readonly before?: string
+  readonly after?: string
+  readonly state: 'updated' | 'current' | 'refused'
+  readonly reason?: PluginUpdateReason
+  readonly message: string
+}
+
 interface SkillsReachOptions {
   readonly json?: boolean
 }
@@ -111,11 +151,24 @@ const SEEDED_FILES: readonly string[] = [
 const SEEDED_DIRS: readonly string[] = ['memory', 'tasks', 'wireframes']
 const USER_DIR = join('tooling', 'claude', 'user')
 const STATUSLINE = 'statusline-command.sh'
+const PLUGIN_MANIFEST = join('claude', '.claude-plugin', 'plugin.json')
+
+/** A local cache read, not a network round trip, matching reclaim.ts's own bound for `claude agents --json`. */
+const PLUGIN_LIST_TIMEOUT_MS = 10_000
+
+/**
+ * `claude plugin update` fetches a marketplace archive over the network, so a
+ * stalled fetch should not hang the caller, which is a git hook on the
+ * ordinary path.
+ */
+const PLUGIN_UPDATE_TIMEOUT_MS = 60_000
 
 export function register(program: Command): void {
   const claude = program
     .command('claude')
-    .description('Claude workflow (init, seeds, sync, setup, routing)')
+    .description(
+      'Claude workflow (init, seeds, sync, setup, routing, plugin-update)',
+    )
     .helpOption('-h, --help', 'Show this help message')
     .addHelpText(
       'after',
@@ -227,6 +280,39 @@ export function register(program: Command): void {
       process.exitCode = runRouting(path, opts)
     })
 
+  claude
+    .command('plugin-update')
+    .description(
+      'Update the installed marketplace plugin cache to match this CLI',
+    )
+    .helpOption('-h, --help', 'Show this help message')
+    .option('--json', 'Add a machine-readable record on stdout')
+    .addHelpText(
+      'after',
+      [
+        '',
+        'Mechanics:',
+        '  Reads the plugin name out of claude/.claude-plugin/plugin.json,',
+        '  matches it against an installed row from `claude plugin list',
+        '  --json` by id prefix (<name>@), then runs `claude plugin update',
+        '  <id> -y`. There is no --json on the update call itself, so the',
+        '  version is read back off `claude plugin list --json` again and',
+        '  compared to what it was before.',
+        '',
+        'Exit codes:',
+        '  0  current already, or the update ran',
+        '  1  refused, with the reason on stderr',
+        '',
+        'Examples:',
+        '  canon claude plugin-update',
+        '  canon claude plugin-update --json',
+        '',
+      ].join('\n'),
+    )
+    .action(async (opts: PluginUpdateOptions) => {
+      process.exitCode = await runPluginUpdate(opts)
+    })
+
   const skills = claude
     .command('skills')
     .description('Plugin skill catalog (list, audit, drift, reach, rank)')
@@ -830,6 +916,200 @@ function reportRouting(
   )
 }
 
+/**
+ * Reads the plugin name off the manifest, matches it against an installed row,
+ * runs the update, and reads the version back off the same list rather than
+ * trusting the update call's own report, since `claude plugin update` carries
+ * no `--json` to answer with. `canon upgrade` makes the identical move for the
+ * package managers it drives.
+ */
+async function runPluginUpdate(opts: PluginUpdateOptions): Promise<number> {
+  const mismatch = checkoutMismatchWarning(process.cwd())
+  intro('canon claude plugin-update')
+  if (mismatch !== undefined) logWarn(mismatch)
+
+  const manifestPath = join(PROJECT_ROOT, PLUGIN_MANIFEST)
+  let manifestText: string
+  try {
+    manifestText = await readFile(manifestPath, 'utf8')
+  } catch {
+    return refusePluginUpdate(
+      opts,
+      'no-manifest',
+      `No manifest at ${manifestPath}, so there is no plugin name to update.`,
+    )
+  }
+
+  const name = readPluginName(manifestText)
+  if (name === undefined) {
+    return refusePluginUpdate(
+      opts,
+      'no-name',
+      `No name field in ${manifestPath}, so there is nothing to match against an installed plugin.`,
+    )
+  }
+
+  logStep('Manifest')
+  logInfo(`${name}, from ${manifestPath}`)
+
+  const before = await listPluginInstalls()
+  if (before.kind === 'missing') {
+    return refusePluginUpdate(
+      opts,
+      'no-claude',
+      'claude is not on PATH, so no installed plugin could be read.',
+    )
+  }
+  if (before.kind === 'failed') {
+    return refusePluginUpdate(
+      opts,
+      'list-failed',
+      `\`claude plugin list --json\` failed. ${before.detail}`,
+    )
+  }
+
+  const match = matchInstall(name, before.installs)
+  if (match.kind === 'none') {
+    return refusePluginUpdate(
+      opts,
+      'no-plugin',
+      `No installed plugin carries the id prefix "${name}@". Install it with \`claude plugin install\` first.`,
+    )
+  }
+  if (match.kind === 'many') {
+    return refusePluginUpdate(
+      opts,
+      'ambiguous',
+      `Multiple installed plugins share the name "${name}": ${match.installs
+        .map((install) => install.id)
+        .join(', ')}. Refusing rather than picking one.`,
+    )
+  }
+
+  const { install } = match
+  logStep('Installed')
+  logInfo(`${install.id} ${install.version}`)
+
+  logStep('Updating')
+  const result = await execa('claude', ['plugin', 'update', install.id, '-y'], {
+    reject: false,
+    timeout: PLUGIN_UPDATE_TIMEOUT_MS,
+    env: gitEnv(),
+    extendEnv: false,
+  })
+
+  if (result.exitCode !== 0) {
+    return refusePluginUpdate(
+      opts,
+      'update-failed',
+      `\`claude plugin update ${install.id} -y\` exited ${result.exitCode}. ${(result.stderr || result.stdout).trim()}`,
+      install.id,
+      install.version,
+    )
+  }
+
+  const after = await listPluginInstalls()
+  if (after.kind !== 'ok') {
+    return refusePluginUpdate(
+      opts,
+      'after-list-failed',
+      '`claude plugin update` ran, but `claude plugin list --json` failed to read the version back.',
+      install.id,
+      install.version,
+    )
+  }
+
+  const afterVersion =
+    after.installs.find((row) => row.id === install.id)?.version ??
+    install.version
+  const state = afterVersion === install.version ? 'current' : 'updated'
+
+  logStep('Installed')
+  logInfo(
+    afterVersion === install.version
+      ? `${afterVersion}, unchanged`
+      : `${install.version} to ${afterVersion}`,
+  )
+  outro()
+
+  emitPluginUpdate(opts, {
+    root: PROJECT_ROOT,
+    id: install.id,
+    before: install.version,
+    after: afterVersion,
+    state,
+    message: updatedMessage(install.version, afterVersion),
+  })
+  return 0
+}
+
+type ListInstallsResult =
+  | { readonly kind: 'ok'; readonly installs: readonly PluginInstall[] }
+  | { readonly kind: 'missing' }
+  | { readonly kind: 'failed'; readonly detail: string }
+
+/**
+ * `missing` separates a `claude` binary that is not on PATH from every other
+ * failure, since only that condition is permanent enough for the hook to
+ * silence forever. execa reports it as `ENOENT` on the result rather than by
+ * throwing, because the call runs with `reject: false`.
+ */
+async function listPluginInstalls(): Promise<ListInstallsResult> {
+  const result = await execa('claude', ['plugin', 'list', '--json'], {
+    reject: false,
+    timeout: PLUGIN_LIST_TIMEOUT_MS,
+    env: gitEnv(),
+    extendEnv: false,
+  })
+
+  if (result.code === 'ENOENT') return { kind: 'missing' }
+  if (result.exitCode !== 0) {
+    return { kind: 'failed', detail: (result.stderr || result.stdout).trim() }
+  }
+
+  try {
+    return {
+      kind: 'ok',
+      installs: JSON.parse(result.stdout) as readonly PluginInstall[],
+    }
+  } catch {
+    return {
+      kind: 'failed',
+      detail: '`claude plugin list --json` did not print valid JSON.',
+    }
+  }
+}
+
+function refusePluginUpdate(
+  opts: PluginUpdateOptions,
+  reason: PluginUpdateReason,
+  message: string,
+  id?: string,
+  before?: string,
+): number {
+  outro()
+  frameError(message)
+  emitPluginUpdate(opts, {
+    root: PROJECT_ROOT,
+    ...(id === undefined ? {} : { id }),
+    ...(before === undefined ? {} : { before }),
+    state: 'refused',
+    reason,
+    message,
+  })
+  return 1
+}
+
+function emitPluginUpdate(
+  opts: PluginUpdateOptions,
+  record: PluginUpdateRecord,
+): void {
+  if (opts.json !== true) return
+  process.stdout.write(
+    `${JSON.stringify({ ...record, message: singleLine(record.message) })}\n`,
+  )
+}
+
 /** What a reader does about the one way the corpus fails to build. */
 const REACH_REFUSALS: Record<ReachRefusal, string> = {
   'no-skills':

package/src/commands/feedback.ts

@@ -7,11 +7,11 @@ import {
   missingField,
   missingFieldMessage,
 } from '@/commands/feedback-format'
-import { PROJECT_ROOT } from '@/project-root'
+import { checkoutMismatchWarning, PROJECT_ROOT } from '@/project-root'
 import { creationRel } from '@/record-root'
 import { createGithubIssue } from '@/github'
 import { issueFailureMessage } from '@/github-format'
-import { frameError, frameSuccess, palette } from '@/ui'
+import { frameError, frameSuccess, logWarn, palette } from '@/ui'
 
 function readStdin(): Promise<string> {
   return new Promise((resolveStream, rejectStream) => {
@@ -45,7 +45,7 @@ function isToolkitSource(): boolean {
  * hand, so each writes under its own name and the enclosing folder keeps the
  * single ignore entry and the single backed-folder entry it already had.
  */
-function writeLocal(body: string): string {
+function writeLocal(body: string, mismatch: string | undefined): string {
   // Resolved against the same root the write joins onto, so a checkout that has
   // not migrated its records writes this beside the ones already there rather
   // than opening a second root nothing reads.
@@ -55,7 +55,16 @@ function writeLocal(body: string): string {
   const filename = `feedback-${deriveSlug(body)}-${timestamp()}.md`
   const filePath = join(reviewDir, filename)
   writeFileSync(filePath, `${body}\n`, 'utf8')
-  frameSuccess('canon feedback', join(relativeDir, filename))
+
+  // Manual frame rather than `frameSuccess`, since the mismatch warning is a
+  // frame-interior line landing between the opener and the command title,
+  // matching the convention `#1587` set at its other six sites.
+  const { GREEN, GREY, NC, WHITE } = palette(process.stderr)
+  process.stderr.write(`${GREY}┌${NC}\n`)
+  if (mismatch !== undefined) logWarn(mismatch)
+  process.stderr.write(
+    `${GREY}│${NC} ${WHITE}canon feedback${NC}\n${GREY}│${NC}\n${GREY}│${NC} ${GREEN}✓${NC} ${join(relativeDir, filename)}\n${GREY}└${NC}\n`,
+  )
   return filePath
 }
 
@@ -124,7 +133,8 @@ export function register(program: Command): void {
         return
       }
 
-      const filePath = writeLocal(body)
+      const mismatch = checkoutMismatchWarning(process.cwd())
+      const filePath = writeLocal(body, mismatch)
       process.stdout.write(`${filePath}\n`)
     })
 }

package/src/commands/gate.ts

@@ -12,7 +12,7 @@ import {
   summarize,
 } from '@/gate/sequencer'
 import { STAGES } from '@/gate/stages'
-import { PROJECT_ROOT } from '@/project-root'
+import { checkoutMismatchWarning, PROJECT_ROOT } from '@/project-root'
 import {
   intro,
   logError,
@@ -89,6 +89,7 @@ export function register(program: Command): void {
 
 async function runGate(opts: RunCommandOptions): Promise<number> {
   const root = PROJECT_ROOT
+  const mismatch = checkoutMismatchWarning(process.cwd())
   const emitJson = opts.json ?? false
   const nested = opts.nested ?? false
   const write = opts.write ?? true
@@ -102,6 +103,7 @@ async function runGate(opts: RunCommandOptions): Promise<number> {
     ? { scoped: false, files: [] }
     : await collectChangedFiles(run)
   if (!emitJson && changed.notice !== undefined) logWarn(changed.notice)
+  if (mismatch !== undefined) logWarn(mismatch)
 
   const ctx: GateContext = {
     root,