@erclx/canon 4.81.0 → 4.83.0

package/src/context/classify/ollama.ts

@@ -0,0 +1,172 @@
+/**
+ * The local Ollama backend: a reachability probe and one chat call per item.
+ *
+ * One chunk or section per call, never batched. The groundwork spike measured
+ * batching 16 hunks into a single call returning KEEP for every one, so a
+ * caller here (`run.ts`) invokes `chat` once per item rather than folding a
+ * set into one prompt.
+ */
+
+export const DEFAULT_OLLAMA_BASE_URL = 'http://localhost:11434'
+
+/**
+ * Nothing in the groundwork pins a request timeout: the spike scripts used a
+ * 600s ceiling meant for a batch research run, not a per-call budget for an
+ * interactive verb. 30s is chosen here as a deviation, wide enough that a
+ * shared GPU under another local session's load (measured coexisting at 12GB)
+ * still has room, while short enough that a `docs-fold` run does not hang
+ * indefinitely on a backend that stopped responding mid-call.
+ */
+export const OLLAMA_TIMEOUT_MS = 30_000
+
+/** Parsed straight off the model's own JSON, upper-cased for a loose model. */
+export interface ParsedVerdict {
+  readonly verdict: string
+  readonly quote: string
+  readonly reason: string
+}
+
+export type ChatOutcome =
+  | {
+      readonly kind: 'ok'
+      readonly parsed: ParsedVerdict
+      readonly raw: string
+    }
+  | { readonly kind: 'unparsed'; readonly raw: string }
+  | { readonly kind: 'unreachable'; readonly message: string }
+  | { readonly kind: 'timeout' }
+
+function describeError(error: unknown): string {
+  return error instanceof Error ? error.message : String(error)
+}
+
+function isTimeout(error: unknown): boolean {
+  return error instanceof DOMException && error.name === 'TimeoutError'
+}
+
+/**
+ * Reads the model's reply out of its own JSON body.
+ *
+ * Ported from `classify.py`'s `_parse`: find the first `{` and the last `}`,
+ * so a model that wraps its JSON in a sentence or a fence still parses. Diff
+ * mode returns a single `quote` string and sweep mode returns a `quotes`
+ * array, and both are read here since the caller decides which mode it asked
+ * for by which prompt it sent, not by which shape came back.
+ */
+export function parseVerdictText(text: string): ParsedVerdict | undefined {
+  const start = text.indexOf('{')
+  const end = text.lastIndexOf('}')
+  if (start === -1 || end === -1 || end < start) return undefined
+
+  let data: unknown
+  try {
+    data = JSON.parse(text.slice(start, end + 1))
+  } catch {
+    return undefined
+  }
+
+  if (typeof data !== 'object' || data === null) return undefined
+  const record = data as Record<string, unknown>
+
+  const verdict = record.verdict
+  if (typeof verdict !== 'string' || verdict === '') return undefined
+
+  const quote =
+    typeof record.quote === 'string'
+      ? record.quote
+      : Array.isArray(record.quotes)
+        ? record.quotes.map((entry) => String(entry)).join(' | ')
+        : ''
+
+  const reason = typeof record.reason === 'string' ? record.reason : ''
+
+  return { verdict: verdict.toUpperCase(), quote, reason }
+}
+
+/**
+ * Whether the backend answers at all, checked before the real call so a
+ * per-item timeout is never the thing that discovers an unreachable Ollama.
+ */
+export async function probeOllama(
+  baseUrl: string,
+  timeoutMs = OLLAMA_TIMEOUT_MS,
+): Promise<boolean> {
+  try {
+    const response = await fetch(`${baseUrl}/api/tags`, {
+      signal: AbortSignal.timeout(timeoutMs),
+    })
+    return response.ok
+  } catch {
+    return false
+  }
+}
+
+/**
+ * One chat call: JSON output format, temperature 0, thinking off.
+ *
+ * Thinking is always off. The groundwork spike measured it never catching a
+ * flag thinking-off missed, at roughly five times the latency, and in sweep
+ * mode it lost three real flags by reasoning itself past them. There is no
+ * option to turn it on here, matching the groundwork decision to defer that
+ * rather than build an unused knob.
+ */
+export async function chat(opts: {
+  readonly baseUrl: string
+  readonly model: string
+  readonly system: string
+  readonly user: string
+  readonly timeoutMs?: number
+}): Promise<ChatOutcome> {
+  const timeoutMs = opts.timeoutMs ?? OLLAMA_TIMEOUT_MS
+
+  let response: Response
+  try {
+    response = await fetch(`${opts.baseUrl}/api/chat`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({
+        model: opts.model,
+        stream: false,
+        think: false,
+        format: 'json',
+        options: { temperature: 0, num_ctx: 16384 },
+        messages: [
+          { role: 'system', content: opts.system },
+          { role: 'user', content: opts.user },
+        ],
+      }),
+      signal: AbortSignal.timeout(timeoutMs),
+    })
+  } catch (error) {
+    if (isTimeout(error)) return { kind: 'timeout' }
+    return { kind: 'unreachable', message: describeError(error) }
+  }
+
+  if (!response.ok) {
+    return {
+      kind: 'unreachable',
+      message: `ollama returned ${response.status}`,
+    }
+  }
+
+  let body: unknown
+  try {
+    body = await response.json()
+  } catch (error) {
+    return { kind: 'unparsed', raw: describeError(error) }
+  }
+
+  const content =
+    typeof body === 'object' && body !== null
+      ? (body as { message?: { content?: unknown } }).message?.content
+      : undefined
+
+  if (typeof content !== 'string') {
+    return { kind: 'unparsed', raw: JSON.stringify(body) }
+  }
+
+  const parsed = parseVerdictText(content)
+  return parsed === undefined
+    ? { kind: 'unparsed', raw: content }
+    : { kind: 'ok', parsed, raw: content }
+}

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}`
+}