@erclx/canon 4.81.0 → 4.83.0

package/src/context/classify/run.ts

@@ -0,0 +1,348 @@
+import {
+  type CanonicalDocType,
+  extractDiffChunks,
+  extractSweepSections,
+  type ExtractRefusal,
+} from '@/context/classify/extract'
+import {
+  chat as ollamaChat,
+  type ChatOutcome,
+  DEFAULT_OLLAMA_BASE_URL,
+  probeOllama,
+} from '@/context/classify/ollama'
+import {
+  diffPatternVerdict,
+  type DiffVerdict,
+  type PatternVerdict,
+  sweepPatternVerdict,
+  type SweepVerdict,
+} from '@/context/classify/patterns'
+import {
+  DIFF_SYSTEM_PROMPT,
+  diffUserMessage,
+  SWEEP_SYSTEM_PROMPT,
+  sweepUserMessage,
+} from '@/context/classify/prompts'
+import {
+  type ClassifierBackend,
+  type ClassifierFlags,
+  type ClassifierResolution,
+  resolveClassifier,
+  type SettingSource,
+} from '@/context/classify/settings'
+
+const DIFF_VERDICTS: readonly DiffVerdict[] = [
+  'KEEP',
+  'REPLACE',
+  'HISTORY',
+  'MOVE',
+]
+const SWEEP_VERDICTS: readonly SweepVerdict[] = ['KEEP', 'REWRITE', 'MOVE']
+
+function isDiffVerdict(value: string): value is DiffVerdict {
+  return (DIFF_VERDICTS as readonly string[]).includes(value)
+}
+
+function isSweepVerdict(value: string): value is SweepVerdict {
+  return (SWEEP_VERDICTS as readonly string[]).includes(value)
+}
+
+/**
+ * A pattern verdict never carries a quote on KEEP, since nothing decided
+ * against the text. The finding's `regex` field is a `LayerVerdict` rather
+ * than a `PatternVerdict`, so it prints the same as a model layer verdict
+ * without every reader having to branch on an absent field.
+ */
+function withQuote<V extends string>(
+  verdict: PatternVerdict<V>,
+): LayerVerdict<V> {
+  return {
+    verdict: verdict.verdict,
+    quote: verdict.quote ?? '',
+    reason: verdict.reason,
+  }
+}
+
+export interface LayerVerdict<V extends string> {
+  readonly verdict: V
+  readonly quote: string
+  readonly reason: string
+}
+
+/**
+ * Why the model layer did not decide a run, named alongside `'ran'` so a
+ * caller reading the record never has to infer the reason from an absent
+ * field. `'off'` and `'skipped-no-model'` come from settings resolution
+ * alone; `'skipped-unreachable'` is the one state a probe call decides.
+ */
+export type ModelLayerState =
+  | 'off'
+  | 'ran'
+  | 'skipped-no-model'
+  | 'skipped-unreachable'
+
+export interface DiffFinding {
+  readonly file: string
+  readonly docType: CanonicalDocType
+  readonly regex: LayerVerdict<DiffVerdict>
+  readonly model?: LayerVerdict<DiffVerdict>
+  /** Set when the model ran but its reply carried no verdict this could read. */
+  readonly modelUnparsed?: boolean
+  readonly verdict: DiffVerdict
+  readonly decidedBy: 'regex' | 'model'
+}
+
+export interface SweepFinding {
+  readonly file: string
+  readonly docType: CanonicalDocType
+  readonly heading: string
+  readonly regex: LayerVerdict<SweepVerdict>
+  readonly model?: LayerVerdict<SweepVerdict>
+  readonly modelUnparsed?: boolean
+  readonly verdict: SweepVerdict
+  readonly decidedBy: 'regex' | 'model'
+}
+
+interface ClassifyRecordBase {
+  readonly backend: ClassifierBackend | undefined
+  readonly model: string | undefined
+  readonly modelLayer: ModelLayerState
+  readonly settingsSource: SettingSource
+}
+
+export interface DiffRecord extends ClassifyRecordBase {
+  readonly mode: 'diff'
+  readonly findings: readonly DiffFinding[]
+}
+
+export interface SweepRecord extends ClassifyRecordBase {
+  readonly mode: 'sweep'
+  readonly findings: readonly SweepFinding[]
+}
+
+export type ClassifyRefusal = ExtractRefusal
+
+export type ClassifyOutcome<Record> =
+  | { readonly kind: 'ok'; readonly record: Record }
+  | {
+      readonly kind: 'refused'
+      readonly reason: ClassifyRefusal
+      readonly message: string
+    }
+
+/**
+ * The network boundary, injected so a test drives the merge logic below
+ * without a live Ollama. `src/version/skew.ts` takes the same shape for the
+ * npm registry lookup it wraps.
+ */
+export interface ModelClient {
+  readonly probe: (baseUrl: string, timeoutMs?: number) => Promise<boolean>
+  readonly chat: (opts: {
+    readonly baseUrl: string
+    readonly model: string
+    readonly system: string
+    readonly user: string
+    readonly timeoutMs?: number
+  }) => Promise<ChatOutcome>
+}
+
+const DEFAULT_CLIENT: ModelClient = { probe: probeOllama, chat: ollamaChat }
+
+export interface ClassifyOptions {
+  readonly flags?: ClassifierFlags
+  readonly docTypes?: readonly CanonicalDocType[]
+  readonly baseUrl?: string
+  readonly client?: ModelClient
+}
+
+interface ModelLayerPlan {
+  readonly modelLayer: ModelLayerState
+  readonly backend?: ClassifierBackend
+  readonly model?: string
+}
+
+/**
+ * Decides whether the model layer runs, probing reachability before any real
+ * call. A configured-but-unreachable backend is a plan the caller reports and
+ * falls back from, never a refusal: the groundwork decision reads "warn and
+ * continue," and a refused run here would fail `docs-fold` for a reason that
+ * has nothing to do with the branch it is checking.
+ */
+async function planModelLayer(
+  resolution: ClassifierResolution,
+  client: ModelClient,
+  baseUrl: string,
+): Promise<ModelLayerPlan> {
+  if (resolution.kind === 'off') return { modelLayer: 'off' }
+  if (resolution.kind === 'no-model') {
+    return { modelLayer: 'skipped-no-model', backend: resolution.backend }
+  }
+
+  const reachable = await client.probe(baseUrl)
+  if (!reachable) {
+    return {
+      modelLayer: 'skipped-unreachable',
+      backend: resolution.backend,
+      model: resolution.model,
+    }
+  }
+
+  return {
+    modelLayer: 'ran',
+    backend: resolution.backend,
+    model: resolution.model,
+  }
+}
+
+/**
+ * One chunk or section, one model call, matching the measured constraint that
+ * batching multiple items into one prompt returned KEEP for everything. The
+ * caller (`classifyDiff`/`classifySweep`) awaits this once per item rather
+ * than issuing every call in parallel, since the items already share one
+ * backend and the groundwork measurements are all serial per-call numbers.
+ */
+async function modelVerdictFor<V extends string>(opts: {
+  readonly plan: ModelLayerPlan
+  readonly client: ModelClient
+  readonly baseUrl: string
+  readonly system: string
+  readonly user: string
+  readonly isVerdict: (value: string) => value is V
+}): Promise<{
+  readonly verdict?: LayerVerdict<V>
+  readonly unparsed: boolean
+}> {
+  if (opts.plan.modelLayer !== 'ran' || !opts.plan.model) {
+    return { unparsed: false }
+  }
+
+  const outcome = await opts.client.chat({
+    baseUrl: opts.baseUrl,
+    model: opts.plan.model,
+    system: opts.system,
+    user: opts.user,
+  })
+
+  if (outcome.kind !== 'ok' || !opts.isVerdict(outcome.parsed.verdict)) {
+    return { unparsed: true }
+  }
+
+  return {
+    verdict: {
+      verdict: outcome.parsed.verdict,
+      quote: outcome.parsed.quote,
+      reason: outcome.parsed.reason,
+    },
+    unparsed: false,
+  }
+}
+
+/**
+ * Runs diff mode over one git range: the regex layer over every extracted
+ * chunk, and the model layer over the same chunks when configured and
+ * reachable.
+ *
+ * A finding's `verdict` takes the model's reading when the model ran and
+ * parsed, and the regex reading otherwise, since the groundwork measurements
+ * show the model catching what the regex layer structurally cannot
+ * (REPLACE, and MOVE outside a wireframe). Both readings stay on the finding
+ * regardless of which one decided, so a caller can see where they disagreed.
+ */
+export async function classifyDiff(
+  root: string,
+  ref: string | undefined,
+  opts: ClassifyOptions = {},
+): Promise<ClassifyOutcome<DiffRecord>> {
+  const extraction = await extractDiffChunks(root, ref, opts.docTypes)
+  if (extraction.kind === 'refused') return extraction
+
+  const resolution = resolveClassifier(root, opts.flags ?? {})
+  const client = opts.client ?? DEFAULT_CLIENT
+  const baseUrl = opts.baseUrl ?? DEFAULT_OLLAMA_BASE_URL
+  const plan = await planModelLayer(resolution, client, baseUrl)
+
+  const findings: DiffFinding[] = []
+  for (const chunk of extraction.chunks) {
+    const regex = withQuote(diffPatternVerdict(chunk.file, chunk.added))
+    const model = await modelVerdictFor({
+      plan,
+      client,
+      baseUrl,
+      system: DIFF_SYSTEM_PROMPT,
+      user: diffUserMessage(chunk),
+      isVerdict: isDiffVerdict,
+    })
+
+    findings.push({
+      file: chunk.file,
+      docType: chunk.docType,
+      regex,
+      model: model.verdict,
+      modelUnparsed: model.unparsed || undefined,
+      verdict: model.verdict?.verdict ?? regex.verdict,
+      decidedBy: model.verdict ? 'model' : 'regex',
+    })
+  }
+
+  return {
+    kind: 'ok',
+    record: {
+      mode: 'diff',
+      backend: plan.backend,
+      model: plan.model,
+      modelLayer: plan.modelLayer,
+      settingsSource: resolution.source,
+      findings,
+    },
+  }
+}
+
+/** Runs sweep mode over every extracted section, mirroring `classifyDiff`. */
+export async function classifySweep(
+  root: string,
+  opts: ClassifyOptions = {},
+): Promise<ClassifyOutcome<SweepRecord>> {
+  const extraction = await extractSweepSections(root, opts.docTypes)
+  if (extraction.kind === 'refused') return extraction
+
+  const resolution = resolveClassifier(root, opts.flags ?? {})
+  const client = opts.client ?? DEFAULT_CLIENT
+  const baseUrl = opts.baseUrl ?? DEFAULT_OLLAMA_BASE_URL
+  const plan = await planModelLayer(resolution, client, baseUrl)
+
+  const findings: SweepFinding[] = []
+  for (const section of extraction.sections) {
+    const regex = withQuote(sweepPatternVerdict(section.file, section.body))
+    const model = await modelVerdictFor({
+      plan,
+      client,
+      baseUrl,
+      system: SWEEP_SYSTEM_PROMPT,
+      user: sweepUserMessage(section),
+      isVerdict: isSweepVerdict,
+    })
+
+    findings.push({
+      file: section.file,
+      docType: section.docType,
+      heading: section.heading,
+      regex,
+      model: model.verdict,
+      modelUnparsed: model.unparsed || undefined,
+      verdict: model.verdict?.verdict ?? regex.verdict,
+      decidedBy: model.verdict ? 'model' : 'regex',
+    })
+  }
+
+  return {
+    kind: 'ok',
+    record: {
+      mode: 'sweep',
+      backend: plan.backend,
+      model: plan.model,
+      modelLayer: plan.modelLayer,
+      settingsSource: resolution.source,
+      findings,
+    },
+  }
+}

