@erclx/canon 5.62.0 → 5.64.0

package/src/commands/context.ts

@@ -30,26 +30,6 @@ import {
   type ShapeIssue,
 } from '@/context/audit'
 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,
@@ -159,411 +139,6 @@ 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 three: ${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',
-        '',
-      ].join('\n'),
-    )
-    .action(async (path: string | undefined, opts: ClassifyDiffOptions) => {
-      process.exitCode = await runClassifyDiff(path, opts)
-    })
-
-  classify
-    .command('sweep')
-    .description(
-      'Classify every section of the three 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 three: ${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/tooling.ts

@@ -258,7 +258,7 @@ export function register(program: Command): void {
         'never overwrites one.',
         '',
         'Examples:',
-        '  canon tooling customize e2e/home.spec.ts',
+        '  canon tooling customize e2e/screenshot.ts',
         '',
       ].join('\n'),
     )
@@ -1014,6 +1014,9 @@ function reportPackage(result: ScanResult): void {
     logStep('Scanning dependencies')
     for (const entry of result.deps) {
       if (entry.state === 'present') logInfo(entry.name)
+      if (entry.state === 'ahead') {
+        logInfo(`${entry.name} ${entry.installed} (ahead of ${entry.spec})`)
+      }
     }
     for (const entry of result.deps) {
       if (entry.state === 'missing') logAdd(entry.spec)

package/src/context/citations.ts

@@ -1,9 +1,10 @@
 import { existsSync } from 'node:fs'
 import { readFile } from 'node:fs/promises'
-import { resolve } from 'node:path'
+import { relative, resolve } from 'node:path'
 import { listRepositoryFiles } from '@/git/files'
 import { RECORD_ROOTS } from '@/roots/record'
 import { SURFACE_ROOTS } from '@/roots/surface'
+import { stampPaths } from '@/sync/stamp'
 
 /**
  * Suppresses citation checking for the source line carrying it.
@@ -191,7 +192,11 @@ export type CitationReport =
   | { readonly kind: 'unavailable' }
 
 /**
- * Resolves every cited path outside the fixture trees.
+ * Resolves every cited path outside the fixture trees and the install stamp.
+ *
+ * The stamp is written by the toolkit, and `canon tooling decline` records the
+ * declined path as a key in it, so scanning it reports a deliberate decline as
+ * a stale citation.
  *
  * This is the only check that gates the repository check, which makes it the
  * only one whose false positives cost a contributor anything. It reports a
@@ -206,7 +211,8 @@ export async function auditCitations(
   const listed = await listRepositoryFiles(root)
   if (!listed) return { kind: 'unavailable' }
 
-  const candidates = listed.filter((rel) => !isFixture(rel))
+  const stamps = new Set(stampPaths(root).map((path) => relative(root, path)))
+  const candidates = listed.filter((rel) => !isFixture(rel) && !stamps.has(rel))
   const citations: Citation[] = []
 
   for (const rel of candidates) {

package/src/gate/measures.ts

@@ -12,6 +12,7 @@ import {
   auditSkills,
   LEDGER_SKILLS,
   PRACTICE_LEDGER,
+  SKILL_LEDGERS,
   PRACTICE_SKILLS,
   SHIPPED_CORPUS,
 } from '@/claude/skills-audit'
@@ -384,7 +385,7 @@ export const skillProvenance: Measure = async (ctx) => {
 
 /**
  * Every listed practice skill against the closing sections, and every skill on
- * the wider ledger list against the ledger, both of which
+ * the wider ledger list against a ledger that cites something, both of which
  * `claude/skills/create-skill/references/skill-practice.md` requires.
  *
  * Read in-process for the reason `skillProvenance` is, so the verb keeps its
@@ -407,14 +408,14 @@ export const skillPracticeShape: Measure = async (ctx) => {
       .join(', ')
     return {
       emissions: [],
-      failure: `${plural(found.length, 'practice shape finding')}: ${where}. Add the closing H2 exactly as named to a practice skill, or the ledger at ${PRACTICE_LEDGER} to any skill on the ledger list.`,
+      failure: `${plural(found.length, 'practice shape finding')}: ${where}. Add the closing H2 exactly as named to a practice skill, or the ledger at ${PRACTICE_LEDGER} to any skill on the ledger list, citing one linked source or one House choice row. A reference of a skill on the per-bullet list, unless exempted, takes one ledger row per bullet under the same H2 at ${SKILL_LEDGERS}.`,
     }
   }
 
   return {
     emissions: [
       info(
-        `${plural(PRACTICE_SKILLS.length, 'practice skill')} carry every closing section, and ${plural(LEDGER_SKILLS.length, 'listed skill')} carry a ledger`,
+        `${plural(PRACTICE_SKILLS.length, 'practice skill')} carry every closing section, and ${plural(LEDGER_SKILLS.length, 'listed skill')} carry a ledger citing a source`,
       ),
     ],
   }

package/src/git/files.ts

@@ -140,7 +140,9 @@ export async function listIgnoreAdditions(
 /**
  * Lists the files under `root`: tracked, plus untracked files git does not
  * ignore. The untracked half is what keeps a file added on this branch in scope
- * rather than one push later.
+ * rather than one push later. A tracked path deleted in the working tree is
+ * left out, since a caller reading the listing would otherwise open a file that
+ * is gone.
  *
  * Returns undefined when git cannot answer, which every caller reports rather
  * than smoothing into an empty list. An empty list passes each of its zero
@@ -161,9 +163,12 @@ export async function listRepositoryFiles(
 
   const tracked = await run(['ls-files'])
   const untracked = await run(['ls-files', '--others', '--exclude-standard'])
-  if (!tracked || !untracked) return undefined
+  const deleted = await run(['ls-files', '--deleted'])
+  if (!tracked || !untracked || !deleted) return undefined
 
-  return [...new Set([...tracked, ...untracked])].sort()
+  const gone = new Set(deleted)
+  const present = tracked.filter((path) => !gone.has(path))
+  return [...new Set([...present, ...untracked])].sort()
 }
 
 /**

package/src/gov/audit.ts

@@ -294,7 +294,12 @@ export function countLedgerRows(text: string): HeadingCount[] {
   return [...counts].map(([key, count]) => ({ heading: key, count }))
 }
 
-function compareLedger(
+/**
+ * Pairs bullets and ledger rows under each heading, naming every heading whose
+ * counts differ. The skill audit reads a practice skill's references through
+ * it, so a rule and a reference are held to one comparison.
+ */
+export function compareLedger(
   groups: readonly HeadingCount[],
   rows: readonly HeadingCount[],
 ): LedgerMismatch[] {

package/src/inventory/subjects.ts

@@ -27,7 +27,7 @@ export interface Subject {
 
 /**
  * Reports what each element changes about itself when it takes focus, which is
- * the reading `governance/rules/ui/keyboard.md` states three rules against and
+ * the reading the `ui-craft` keyboard reference states three rules against and
  * nothing measures.
  *
  * The difference between rest and focus is the treatment, rather than the

package/src/markdown/gated.ts

@@ -120,7 +120,7 @@ export function appendGatedPrefix(
   return 'appended'
 }
 
-/** Written by hand rather than serialized, the way `classifier.toml` is. */
+/** Written by hand rather than serialized, so the list keeps its one-entry-per-line form. */
 function writeGatedList(root: string, prefixes: readonly string[]): void {
   const path = join(root, GATED_CONFIG_REL)
   const mode = existsSync(path) ? statSync(path).mode : undefined

package/src/markdown/scope.ts

@@ -154,7 +154,6 @@ export const GATED_PATHS: readonly string[] = [
   'claude/skills/codebase-layout/references/tests.md',
   'claude/skills/context-fold/REQUIREMENT.md',
   'claude/skills/context-fold/SKILL.md',
-  'claude/skills/context-fold/references/classify.md',
   'claude/skills/context-fold/references/completion-report.md',
   'claude/skills/context-fold/references/context-refresh.md',
   'claude/skills/context-fold/references/context.md',

package/src/tooling/package.ts

@@ -17,7 +17,9 @@ export interface ScriptState {
 export interface DepState {
   readonly spec: string
   readonly name: string
-  readonly state: 'missing' | 'present'
+  readonly state: 'missing' | 'present' | 'ahead'
+  /** The spec the target records, set only when it is `ahead` of the pin. */
+  readonly installed?: string
 }
 
 export function readPackage(path: string): PackageJson | undefined {
@@ -89,18 +91,24 @@ function firstInteger(value: string): string | undefined {
 
 /**
  * Compares a manifest pin against what package.json records. A spec counts as
- * missing when absent, or when the pinned major differs from the installed
- * major. Anything looser than a major mismatch is left alone.
+ * missing when absent or on an earlier major than the pin, and ahead when it
+ * sits on a later one, which a write leaves alone. A spec with no integer to
+ * compare, such as `latest` or `workspace:*`, counts as present.
  */
-function isSatisfied(installed: string | undefined, pin: string): boolean {
-  if (installed === undefined) return false
-  if (pin === '') return true
+function compareSpec(
+  installed: string | undefined,
+  pin: string,
+): DepState['state'] {
+  if (installed === undefined) return 'missing'
+  if (pin === '') return 'present'
 
   const pinMajor = firstInteger(pin)
   const installedMajor = firstInteger(installed)
-  if (pinMajor === undefined) return true
+  if (pinMajor === undefined || installedMajor === undefined) return 'present'
 
-  return pinMajor === installedMajor
+  const delta = Number(installedMajor) - Number(pinMajor)
+  if (delta === 0) return 'present'
+  return delta > 0 ? 'ahead' : 'missing'
 }
 
 /**
@@ -121,11 +129,12 @@ export function collectDeps(
       if (name === '' || seen.has(name)) continue
       seen.add(name)
 
-      states.push({
-        spec,
-        name,
-        state: isSatisfied(installed[name], pin) ? 'present' : 'missing',
-      })
+      const state = compareSpec(installed[name], pin)
+      states.push(
+        state === 'ahead'
+          ? { spec, name, state, installed: installed[name] }
+          : { spec, name, state },
+      )
     }
   }
 

package/tooling/web/reference.md

@@ -45,6 +45,8 @@ The web layer covers the tooling shared across Vite + React, Astro, and Next.js.
 
 ## Screenshot cases
 
+The starter `e2e/home.spec.ts` is seeded once. Sync copies it into a project that has none and leaves it alone after, so grow it freely.
+
 - Edit the `CASES` in the seeded `e2e/capture/cases.ts`, one entry per output file naming a section, a theme, and a route, since sync overwrites the `e2e/screenshot.ts` harness
 - Move cases from `e2e/screenshot.ts` to `e2e/capture/cases.ts` before a sync, and set `EVIDENCE_ROOT = 'evidence'` to keep an existing baseline
 - Expect each case crossed with `VIEWPORTS`, written to `screenshots/<hostname>/<section>/<width>--<theme>.png`, so local and deployed runs stay apart
@@ -76,7 +78,7 @@ The web layer covers the tooling shared across Vite + React, Astro, and Next.js.
 
 - Expect the sweep under `screenshots/` to be ignored and only a flagged case's `EVIDENCE_ROOT` output tracked, so a target's first capture is the baseline it commits
 - Size a case's `sections` list against the frames each later change regenerates, since a case naming sections commits a folder per section
-- Run the capture after a surface changes, component files included, per `governance/rules/ui/surface-capture.md`, unless the production build strips the component out
+- Run the capture after a surface changes, component files included, per the `ui-craft` skill's capture reference, unless the production build strips the component out
 
 ## Screenshot scripts and workflows