@erclx/canon 5.63.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/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

@@ -408,7 +408,7 @@ 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, citing one linked source or one House choice row. A reference on the per-bullet list takes one ledger row per bullet under the same H2 at ${SKILL_LEDGERS}.`,
+      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}.`,
     }
   }
 

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/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/claude/skills/context-fold/references/classify.md

@@ -1,87 +0,0 @@
----
-title: Classify the fold's diff baseline
-description: The classify diff invocation, the record fields to read, applying a finding, the one-line keep reason, the unreachable and missing-subcommand lines, and the report shape
----
-
-# Classify the fold's diff baseline
-
-Mechanics for the classify half of Step 4 of `context-fold`. The body owns the skip condition and the shared baseline, and this file owns the invocation, what the record carries, and what applying a finding does.
-
-## Invocation
-
-Call the verb rather than reimplementing its pattern or prompt in this skill:
-
-```bash
-canon context classify diff --base <base> --json
-```
-
-Never substitute a different verb for it, such as `canon docs <name>` (a documentation lookup, not a classification).
-
-Reuse the base the Diff baseline section already resolved for Steps 2 and 5 rather than resolving a second time. Never pick or configure a backend here. The project setting decides it, and this step reports `modelLayer` as the record returns it.
-
-## Reading the record
-
-Branch on the record's `decision` field, never on the exit code, which a shell function wrapping `canon` can flatten to zero.
-
-- `decision: 'refused'`: a bad range or a file the verb could not read. Report the record's `message` and continue. See "When the verb is absent or refused" below.
-- `decision: 'ok'`: the record carries `modelLayer` (`'off'`, `'ran'`, `'skipped-no-model'`, or `'skipped-unreachable'`) and `findings`.
-
-Each finding carries `file`, a `verdict` of `KEEP`, `REPLACE`, `HISTORY`, or `MOVE`, and `decidedBy` (`'regex'` or `'model'`) naming which layer's reading won. Take the `quote` and `reason` from whichever of the finding's `regex` or `model` fields `decidedBy` names. Skip every `KEEP` finding: nothing decided against that text.
-
-## Scope
-
-Answer every non-`KEEP` finding the verb returns, not only the files Step 3 wrote this run, since a branch carrying a prior session's commits has doc edits the fold is equally responsible for.
-
-The verb's own extraction already scopes to canonical doc types and reports nothing when the range carries none, so there is no narrower check to add here.
-
-## Applying a finding
-
-Locate the finding by its `quote` in the file's current content. The quote is often a narrow fragment rather than the whole clause it sits in, since the regex layer's own match is a short pattern hit, so the edit below targets the sentence or bullet the quote sits in rather than the literal substring alone.
-
-- **Found exactly once.** Apply the verdict under its heading below.
-- **Found more than once, or not found at all.** Report it as not located rather than guessing an occurrence or silently rewriting nothing. A model paraphrasing its quote is the usual cause.
-
-Run the classifier once per fold. Do not re-run it after applying a finding to check the edit, since a second pass over what this step wrote is the loop the verb's own reference already warns against.
-
-### REPLACE
-
-Rewrite the sentence or bullet carrying the quote in place with the fact that now stands, per Step 3's rewrite-in-place rule. State what is current and drop what the quote restated, in the one edit.
-
-### HISTORY
-
-Rewrite the sentence or bullet carrying the quote to drop the narration and keep any current fact the same clause states. The quote narrates how the fact arrived rather than stating the fact, which a canonical doc excludes regardless of what wrote it.
-
-A literal cut of the fragment alone would leave the rest of the clause grammatically stranded.
-
-### MOVE
-
-Do not cut. The verdict means correct content sits on the wrong surface, such as a rule written into a context entry that belongs in a path-scoped rule, and only the model layer returns it.
-
-Report the finding instead, naming the surface the `reason` names as where the content belongs, and leave the file unedited. Cutting would delete content a fold with no model configured would never have flagged at all.
-
-## Keeping a finding
-
-Keep a non-`KEEP` finding without applying it only when the quote is itself the alternative a nearby decision states and lost, or the file already carries the current fact elsewhere. State the reason in one line in the report. A keep costs one line, where an incorrect apply costs a rewrite of prose nobody asked to change.
-
-## When the verb is absent or refused
-
-The verb ships with the CLI and this skill ships with the plugin, so a target holding an older installed binary carries no `context classify` subcommand. Never read a missing subcommand as a clean pass, which would report a run that never checked anything as one that found nothing.
-
-| Case               | Report, then continue                                                                |
-| ------------------ | ------------------------------------------------------------------------------------ |
-| Subcommand missing | `⚠ Classify: canon context classify not available on the installed binary. Skipped.` |
-| Range refused      | `⚠ Classify: <message>`, naming the verb's own message                               |
-
-Neither case stops the fold. This step checks what the fold wrote, and a check that cannot run is not a reason to leave the fold's own output unshipped.
-
-## Report
-
-Print one line naming what ran, `✅ Classify: <n> findings, regex ran, model <modelLayer>`, then one line per non-`KEEP` finding:
-
-- `✏ Rewrote: <file>, "<quote>" (<reason>)`
-- `✂ Cut: <file>, "<quote>" (<reason>)`
-- `➡ Move needed: <file>, "<quote>" (<reason>)`, for a `MOVE` this step reported rather than cut
-- `⏭ Kept: <file>, "<quote>", <reason for keeping>`
-- `⚠ Not located: <file>, "<quote>" not found or found more than once`
-
-When every finding reads `KEEP`, output `✅ Classify: <n> findings, all KEEP` and nothing further.