@erclx/canon 4.81.0 → 4.82.0

package/src/context/classify/patterns.ts

@@ -0,0 +1,114 @@
+/**
+ * Regex layer for the doc classifier, ported from the groundwork spike at
+ * `.canon/groundwork/93-canonical-doc-drift/scripts/heuristic.py`. It never
+ * needs a model installed, so it is the layer that always runs.
+ *
+ * Diff mode reads one changed chunk and answers KEEP, HISTORY, or MOVE. It
+ * never answers REPLACE, since telling a restated figure from a genuinely new
+ * one needs the section the hunk landed in, which the model layer reads and
+ * this one does not. Sweep mode reads one whole section and answers KEEP,
+ * REWRITE, or MOVE, collapsing REPLACE and HISTORY the way the sweep prompt
+ * does, since a section already carries its own history in view.
+ */
+
+export type DiffVerdict = 'KEEP' | 'REPLACE' | 'HISTORY' | 'MOVE'
+export type SweepVerdict = 'KEEP' | 'REWRITE' | 'MOVE'
+
+export interface PatternVerdict<V extends string> {
+  readonly verdict: V
+  /** Absent on KEEP, since nothing decided against the text. */
+  readonly quote?: string
+  readonly reason: string
+}
+
+/**
+ * Narrates how a fact got here rather than stating it: a branch or PR name, a
+ * closed or retired marker, a review-pass story. Ported from
+ * `heuristic.py`'s `NARRATION` pattern with one change: the bare
+ * `on \d{4}-\d{2}-\d{2}` alternative is dropped.
+ *
+ * That alternative was measured to false-flag a gotcha ending "Measured at
+ * `<sha>` on <date>.", a dating anchor both prompts call correct on a current
+ * statement. Every tuned hunk the bare date branch caught also carries a
+ * narration verb elsewhere in the same text (`closed on`, `moved again`,
+ * `did not survive`), so dropping it costs no measured catch and removes the
+ * one measured false flag.
+ */
+const NARRATION =
+  /moved (again|twice|on)|has since|at this branch|on `feat|Measured in PR|did not survive|the operator picked|picked arm|\barm \d|closed on|was retired|no longer|used to|\bround\b|a review pass|this pass/i
+
+/**
+ * A source-file path inside prose, the shape of implementation detail landing
+ * on a surface that should describe layout and intent instead. Ported
+ * verbatim from `heuristic.py`.
+ */
+const MECHANISM_IN_WIREFRAME = /`[\w./-]+\.(tsx?|py|css|spec\.ts)`/
+
+function narrationQuote(text: string): string | undefined {
+  return text.match(NARRATION)?.[0]
+}
+
+/**
+ * Classifies one diff-mode chunk from its added text alone.
+ *
+ * `file` decides whether the wireframe-only MOVE test applies. A file argument
+ * rather than a boolean matches `run.ts`'s other call sites, which hold the
+ * path and not a pre-computed flag.
+ */
+export function diffPatternVerdict(
+  file: string,
+  added: string,
+): PatternVerdict<DiffVerdict> {
+  const quote = narrationQuote(added)
+  if (quote !== undefined) {
+    return { verdict: 'HISTORY', quote, reason: 'narrates how this got here' }
+  }
+
+  if (file.includes('wireframes/')) {
+    const match = added.match(MECHANISM_IN_WIREFRAME)
+    if (match) {
+      return {
+        verdict: 'MOVE',
+        quote: match[0],
+        reason: 'names a source file, which is implementation detail',
+      }
+    }
+  }
+
+  return { verdict: 'KEEP', reason: 'no narration or wrong-surface pattern' }
+}
+
+/**
+ * Classifies one sweep-mode section from its whole body.
+ *
+ * REWRITE stands in for both REPLACE and HISTORY, matching `sweep-v1.md`'s
+ * own three-verdict vocabulary: a section already shows its own history in
+ * full view, so the model layer does not need the diff-mode split and the
+ * regex layer follows it.
+ */
+export function sweepPatternVerdict(
+  file: string,
+  body: string,
+): PatternVerdict<SweepVerdict> {
+  const quote = narrationQuote(body)
+  if (quote !== undefined) {
+    return {
+      verdict: 'REWRITE',
+      quote,
+      reason: 'carries its own history rather than the current state alone',
+    }
+  }
+
+  if (file.includes('wireframes/')) {
+    const match = body.match(MECHANISM_IN_WIREFRAME)
+    if (match) {
+      return {
+        verdict: 'MOVE',
+        quote: match[0],
+        reason: 'names a source file, which is implementation detail',
+      }
+    }
+  }
+
+  return { verdict: 'KEEP', reason: 'no narration or wrong-surface pattern' }
+}

package/src/context/classify/prompts.ts

@@ -0,0 +1,73 @@
+/**
+ * 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). Neither prompt text is invented here.
+ *
+ * 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.
+- ARCHITECTURE.md: cross-domain decisions only, each a few sentences: what was chosen, over what, why. A measurement or mechanism specific to one domain belongs in that domain's context entry. Loaded every session, so weight matters.
+- wireframes/<surface>.md: layout sketches, reachable states, exact on-screen copy, interaction intent. Would the line still be true if the surface were rebuilt in another framework? Component names, test files, pixel constants, and mechanism belong in context.
+- 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 or a decision log.
+- MOVE: correct content on the wrong surface (domain mechanism in ARCHITECTURE.md, implementation detail in a wireframe).
+
+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.
+- ARCHITECTURE.md: cross-domain decisions only, each a few sentences: what was chosen, over what, why. A measurement or mechanism specific to one domain belongs in that domain's context entry.
+- wireframes/<surface>.md: layout, reachable states, exact on-screen copy, interaction intent. Would the line still be true if the surface were rebuilt in another framework? Component names, test files, and pixel constants belong in context.
+- 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, one domain's mechanism in architecture, implementation detail in a wireframe).
+
+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.
+
+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

@@ -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,
+    },
+  }
+}