@erclx/canon 4.81.0 → 4.82.0

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/surface-root.ts

@@ -43,6 +43,7 @@ export const SURFACE_ENTRIES: readonly string[] = [
   'DESIGN.md',
   'context',
   'wireframes',
+  'decisions',
   'canon',
 ]
 

package/standards/decisions.md

@@ -0,0 +1,100 @@
+---
+title: Decisions reference
+description: Folder layout, ordinal filename, frontmatter, record sections, and the append-only lifecycle for canon/decisions/
+---
+
+# Decisions reference
+
+Applies to `canon/decisions/`. Holds the history a canonical doc used to carry itself: pick rounds, superseded figures, and a decision's rejected alternatives, in a tracked folder nothing loads eagerly. A canonical doc points at a record from its own history section rather than restating it.
+
+## Scope
+
+Governs `canon/decisions/`: folder layout, the ordinal filename, frontmatter, record sections, and the append-only lifecycle.
+
+Does not govern:
+
+- Which canonical doc points here and when, and what stays behind in that doc's own body: `architecture.md`, `context.md`, `wireframes.md`, `design.md`, `requirements.md`, once each states its own retirement rule
+- Voice, rhythm, and sentence construction: the `write-human` skill
+- Headings, punctuation, word choice, and file references: `markdown.md`
+
+## What a working record looks like
+
+A record works when a reader who has never opened the project can follow it from the file alone:
+
+- What was decided, stated once, without needing the canonical doc that points here
+- What else was considered, and why each alternative lost
+- Which claim rests on a measurement, and what commit that measurement was read against
+
+A record failing these is non-conforming even when it satisfies every shape rule below.
+
+## Folder name
+
+- `canon/decisions/`, resolved the way every tracked surface is: at `canon/decisions/` in a project that has moved, at `.claude/decisions/` in one that has not.
+- Never add `canon/decisions/index.md` to a `CLAUDE.md` `@` import. A log that loads eagerly rebuilds the bloat it exists to absorb. A canonical doc's own pointer is how a reader reaches a record, one file at a time.
+
+## Record filename
+
+- Name each record `<nn>-<slug>.md`, a two-digit zero-padded ordinal followed by a kebab-case slug, the same shape a groundwork track's folder takes.
+- The ordinal is the order the record was written in, which is what lets a listing sort by when a decision landed rather than alphabetically by subject.
+- Never renumber an existing record. A later reader cites it by that name, and a record whose number moved is a record a stale citation can no longer find.
+
+## Frontmatter
+
+- `title` (required): the decision in sentence case
+- `description` (required): one line naming what was decided
+
+## Sections
+
+Use `## Context`, `## Decision`, `## Alternatives`, and `## Measurements`.
+
+- `## Context`: the problem as it stood, stated so a reader needs nothing else open. Restate a fact rather than pointing at where it was found.
+- `## Decision`: what was chosen, and why, in enough detail that a reader can tell it apart from an alternative that sounds similar.
+- `## Alternatives`: each one considered and dropped, with the reason it lost. An alternative with no stated reason reads as a claim nobody checked.
+- `## Measurements`: skip when the decision cites no number. When it does, state the number and close with the commit it was read against, per Verification anchors below.
+
+## Verification anchors
+
+A record's reasoning stays correct while the numbers it cites move. The anchor records what a measured claim was read against, so a reader can tell a number that was checked and held from one nobody has looked at since.
+
+- Close a `## Measurements` section with a trailing sentence naming the short commit SHA and the ISO date that number was read: `Measured at <short-sha> on <YYYY-MM-DD>.`
+- Anchor on the number alone. A record citing none carries no `## Measurements` section at all.
+- Read an absent section as unchecked rather than as current. A record with no measurements has nothing due a re-read.
+
+## Lifecycle
+
+- Append-only. A written record is never edited to reflect a later reversal.
+- Write a new record when a later decision supersedes an earlier one, naming the record it supersedes. The old record stays as it was written, since it is history rather than a live statement of the current shape.
+- Never auto-loaded. A canonical doc's own history section links to a record by relative path, and a reader reaches it by following that link, not by the folder loading with the session.
+
+## Citation
+
+- Never cite `.canon/`. A record restates what it needs, since a clone without the gitignored records folder resolves nothing there.
+- Cite a same-repository pull request or commit the way `publish.md` fixes for any tracked document.
+
+## Template
+
+```markdown
+---
+title: <Decision, in sentence case>
+description: <one line naming what was decided>
+---
+
+# <Decision title>
+
+## Context
+
+<The problem as it stood, self-contained.>
+
+## Decision
+
+<What was chosen, and why.>
+
+## Alternatives
+
+- **<Alternative>.** <Why it lost.>
+- **<Alternative>.** <Why it lost.>
+
+## Measurements
+
+<The number the decision rests on.> Measured at <short-sha> on <YYYY-MM-DD>.
+```

package/standards/index.md

@@ -11,6 +11,7 @@ Reference docs for consistent authoring across the toolkit and target projects.
 - [Branch reference](branch.md): Branch naming format and type conventions
 - [Commit reference](commit.md): Commit message format and type conventions
 - [Context entry reference](context.md): Shape and content rules for canon/context/<domain>.md entries
+- [Decisions reference](decisions.md): Folder layout, ordinal filename, frontmatter, record sections, and the append-only lifecycle for canon/decisions/
 - [Design reference](design.md): Shape and content rules for canon/DESIGN.md
 - [Diagram reference](diagrams.md): Shape and content rules for .canon/diagrams/<kind>.md files
 - [Docs reference](docs.md): Reader and jurisdiction, frontmatter, page structure, what a page links out to, the diagram permission, and when a category earns a subfolder

package/tooling/claude/reference.md

@@ -14,6 +14,7 @@ canon/
 ├── ARCHITECTURE.md    ← seeded. Technical design decisions and open questions
 ├── DESIGN.md          ← seeded. Visual intent and the decisions behind it
 ├── context/           ← seeded. Per-domain narrative. `index.md` is the discovery anchor.
+├── decisions/         ← seeded. Decision history a canonical doc points at, never loaded eagerly. `<nn>-<slug>.md` records.
 └── wireframes/        ← seeded. Per-surface ASCII layouts. `index.md` is the discovery anchor; `<surface>.md` files hold the sketches and behavior bullets.
 
 .claude/

package/tooling/claude/seeds/CLAUDE.md

@@ -22,3 +22,4 @@
 - `canon/DESIGN.md`: design tokens and the visual system
 - `canon/context/`: per-domain narrative (how a domain is structured, decisions, gotchas), indexed via `canon/context/index.md`
 - `canon/wireframes/`: per-surface ASCII layouts loaded on demand, indexed via `canon/wireframes/index.md`
+- `canon/decisions/`: decision history a project doc points at, never loaded eagerly

package/tooling/claude/seeds/canon/decisions/index.md

@@ -0,0 +1,8 @@
+---
+title: Decisions
+subtitle: Decision history a project doc points at, never loaded eagerly
+---
+
+# Decisions
+
+Decision history a project doc points at, never loaded eagerly