@erclx/canon 4.81.0 → 4.83.0

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,
@@ -39,6 +59,10 @@ import {
   PRONOUN_HEADING,
   VERB_HEADING,
 } from '@/context/narration'
+import {
+  measureWireframeFolder,
+  type WireframeStatesReport,
+} from '@/context/wireframe-states'
 import { RENDER_WIDTH } from '@/markdown/structure'
 import {
   frameError,
@@ -74,7 +98,7 @@ export function register(program: Command): void {
   context
     .command('audit')
     .description(
-      'Report required sections, entry length, citations, reference form, catalog tables, provenance, superseded-decision narration, index drift, and the architecture record against its own ceiling',
+      'Report required sections, entry length, citations, reference form, catalog tables, provenance, superseded-decision narration, index drift, the architecture record against its own ceiling and its word weight, and wireframe states against their evidence folders',
     )
     .argument('[path]', 'Project root, defaulting to the current directory')
     .helpOption('-h, --help', 'Show this help message')
@@ -122,6 +146,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 {
@@ -237,6 +666,15 @@ async function runAudit(
   // are different answers, and one value for both reports the second as the
   // first.
   const record = gateOnly ? undefined : await measureArchitecture(root)
+  const wireframes = gateOnly
+    ? []
+    : (
+        await Promise.all(
+          folders
+            .filter((folder) => folder.name === 'wireframes')
+            .map((folder) => measureWireframeFolder(root, folder)),
+        )
+      ).flat()
 
   if (gateOnly) {
     reportGate(citations)
@@ -252,6 +690,7 @@ async function runAudit(
     reportNarration(entries, folders, narration)
     reportDrift(drift)
     reportRecord(record, root)
+    reportWireframeStates(wireframes)
     outro()
   }
 
@@ -288,6 +727,11 @@ async function runAudit(
         // target that never wrote one is entitled to. Absent says the run
         // never looked, which is `--citations-only`.
         architecture: gateOnly ? undefined : (record ?? null),
+        // Absent under `--citations-only`, for the same reason as above. An
+        // empty array under the ordinary run says the project carries no
+        // wireframes folder or no entry carrying a States table, which is a
+        // fact rather than an unmeasured run.
+        wireframes: gateOnly ? undefined : wireframes,
         checkpoints: {
           lines: LENGTH_CHECKPOINT,
           renderWidth: RENDER_WIDTH,
@@ -317,6 +761,7 @@ async function runAudit(
     recordOverLength: record !== undefined && isOverLength(record),
     sections,
     drift,
+    wireframes,
     widened,
   })
 
@@ -777,6 +1222,15 @@ function reportRecord(
   const decisions = report.decisions.length
   const { allowances } = report
 
+  logInfo(
+    `${plural(report.words, 'word')} across ${plural(report.lines, 'line')}, read alongside the weight judgment a session makes by reading the file. This never gates.`,
+  )
+  if (report.risksWords !== undefined) {
+    logInfo(
+      `\`## Risks / open questions\` holds ${plural(report.risksWords, 'word')}, weighed the same way and read alongside the same judgment.`,
+    )
+  }
+
   if (allowances === undefined) {
     logInfo(
       `Covers ${report.rel} alone. No standard sets a length rule for it and this record states none, so its ${plural(report.lines, 'line')} across ${plural(decisions, 'decision')} are reported and nothing is gated.`,
@@ -836,7 +1290,7 @@ function reportRecord(
           entry.checks.length > 0
             ? `\n  checked by ${entry.checks.join(', ')}`
             : ''
-        return `${report.rel}:${entry.line}  ${kind}${evidence}\n  ${entry.heading}${checks}`
+        return `${report.rel}:${entry.line}  ${kind}${evidence}  ${plural(entry.words, 'word')}\n  ${entry.heading}${checks}`
       })
       .join('\n'),
   )
@@ -858,3 +1312,43 @@ function reportDrift(drift: readonly FolderDrift[]): void {
   logWarn(plural(lines.length, 'disagreement'))
   pipeOutput(lines.join('\n'))
 }
+
+function reportWireframeStates(
+  wireframes: readonly WireframeStatesReport[],
+): void {
+  logStep('Wireframe states')
+
+  const withRows = wireframes.filter((entry) => entry.rows.length > 0)
+  if (withRows.length === 0) {
+    logInfo(
+      'No wireframe carries a States table, so nothing was checked against its evidence folders.',
+    )
+    return
+  }
+
+  const lines = withRows.flatMap((entry) => [
+    ...entry.missingFolders.map(
+      (finding) =>
+        `${entry.rel}:${finding.line}  ${finding.state}  no folder at ${finding.path}`,
+    ),
+    ...entry.unlistedFolders.map(
+      (finding) =>
+        `${entry.rel}  ${finding.root}/${finding.folder}  named in no row`,
+    ),
+    ...(entry.sketchWithEvidence
+      ? [
+          `${entry.rel}:${entry.sketchLine}  a plaintext sketch sits beside evidence that already exists`,
+        ]
+      : []),
+  ])
+
+  if (lines.length === 0) {
+    logInfo(
+      `${plural(withRows.length, 'wireframe')} checked, every state matched one-to-one with its evidence folder.`,
+    )
+    return
+  }
+
+  logWarn(plural(lines.length, 'finding'))
+  pipeOutput(lines.join('\n'))
+}