package/src/context/classify/settings.ts

@@ -0,0 +1,196 @@
+import {
+  chmodSync,
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  statSync,
+  writeFileSync,
+} from 'node:fs'
+import { dirname, join } from 'node:path'
+
+/**
+ * Ollama is the only backend. The groundwork decision explicitly deferred a
+ * Haiku or Claude API backend, so this union has one member rather than
+ * carrying an unused second case a switch would have to handle.
+ */
+export type ClassifierBackend = 'ollama'
+
+/** Where `set` writes and `classify`/`classifier show` read the project setting. */
+export const CLASSIFIER_CONFIG_REL = join('canon', 'config', 'classifier.toml')
+
+export type SettingSource = 'flag' | 'env' | 'file' | 'default'
+
+export interface ClassifierFlags {
+  readonly backend?: string
+  readonly model?: string
+}
+
+interface FileSettings {
+  readonly backend?: string
+  readonly model?: string
+}
+
+function readFileSettings(root: string): FileSettings {
+  const path = join(root, CLASSIFIER_CONFIG_REL)
+  if (!existsSync(path)) return {}
+
+  let parsed: Record<string, unknown>
+  try {
+    parsed = Bun.TOML.parse(readFileSync(path, 'utf8')) as Record<
+      string,
+      unknown
+    >
+  } catch {
+    return {}
+  }
+
+  const table = parsed.classifier
+  if (typeof table !== 'object' || table === null) return {}
+  const { backend, model } = table as Record<string, unknown>
+
+  return {
+    backend: typeof backend === 'string' ? backend : undefined,
+    model: typeof model === 'string' ? model : undefined,
+  }
+}
+
+function isBackend(value: string): value is ClassifierBackend {
+  return value === 'ollama'
+}
+
+/**
+ * Resolves the backend through the stated precedence: flag, then the
+ * `CANON_CLASSIFIER_BACKEND` environment variable, then the project config
+ * file, then off. `off` is a value in its own right rather than an absence,
+ * since a project's config file setting `backend = "off"` states the same
+ * fact the missing-file default does, and the source line should say which
+ * one decided it.
+ *
+ * An unrecognized value at any tier is read the same as an absent one, and
+ * falls through to the next tier rather than refusing. That keeps a typo'd
+ * environment variable from silently making the whole precedence chain
+ * unreachable underneath it.
+ */
+export function resolveBackend(
+  root: string,
+  flags: ClassifierFlags,
+): {
+  readonly value: ClassifierBackend | 'off'
+  readonly source: SettingSource
+} {
+  if (flags.backend !== undefined) {
+    if (flags.backend === 'off') return { value: 'off', source: 'flag' }
+    if (isBackend(flags.backend))
+      return { value: flags.backend, source: 'flag' }
+  }
+
+  const envBackend = process.env.CANON_CLASSIFIER_BACKEND
+  if (envBackend !== undefined) {
+    if (envBackend === 'off') return { value: 'off', source: 'env' }
+    if (isBackend(envBackend)) return { value: envBackend, source: 'env' }
+  }
+
+  const fileBackend = readFileSettings(root).backend
+  if (fileBackend !== undefined) {
+    if (fileBackend === 'off') return { value: 'off', source: 'file' }
+    if (isBackend(fileBackend)) return { value: fileBackend, source: 'file' }
+  }
+
+  return { value: 'off', source: 'default' }
+}
+
+/**
+ * Resolves the model name through the same precedence as the backend, kept as
+ * a separate function since a caller can name a backend without a model (the
+ * `no-model` state `resolveClassifier` reports) or a model without a backend
+ * (which resolves nothing, since there is nothing to run it against).
+ */
+export function resolveModel(
+  root: string,
+  flags: ClassifierFlags,
+): { readonly value: string; readonly source: SettingSource } | undefined {
+  if (flags.model !== undefined && flags.model !== '') {
+    return { value: flags.model, source: 'flag' }
+  }
+
+  const envModel = process.env.CANON_CLASSIFIER_MODEL
+  if (envModel !== undefined && envModel !== '') {
+    return { value: envModel, source: 'env' }
+  }
+
+  const fileModel = readFileSettings(root).model
+  if (fileModel !== undefined && fileModel !== '') {
+    return { value: fileModel, source: 'file' }
+  }
+
+  return undefined
+}
+
+export type ClassifierResolution =
+  | { readonly kind: 'off'; readonly source: SettingSource }
+  | {
+      readonly kind: 'no-model'
+      readonly backend: ClassifierBackend
+      readonly source: SettingSource
+    }
+  | {
+      readonly kind: 'configured'
+      readonly backend: ClassifierBackend
+      readonly model: string
+      /** The source that decided the backend, which decided the model layer runs at all. */
+      readonly source: SettingSource
+    }
+
+/**
+ * Combines the two precedence reads into the one answer `classify` and
+ * `classifier show` both need: whether the model layer runs, and why.
+ *
+ * No default model name exists on purpose. The groundwork decision reads: a
+ * model name on one machine means nothing on another, so `show` reports the
+ * gap and `classify` warns and falls back to the regex layer rather than
+ * guessing a name that may not be pulled.
+ */
+export function resolveClassifier(
+  root: string,
+  flags: ClassifierFlags = {},
+): ClassifierResolution {
+  const backend = resolveBackend(root, flags)
+  if (backend.value === 'off') return { kind: 'off', source: backend.source }
+
+  const model = resolveModel(root, flags)
+  if (model === undefined) {
+    return { kind: 'no-model', backend: backend.value, source: backend.source }
+  }
+
+  return {
+    kind: 'configured',
+    backend: backend.value,
+    model: model.value,
+    source: backend.source,
+  }
+}
+
+/**
+ * Writes the project's classifier setting, creating `canon/config/` when a
+ * project does not carry it yet. `pr-labels.toml` is the one precedent for a
+ * `canon/config/` file and it is hand-authored and read-only to the CLI, so
+ * this is the first write path into that folder and the first TOML file this
+ * CLI generates rather than parses.
+ *
+ * Preserves an existing file's mode per the operator-file convention, so a
+ * destination an operator locked down keeps its permissions across a rewrite.
+ */
+export function writeClassifierConfig(
+  root: string,
+  backend: ClassifierBackend | 'off',
+  model?: string,
+): void {
+  const path = join(root, CLASSIFIER_CONFIG_REL)
+  const mode = existsSync(path) ? statSync(path).mode : undefined
+
+  const modelLine = model ? `model = "${model}"\n` : ''
+  mkdirSync(dirname(path), { recursive: true })
+  writeFileSync(path, `[classifier]\nbackend = "${backend}"\n${modelLine}`)
+
+  if (mode !== undefined) chmodSync(path, mode)
+}

