@erclx/canon 5.63.0 → 5.64.0

package/src/context/classify/prompts.ts

@@ -1,74 +0,0 @@
-/**
- * System prompts and user-message builders for the model layer, ported
- * verbatim as data from the groundwork spike at
- * `.canon/groundwork/93-canonical-doc-drift/scripts/prompts/v3.md` (diff
- * mode) and `sweep-v1.md` (sweep mode). The diff prompt is verbatim. The sweep
- * prompt was tuned past `sweep-v1.md` with one decision check, measured
- * against the groundwork's labelled set in
- * `canon/context/context-model.md`.
- *
- * Each prompt already states its own rules per canonical doc type inside one
- * string, which is the shape the spike measured, so there is one prompt per
- * mode rather than one per doc type.
- */
-
-export const DIFF_SYSTEM_PROMPT = `You review one hunk just added to a project's canonical documentation. The docs state the project AS IT STANDS NOW. Judge only the ADDED text.
-
-File types and what they hold:
-- context/<domain>.md: one domain's structure, decisions (choice + the alternative that lost), gotchas. No history of how the domain got here, no change numbers, branch names, or dates attached to a change.
-- DESIGN.md: tokens and visual rules, current state only.
-
-Verdicts (pick exactly one):
-- KEEP: states current design, a rule, copy, a decision with its rejected alternative, or a live gotcha, on the right surface.
-- REPLACE: restates a fact or figure the existing section already carries ("moved again", "now", "the count moved", a newer number appended after an older one). The old statement should be rewritten in place, not appended to.
-- HISTORY: narrates how things got here: which branch/PR changed what, "closed on", "did not survive", review-pass stories, pick-by-pick rounds. The current state is what belongs; the trail goes to the PR.
-- MOVE: correct content on the wrong surface (a rule written into a context entry, or a measured result written into the requirements record).
-
-Return only JSON: {"verdict": "...", "quote": "<the shortest added phrase that decided it>", "reason": "<one sentence>"}
-
-Decision checks, in order:
-1. If the hunk REMOVED text and the added text is the same statement rewritten (a table row, a figure, a sentence updated in place), that is the correct way to update: KEEP, unless the new wording itself narrates history.
-2. A trailing "Measured at <sha> on <date>" or a branch name does not make a sentence current. If the section already carries an earlier figure or statement on the same subject and the hunk removed nothing, the answer is REPLACE.
-3. Judge only what the added text says. Narration elsewhere in the section is not evidence about this hunk.
-`
-
-export const SWEEP_SYSTEM_PROMPT = `You review one whole section of a project's canonical documentation, as it stands today. The docs must state the project AS IT IS NOW, once, on the right surface.
-
-File types and what they hold:
-- context/<domain>.md: one domain's structure, decisions (choice + the alternative that lost), gotchas. No history of how the domain got here, no change numbers, branch names, or dates attached to a change.
-- DESIGN.md: tokens and visual rules, current state only.
-- REQUIREMENTS.md: problem, goals, non-goals, scope, constraints. Never measured results.
-
-Verdicts (pick exactly one):
-- KEEP: the section states the current design, rules, copy, or decisions once, on the right surface. A single commit anchor on a figure is fine.
-- REWRITE: the section carries its own history: a figure followed by a later corrected figure, "superseded", "now", "moved", "no longer", "reverses the earlier reading", branch or PR narration, pick-by-pick rounds, a heading that narrates an event. The subject belongs here, but it must be restated as the current state.
-- MOVE: the section, or most of it, belongs on another surface (results in requirements).
-
-Decision checks, in order:
-1. Judge what the text says, not how long it is. A long section that states current design once is KEEP.
-2. A trailing "Measured at <sha> on <date>" does not make a paragraph current if another paragraph in the section states an older value on the same subject.
-3. Short rationale for a current rule ("the form checks length itself because...") is KEEP. A story of the rounds that produced the rule is REWRITE.
-4. Rationale is KEEP even when it is told in the past tense. A reason naming why an alternative was left out, what an earlier approach got wrong, what a measurement caught, or what a past run cost is the evidence for the current rule, so a sentence such as "the first form timed out" or "two runs took 1281s and 1924s" or "reading figures from real data caught three wrong claims" supports a rule that stands and stays KEEP. Past tense alone is never the test.
-5. REWRITE needs the section to restate its own subject as a sequence: a superseded figure kept beside its replacement, "now" or "no longer" marking a change, branch or PR narration, or rounds of candidates. A maintenance step or an operator decision stated as a rule is current, not history.
-
-Return only JSON: {"verdict": "...", "quotes": ["<up to three short phrases copied from the section that decided it>"], "reason": "<one sentence>"}
-`
-
-/** Ported from `classify.py`'s `_user_message`, the unmarked diff-mode branch. */
-export function diffUserMessage(opts: {
-  readonly file: string
-  readonly removed: string
-  readonly added: string
-  readonly sectionAfter: string
-}): string {
-  const removed = opts.removed === '' ? '(nothing)' : opts.removed
-  return `FILE: ${opts.file}\n\nREMOVED IN THIS HUNK:\n${removed}\n\nADDED IN THIS HUNK:\n${opts.added}\n\nTHE SECTION AFTER THE CHANGE (for context):\n${opts.sectionAfter}`
-}
-
-/** Ported from `classify.py`'s `_user_message`, the sweep-mode branch. */
-export function sweepUserMessage(opts: {
-  readonly file: string
-  readonly body: string
-}): string {
-  return `FILE: ${opts.file}\n\nSECTION:\n${opts.body}`
-}

package/src/context/classify/run.ts

@@ -1,348 +0,0 @@
-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 `context-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). 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.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.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

@@ -1,196 +0,0 @@
-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)
-}