@erclx/canon 4.80.0 → 4.82.0

package/src/claude/cases/misc.ts

@@ -17,6 +17,11 @@ export const MISC_CASES: readonly SkillCase[] = [
       'This project has no logo yet. Draft one and give me a social card to go with it.',
     expect: 'draft-identity',
   },
+  {
+    prompt:
+      "I found two sites whose look I want us to draw from. Put them side by side and let's settle which one the design should follow before anyone writes a token.",
+    expect: 'sketch-design',
+  },
   {
     prompt: 'Fire up the dev server the way this project documents it.',
     expect: 'project-commands',

package/src/claude/seeds.ts

@@ -20,6 +20,7 @@ const HOOKS = 'hooks'
 export const SUBDIRS: readonly string[] = [
   HOOKS,
   'context',
+  'decisions',
   'diagrams',
   'memory',
   'tasks',

package/src/commands/claude.ts

@@ -61,6 +61,7 @@ import { copyPreservingMode } from '@/copy'
 import { execScript } from '@/exec'
 import { checkoutMismatchWarning, PROJECT_ROOT } from '@/project-root'
 import { recordDir } from '@/record-root'
+import { SURFACE_ENTRIES, surfaceDir } from '@/surface-root'
 import { isDirectory, resolveTarget } from '@/target'
 import { injectGitignore, pruneGitignore } from '@/tooling/inject'
 import {
@@ -148,7 +149,27 @@ const SEEDED_FILES: readonly string[] = [
   'REQUIREMENTS.md',
   'DESIGN.md',
 ]
-const SEEDED_DIRS: readonly string[] = ['memory', 'tasks', 'wireframes']
+const SEEDED_DIRS: readonly string[] = [
+  'decisions',
+  'memory',
+  'tasks',
+  'wireframes',
+]
+
+/**
+ * Where a `SEEDED_DIRS` entry resolves for the sync presence check.
+ *
+ * `wireframes` and `decisions` are tracked surface entries, resolved under
+ * `canon/` ahead of `.claude/`, while `memory` and `tasks` are session records
+ * resolved under `.canon/` ahead of `.claude/`. Routing every name through
+ * `recordDir` reported a migrated target's `canon/wireframes/` or
+ * `canon/decisions/` as missing, since that resolver never checks `canon/`.
+ */
+export function seededDirPath(resolved: string, name: string): string {
+  return SURFACE_ENTRIES.includes(name)
+    ? surfaceDir(resolved, name)
+    : recordDir(resolved, name)
+}
 const USER_DIR = join('tooling', 'claude', 'user')
 const STATUSLINE = 'statusline-command.sh'
 const PLUGIN_MANIFEST = join('claude', '.claude-plugin', 'plugin.json')
@@ -580,16 +601,16 @@ async function runSync(target: string): Promise<number> {
 
   // A record folder resolves at either root, so a migrated target is reported as
   // seeded rather than sent to `canon claude init` to re-create records it
-  // already holds. The three seeded files and `wireframes` are tracked and stay
-  // at `.claude/`, which the resolver answers for them anyway, since nothing
-  // ever creates a second root copy for a name that does not move.
+  // already holds. `wireframes` and `decisions` are tracked surface entries
+  // instead, resolved through `surfaceDir`, since a migrated target holds them
+  // at `canon/` rather than under either record root.
   logStep('Seeded')
   for (const name of SEEDED_FILES) {
     if (existsSync(join(resolved, '.claude', name))) logInfo(name)
     else logWarn(`${name} missing. Run \`canon claude init\``)
   }
   for (const name of SEEDED_DIRS) {
-    if (isDirectory(recordDir(resolved, name))) logInfo(`${name}/`)
+    if (isDirectory(seededDirPath(resolved, name))) logInfo(`${name}/`)
     else logWarn(`${name}/ missing. Run \`canon claude init\``)
   }
 

package/src/commands/context.ts

@@ -25,6 +25,26 @@ import {
   testableCount,
 } from '@/context/architecture'
 import { auditCitations, type CitationReport } from '@/context/citations'
+import {
+  CANONICAL_DOC_TYPES,
+  type CanonicalDocType,
+} from '@/context/classify/extract'
+import {
+  classifyDiff,
+  classifySweep,
+  type ClassifyOutcome,
+  type ClassifyRefusal,
+  type DiffFinding,
+  type DiffRecord,
+  type SweepFinding,
+  type SweepRecord,
+} from '@/context/classify/run'
+import {
+  CLASSIFIER_CONFIG_REL,
+  type ClassifierBackend,
+  resolveClassifier,
+  writeClassifierConfig,
+} from '@/context/classify/settings'
 import {
   type AuditedFolder,
   DEFAULT_FOLDERS,
@@ -122,6 +142,411 @@ export function register(program: Command): void {
     .action(async (path: string | undefined, opts: AuditCommandOptions) => {
       process.exitCode = await runAudit(path, opts)
     })
+
+  const classify = context
+    .command('classify')
+    .description(
+      'Classify canonical-doc content as keep, replace/rewrite, history, or move',
+    )
+    .helpOption('-h, --help', 'Show this help message')
+
+  classify
+    .command('diff')
+    .description(
+      'Classify the chunks a git range changed, each with the section it landed in',
+    )
+    .argument('[path]', 'Project root, defaulting to the current directory')
+    .helpOption('-h, --help', 'Show this help message')
+    .option('--base <ref>', 'Far side of the range, defaulting to the trunk')
+    .option(
+      '--doc-types <list>',
+      `Comma-separated canonical doc types (default: all five: ${CANONICAL_DOC_TYPES.join(', ')})`,
+    )
+    .option(
+      '--backend <name>',
+      'Override the resolved model backend for this run',
+    )
+    .option('--model <name>', 'Override the resolved model name for this run')
+    .option('--json', 'Add a machine-readable record on stdout')
+    .addHelpText(
+      'after',
+      [
+        '',
+        'The regex layer always runs. The model layer runs only when a',
+        'backend resolves through `canon context classifier show`, and a',
+        'configured-but-unreachable backend warns and falls back to regex',
+        'rather than failing the run.',
+        '',
+        'Exit codes:',
+        '  0  the run completed, whatever the findings say',
+        '  1  refused: a bad range or a file this could not read',
+        '',
+        'Examples:',
+        '  canon context classify diff',
+        '  canon context classify diff --base origin/main --json',
+        '  canon context classify diff --doc-types context,wireframes',
+        '',
+      ].join('\n'),
+    )
+    .action(async (path: string | undefined, opts: ClassifyDiffOptions) => {
+      process.exitCode = await runClassifyDiff(path, opts)
+    })
+
+  classify
+    .command('sweep')
+    .description(
+      'Classify every section of the five canonical doc types, split at H3',
+    )
+    .argument('[path]', 'Project root, defaulting to the current directory')
+    .helpOption('-h, --help', 'Show this help message')
+    .option(
+      '--doc-types <list>',
+      `Comma-separated canonical doc types (default: all five: ${CANONICAL_DOC_TYPES.join(', ')})`,
+    )
+    .option(
+      '--backend <name>',
+      'Override the resolved model backend for this run',
+    )
+    .option('--model <name>', 'Override the resolved model name for this run')
+    .option('--json', 'Add a machine-readable record on stdout')
+    .addHelpText(
+      'after',
+      [
+        '',
+        'Exit codes:',
+        '  0  the run completed, whatever the findings say',
+        '  1  refused: a file this could not read',
+        '',
+        'Examples:',
+        '  canon context classify sweep',
+        '  canon context classify sweep --doc-types design,requirements --json',
+        '',
+      ].join('\n'),
+    )
+    .action(async (path: string | undefined, opts: ClassifySweepOptions) => {
+      process.exitCode = await runClassifySweep(path, opts)
+    })
+
+  const classifier = context
+    .command('classifier')
+    .description('Read or write the project classifier setting')
+    .helpOption('-h, --help', 'Show this help message')
+
+  classifier
+    .command('show')
+    .description(
+      'Report the backend and model that would run, and which source decided it',
+    )
+    .argument('[path]', 'Project root, defaulting to the current directory')
+    .helpOption('-h, --help', 'Show this help message')
+    .option('--json', 'Add a machine-readable record on stdout')
+    .action((path: string | undefined, opts: { json?: boolean }) => {
+      runClassifierShow(path, opts)
+    })
+
+  classifier
+    .command('set')
+    .description('Write the project classifier setting')
+    .argument('[path]', 'Project root, defaulting to the current directory')
+    .helpOption('-h, --help', 'Show this help message')
+    .requiredOption('--backend <name>', 'ollama or off')
+    .option('--model <name>', 'Model name, required when --backend is ollama')
+    .option('--json', 'Add a machine-readable record on stdout')
+    .action((path: string | undefined, opts: ClassifierSetOptions) => {
+      process.exitCode = runClassifierSet(path, opts)
+    })
+}
+
+interface ClassifyDiffOptions {
+  readonly json?: boolean
+  readonly base?: string
+  readonly docTypes?: string
+  readonly backend?: string
+  readonly model?: string
+}
+
+interface ClassifySweepOptions {
+  readonly json?: boolean
+  readonly docTypes?: string
+  readonly backend?: string
+  readonly model?: string
+}
+
+interface ClassifierSetOptions {
+  readonly json?: boolean
+  readonly backend: string
+  readonly model?: string
+}
+
+function parseDocTypes(
+  list: string | undefined,
+): readonly CanonicalDocType[] | string {
+  if (!list) return CANONICAL_DOC_TYPES
+
+  const names = list
+    .split(',')
+    .map((name) => name.trim())
+    .filter(Boolean)
+
+  const invalid = names.filter(
+    (name) => !CANONICAL_DOC_TYPES.includes(name as CanonicalDocType),
+  )
+  if (invalid.length > 0) {
+    return `--doc-types takes ${CANONICAL_DOC_TYPES.join(', ')}: ${invalid.join(', ')}`
+  }
+
+  return names as CanonicalDocType[]
+}
+
+/**
+ * Validates `--backend` up front, so a typo'd value refuses rather than
+ * falling through `resolveBackend`'s tier chain to the environment, the
+ * file, or the default, which reads as the flag having been ignored.
+ */
+function parseBackendFlag(value: string | undefined): string | undefined {
+  if (value === undefined || value === 'ollama' || value === 'off') {
+    return undefined
+  }
+  return `--backend takes ollama or off: ${value}`
+}
+
+/** Widens the extraction refusals with the CLI's own argument-parsing failure. */
+type CliRefusal = ClassifyRefusal | 'bad-flags'
+
+function refuseClassify(
+  reason: CliRefusal,
+  message: string,
+  emitJson: boolean,
+): number {
+  intro('canon context classify')
+  logStep('Refused')
+  logWarn(message)
+  outro()
+
+  if (emitJson) {
+    process.stdout.write(
+      `${JSON.stringify({ decision: 'refused', reason, message })}\n`,
+    )
+  }
+  return 1
+}
+
+/** How each not-off model-layer state reads in the report. */
+const MODEL_LAYER_LABEL: Record<string, string> = {
+  ran: 'ran',
+  'skipped-no-model': 'skipped, no model resolved for the configured backend',
+  'skipped-unreachable': 'skipped, the configured backend did not answer',
+}
+
+function reportLayers(record: DiffRecord | SweepRecord): void {
+  logStep('Layers')
+  logInfo('regex: ran')
+
+  if (record.modelLayer === 'off') {
+    logInfo('model: off, no backend configured')
+    return
+  }
+
+  logInfo(
+    `model: ${MODEL_LAYER_LABEL[record.modelLayer]} (${record.backend ?? 'none'}${record.model ? `, ${record.model}` : ''})`,
+  )
+  if (record.modelLayer !== 'ran') {
+    logWarn('Falling back to the regex layer alone for this run.')
+  }
+}
+
+function reportFindings(
+  findings: readonly (DiffFinding | SweepFinding)[],
+  label: (finding: DiffFinding | SweepFinding) => string,
+): void {
+  logStep('Findings')
+
+  if (findings.length === 0) {
+    logInfo('Nothing met the extraction floor under the requested doc types.')
+    return
+  }
+
+  const flagged = findings.filter((finding) => finding.verdict !== 'KEEP')
+  logInfo(
+    `${plural(findings.length, 'item')} read, ${plural(flagged.length, 'flagged')}`,
+  )
+
+  if (flagged.length === 0) return
+
+  pipeOutput(
+    flagged
+      .map((finding) => {
+        const chosen =
+          finding.decidedBy === 'model' ? finding.model : finding.regex
+        return `${label(finding)}  ${finding.verdict} (${finding.decidedBy})\n  ${chosen?.quote ? `"${chosen.quote}"  ` : ''}${chosen?.reason ?? ''}`
+      })
+      .join('\n'),
+  )
+}
+
+async function runClassifyDiff(
+  path: string | undefined,
+  opts: ClassifyDiffOptions,
+): Promise<number> {
+  const root = resolve(path ?? process.cwd())
+  const emitJson = opts.json ?? false
+
+  const docTypes = parseDocTypes(opts.docTypes)
+  if (typeof docTypes === 'string') {
+    return refuseClassify('bad-flags', docTypes, emitJson)
+  }
+
+  const backendError = parseBackendFlag(opts.backend)
+  if (backendError !== undefined) {
+    return refuseClassify('bad-flags', backendError, emitJson)
+  }
+
+  const result: ClassifyOutcome<DiffRecord> = await classifyDiff(
+    root,
+    opts.base,
+    {
+      docTypes,
+      flags: { backend: opts.backend, model: opts.model },
+    },
+  )
+
+  if (result.kind === 'refused') {
+    return refuseClassify(result.reason, result.message, emitJson)
+  }
+
+  intro('canon context classify diff')
+  reportLayers(result.record)
+  reportFindings(result.record.findings, (finding) => finding.file)
+  outro()
+
+  if (emitJson) {
+    process.stdout.write(
+      `${JSON.stringify({ decision: 'ok', ...result.record })}\n`,
+    )
+  }
+
+  return 0
+}
+
+async function runClassifySweep(
+  path: string | undefined,
+  opts: ClassifySweepOptions,
+): Promise<number> {
+  const root = resolve(path ?? process.cwd())
+  const emitJson = opts.json ?? false
+
+  const docTypes = parseDocTypes(opts.docTypes)
+  if (typeof docTypes === 'string') {
+    return refuseClassify('bad-flags', docTypes, emitJson)
+  }
+
+  const backendError = parseBackendFlag(opts.backend)
+  if (backendError !== undefined) {
+    return refuseClassify('bad-flags', backendError, emitJson)
+  }
+
+  const result: ClassifyOutcome<SweepRecord> = await classifySweep(root, {
+    docTypes,
+    flags: { backend: opts.backend, model: opts.model },
+  })
+
+  if (result.kind === 'refused') {
+    return refuseClassify(result.reason, result.message, emitJson)
+  }
+
+  intro('canon context classify sweep')
+  reportLayers(result.record)
+  reportFindings(
+    result.record.findings,
+    (finding) => `${finding.file}:${(finding as SweepFinding).heading}`,
+  )
+  outro()
+
+  if (emitJson) {
+    process.stdout.write(
+      `${JSON.stringify({ decision: 'ok', ...result.record })}\n`,
+    )
+  }
+
+  return 0
+}
+
+function runClassifierShow(
+  path: string | undefined,
+  opts: { json?: boolean },
+): void {
+  const root = resolve(path ?? process.cwd())
+  const resolution = resolveClassifier(root, {})
+
+  intro('canon context classifier show')
+
+  if (resolution.kind === 'off') {
+    logInfo(
+      `Model layer off (source: ${resolution.source}). Regex layer always runs.`,
+    )
+  } else if (resolution.kind === 'no-model') {
+    logWarn(
+      `Backend ${resolution.backend} configured (source: ${resolution.source}) with no model name. \`classify\` runs regex only.`,
+    )
+  } else {
+    logInfo(
+      `Backend ${resolution.backend}, model ${resolution.model} (source: ${resolution.source}).`,
+    )
+  }
+
+  logInfo(
+    `Reads ${CLASSIFIER_CONFIG_REL} when neither a flag nor an environment variable decides.`,
+  )
+  outro()
+
+  if (opts.json) {
+    process.stdout.write(`${JSON.stringify(resolution)}\n`)
+  }
+}
+
+function runClassifierSet(
+  path: string | undefined,
+  opts: ClassifierSetOptions,
+): number {
+  const root = resolve(path ?? process.cwd())
+  const emitJson = opts.json ?? false
+
+  if (opts.backend !== 'ollama' && opts.backend !== 'off') {
+    return refuseClassify(
+      'bad-flags',
+      '--backend takes ollama or off.',
+      emitJson,
+    )
+  }
+
+  if (opts.backend === 'ollama' && !opts.model) {
+    return refuseClassify(
+      'bad-flags',
+      '--model is required when --backend is ollama.',
+      emitJson,
+    )
+  }
+
+  const backend: ClassifierBackend | 'off' = opts.backend
+  writeClassifierConfig(
+    root,
+    backend,
+    backend === 'off' ? undefined : opts.model,
+  )
+
+  intro('canon context classifier set')
+  logInfo(
+    `Wrote ${CLASSIFIER_CONFIG_REL}: backend ${opts.backend}${opts.model ? `, model ${opts.model}` : ''}.`,
+  )
+  outro()
+
+  if (emitJson) {
+    process.stdout.write(
+      `${JSON.stringify({ decision: 'ok', backend: opts.backend, model: opts.model })}\n`,
+    )
+  }
+
+  return 0
 }
 
 function parseFolders(list: string | undefined): string[] | string {

package/src/commands/design.ts

@@ -11,12 +11,17 @@ import { buildDesignCss } from '@/design/css'
 import { HAND_DRAWN_FONT_FACES } from '@/design/fonts'
 import { renderDesignDoc } from '@/design/render'
 import { DESIGN_BASE_CSS, DESIGN_DOCUMENT, regenDesign } from '@/design/regen'
-import { checkoutMismatchWarning, PROJECT_ROOT } from '@/project-root'
+import {
+  checkoutMismatchWarning,
+  isOwnCheckout,
+  PROJECT_ROOT,
+} from '@/project-root'
 import { creationRel } from '@/record-root'
 import { surfaceDir } from '@/surface-root'
 import { recordStamp, runDomainSync } from '@/sync/engine'
 import { resolveTarget } from '@/target'
 import { intro, logAdd, logError, logInfo, logWarn, outro, palette } from '@/ui'
+import { mainWorktreeRoot } from '@/worktree'
 
 export function register(program: Command): void {
   const design = program
@@ -133,33 +138,44 @@ export function register(program: Command): void {
   design
     .command('board')
     .description(
-      'Generate the design board, an index over this repository’s own design surfaces',
+      'Generate the design board, an index over a project’s design surfaces',
     )
     .option(
       '-o, --out <path>',
       'Output directory',
       creationRel(process.cwd(), 'review', 'board'),
     )
+    .option('--root <path>', 'Project root, defaulting to the main worktree')
     .addHelpText(
       'after',
       [
         '',
-        'Like regen, this runs against the toolkit checkout rather than a',
-        'target: it reads five sources already on disk relative to the',
-        'project root and writes a static page set, never installed or',
-        'synced. Open it with canon serve <out>.',
+        'Reads its sources from --root, defaulting to the main worktree of',
+        'whatever project the caller stands in, and writes a static page',
+        'set, never installed or synced. The surfaces panel’s landing-page',
+        'half and the whole components panel render only when that root is',
+        'this toolkit’s own checkout. Open the result with canon serve <out>.',
         '',
       ].join('\n'),
     )
-    .action((opts: { out: string }) => {
+    .action(async (opts: { out: string; root?: string }) => {
       const outDir = resolve(process.cwd(), opts.out)
+      const root = opts.root
+        ? resolve(process.cwd(), opts.root)
+        : await mainWorktreeRoot()
+      const isToolkitCheckout = isOwnCheckout(root)
       const { GREEN, GREY, NC, RED, WHITE } = palette(process.stderr)
       const mismatch = checkoutMismatchWarning(process.cwd())
       process.stderr.write(
         `${GREY}┌${NC}\n${GREY}│${NC} ${WHITE}Generate design board${NC}\n`,
       )
       if (mismatch !== undefined) logWarn(mismatch)
-      const result = generateBoard(PROJECT_ROOT, outDir, process.cwd())
+      const result = generateBoard(
+        root,
+        outDir,
+        process.cwd(),
+        isToolkitCheckout,
+      )
       if (!result.ok) {
         process.stderr.write(
           `${GREY}│${NC} ${RED}✗${NC} ${result.detail}\n${GREY}└${NC}\n`,