package/src/context/folders.ts

@@ -19,6 +19,7 @@ import { SURFACE_ROOTS } from '@/surface-root'
  */
 export const DEFAULT_FOLDERS: readonly string[] = [
   'context',
+  'decisions',
   'diagrams',
   'wireframes',
 ]

package/src/context/gate.ts

@@ -1,5 +1,6 @@
 import type { SectionFinding } from '@/context/audit'
 import type { FolderDrift } from '@/context/index-drift'
+import type { WireframeStatesReport } from '@/context/wireframe-states'
 
 export interface GateInput {
   /** Cited paths that resolved to nothing, which gate under either mode. */
@@ -15,6 +16,22 @@ export interface GateInput {
   readonly recordOverLength: boolean
   readonly sections: readonly SectionFinding[]
   readonly drift: readonly FolderDrift[]
+  /**
+   * Every wireframe entry's states report, empty for a project carrying no
+   * `canon/wireframes/` folder. A states/evidence mismatch is a fact read off
+   * the file, the same standing the missing-section and index-drift findings
+   * already have, so it gates alongside them under the widened mode.
+   *
+   * A sketch beside existing evidence stays out of the gate on both modes.
+   * `sketchWithEvidence` reads the whole entry against whether any of its
+   * states has evidence, not the sketched layout against the evidence for
+   * that same layout, since the standard's `## States` table names states
+   * rather than layouts and the report has no narrower unit to match on. An
+   * entry with a captured default layout and a sketch for a breakpoint layout
+   * that is not built yet is conforming and still trips this reading, so the
+   * finding stays a judgment for a reader rather than a fact a push fails on.
+   */
+  readonly wireframes: readonly WireframeStatesReport[]
   /**
    * Whether the caller asked for the widened gate. False leaves a missing
    * section and a drifted index advisory, which is what the project-root stage
@@ -30,28 +47,49 @@ export function hasDrift(drift: readonly FolderDrift[]): boolean {
   )
 }
 
+/** Whether any wireframe's States table disagrees with its evidence folders. */
+export function hasStatesMismatch(
+  wireframes: readonly WireframeStatesReport[],
+): boolean {
+  return wireframes.some(
+    (entry) =>
+      entry.missingFolders.length > 0 || entry.unlistedFolders.length > 0,
+  )
+}
+
+/** Whether any wireframe carries a sketch beside evidence that already exists. */
+export function hasSketchWithEvidence(
+  wireframes: readonly WireframeStatesReport[],
+): boolean {
+  return wireframes.some((entry) => entry.sketchWithEvidence)
+}
+
 /**
  * Whether the audit found something that should fail the caller.
  *
  * An unresolved citation is a broken pointer and gates unconditionally, and so
  * does a record past its own ceiling: the record states the limit for itself
  * and derives it from a count, which makes it the one measure here that is a
- * fact rather than a threshold a reader weighs. The two findings `--gate` adds
- * are the ones answerable from the file itself: a required section it does not
- * declare, and an index disagreeing with its folder. Entry length, depth,
- * bullet, table, provenance, and the record's claim coverage are judgments, so
- * they stay out under both modes.
+ * fact rather than a threshold a reader weighs. The findings `--gate` adds are
+ * the ones answerable from the file itself: a required section it does not
+ * declare, an index disagreeing with its folder, and a wireframe's States
+ * table disagreeing with its evidence folders. Entry length, depth, bullet,
+ * table, provenance, the record's claim coverage, and a sketch beside
+ * existing evidence are judgments, so they stay out under both modes. The
+ * `wireframes` field's own doc states why the sketch finding is a judgment
+ * rather than a fact.
  */
 export function isGating({
   unresolvedCitations,
   recordOverLength,
   sections,
   drift,
+  wireframes,
   widened,
 }: GateInput): boolean {
   if (unresolvedCitations > 0) return true
   if (recordOverLength) return true
   if (!widened) return false
 
-  return sections.length > 0 || hasDrift(drift)
+  return sections.length > 0 || hasDrift(drift) || hasStatesMismatch(wireframes)
 }