doctrina-cli 0.13.0 → 0.14.0

package/src/lib/json-out.js

@@ -0,0 +1,83 @@
+// @ts-check
+import process from "node:process";
+import { EXIT } from "./exit-codes.js";
+
+// `--json` on every command, with a versioned envelope (audit item M7).
+//
+// Five of thirty-five commands spoke JSON. Everything else emitted
+// ANSI-coloured prose, while the primary consumer is a machine. Paired with
+// the exit-code contract (ADR 0018), the two form the machine interface:
+// structured output plus a meaningful status. Without both, an autonomous
+// loop is parsing English.
+//
+// Two levels of support, and the difference is stated rather than hidden:
+//
+//   STRUCTURED — the command builds a payload describing its result. These
+//     are the read and report commands, where a result has real shape.
+//   ENVELOPE   — the command's human output is captured and returned inside
+//     a versioned envelope alongside `ok` and `exitCode`. Branch on those;
+//     the lines are there for completeness, not for parsing.
+//
+// A command with nothing better to say is still machine-consumable, which
+// is what makes "--json on every command" a claim rather than an intention.
+
+export const JSON_SCHEMA_VERSION = "1.0.0";
+
+export function wantsJson(flags) {
+  return flags?.get?.("json") === true;
+}
+
+// Print a structured payload. `command` is the invocation, `data` whatever
+// that command has to say.
+export function emitJson(command, data, { ok = true, exitCode = EXIT.OK } = {}) {
+  process.stdout.write(JSON.stringify({
+    $schema_version: JSON_SCHEMA_VERSION,
+    command,
+    ok,
+    exit_code: exitCode,
+    ...data,
+  }, null, 2) + "\n");
+}
+
+// Run `fn` with console output captured, so a command that has no
+// structured payload can still answer in JSON. Returns { code, stdout,
+// stderr } with the lines it would have printed.
+export async function captureOutput(fn) {
+  const stdout = [];
+  const stderr = [];
+  const origLog = console.log;
+  const origError = console.error;
+  const origWarn = console.warn;
+  // Some commands write to the stream directly rather than through console
+  // — `completion` emits a shell script meant for redirection. Capturing
+  // only console.* let that output escape the envelope and corrupt the
+  // JSON on stdout, so the raw stream is captured too.
+  const origWrite = process.stdout.write.bind(process.stdout);
+  const pushLines = (target, chunk) => {
+    for (const line of String(chunk).replace(/\n$/, "").split("\n")) target.push(line);
+  };
+  console.log = (...args) => stdout.push(args.map(String).join(" "));
+  console.error = (...args) => stderr.push(args.map(String).join(" "));
+  console.warn = (...args) => stderr.push(args.map(String).join(" "));
+  process.stdout.write = (chunk, ...rest) => {
+    pushLines(stdout, chunk);
+    const cb = rest.find((r) => typeof r === "function");
+    if (cb) cb();
+    return true;
+  };
+  try {
+    const code = await fn();
+    return { code: code ?? EXIT.OK, stdout, stderr };
+  } finally {
+    console.log = origLog;
+    console.error = origError;
+    console.warn = origWarn;
+    process.stdout.write = origWrite;
+  }
+}
+
+// Strip ANSI so captured lines are usable as data even when colour was on.
+export function stripAnsi(s) {
+  // eslint-disable-next-line no-control-regex
+  return String(s).replace(/\[[0-9;]*m/g, "");
+}

package/src/lib/prompt.js

@@ -1,4 +1,15 @@
+// @ts-check
 import readline from "node:readline";
+import process from "node:process";
+
+// Is there a real person on the other end? Every prompt must ask this
+// first. `init` checked it before the ADAPTER prompt but not before the
+// project-description prompt, so a non-interactive caller that forgot
+// --non-interactive got a project with a blank description and no warning
+// (audit item C9).
+export function isInteractive() {
+  return Boolean(process.stdin.isTTY && process.stdout.isTTY);
+}
 
 export async function ask(question, { defaultValue = "" } = {}) {
   const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
@@ -11,7 +22,13 @@ export async function ask(question, { defaultValue = "" } = {}) {
   }
 }
 
-export async function confirm(question, { defaultYes = false } = {}) {
+// Ask for consent. Off a terminal there is nobody to ask, so the answer is
+// `whenNonInteractive` — which callers set to false for destructive
+// operations: silence is not consent.
+export async function confirm(question, { defaultYes = false, whenNonInteractive = null } = {}) {
+  if (!isInteractive()) {
+    return whenNonInteractive === null ? defaultYes : whenNonInteractive;
+  }
   const suffix = defaultYes ? "Y/n" : "y/N";
   const ans = await ask(`${question} (${suffix})`);
   if (!ans) return defaultYes;

package/src/lib/scan.js

@@ -1,3 +1,5 @@
+// @ts-check
+import { getHeader, getSection } from "./doc-model.js";
 import path from "node:path";
 import { readdirSync } from "node:fs";
 import { isDir, isFile, read, walk } from "./fs-ops.js";
@@ -5,29 +7,18 @@ import { today } from "./dates.js";
 import { parseFrontmatter } from "../commands/skill.js";
 import { parseOperation, parseCapabilityFromDelta } from "../commands/change.js";
 
-// Parse a metadata header line, tolerating BOTH conventions:
-//   **Name:** value        (spec style)
-//   - **Name:** value      (ADR / proposal / intake style)
-// The leading "- " is optional so a one-character convention slip (an
-// agent hand-authoring an ADR with the bare spec form, or vice versa)
-// still parses instead of silently falling back to a default value.
-const HEADER_PREFIX = "(?:-\\s+)?";
-
-// Parse a spec-style header line: **Name:** value (dash optional).
+// Header reading lives in ONE place now (lib/doc-model.js, audit item M3).
+// These two names survive because dozens of call sites use them and the
+// distinction they once encoded — spec style vs list style — is now the
+// document model's job, not the caller's.
 export function specHeader(text, name) {
-  const m = text.match(new RegExp(`^${HEADER_PREFIX}\\*\\*${name}:\\*\\*\\s+(.+)$`, "m"));
-  return m ? m[1].trim() : null;
+  return getHeader(text, name);
 }
 
-// Parse an ADR/proposal-style header line: - **Name:** value (dash optional).
 export function listHeader(text, name) {
-  const m = text.match(new RegExp(`^${HEADER_PREFIX}\\*\\*${name}:\\*\\*\\s+(.+)$`, "m"));
-  return m ? m[1].trim() : null;
+  return getHeader(text, name);
 }
 
-// The machine-readable "**Depends on:** defects, decisions" spec header: the
-// sibling capabilities this spec builds on. Returns [] when absent, "n/a", or
-// empty. One parser so index, why, context, and review agree.
 export function parseDependsOn(text) {
   const raw = specHeader(text, "Depends on");
   if (!raw || /^n\/a\b/i.test(raw.trim()) || raw.trim() === "—") return [];
@@ -39,6 +30,72 @@ function dirEntries(dir) {
   return readdirSync(dir).filter((e) => !e.startsWith(".")).sort();
 }
 
+
+// The capabilities an ADR governs, from its optional "Scope:" header
+// (M4). Returns [] when absent, "n/a", or "—" — an unscoped ADR is global
+// and belongs in every pack, which is what keeps this backward compatible.
+export function parseAdrScope(text) {
+  const raw = listHeader(text, "Scope");
+  if (!raw || /^n\/a\b/i.test(raw.trim()) || raw.trim() === "—") return [];
+  return raw.match(/[a-z][a-z0-9][a-z0-9-]*/g) ?? [];
+}
+
+// One sentence describing what an ADR decided, taken from its "## Decision"
+// section. This is what a budget-constrained pack falls back to before it
+// drops an ADR entirely: a title and a sentence still carry the decision,
+// where an omission carries nothing.
+export function adrSummary(text) {
+  const body = getSection(text, "Decision");
+  if (!body) return null;
+  for (const line of body.split("\n")) {
+    const s = line.trim();
+    if (!s || s.startsWith("<!--") || s.startsWith("#") || s.startsWith("|")) continue;
+    // Take the first sentence, capped so the index stays scannable.
+    const plain = s.replace(/^[-*\d.]+\s*/, "").replace(/\*\*/g, "");
+    const sentence = (plain.match(/^.*?[.!?](?=\s|$)/) ?? [plain])[0].trim();
+    if (sentence.length < 12) continue;
+    return sentence.length > 220 ? sentence.slice(0, 217).trimEnd() + "..." : sentence;
+  }
+  return null;
+}
+
+// The index entry for ONE decision, derived from its file. This is the
+// single definition of a decision record: `deriveIndex` builds the whole
+// list from it, and `doctrina decision new` registers a new ADR through it
+// rather than assembling a look-alike by hand. Two constructors for one
+// record shape is how a field added to the deriver (M4's `summary`) turns
+// every freshly created ADR into index drift the moment it is written.
+export function decisionEntry(text, basename, prev, date) {
+  const id = basename.match(/^(\d{4})-/)?.[1] ?? prev?.id ?? "0000";
+  const titleMatch = text.match(/^#\s+ADR\s+\d{4}\s*[—-]\s*(.+)$/m);
+  const entry = {
+    id,
+    path: `.doctrina/decisions/${basename}`,
+    title: titleMatch ? titleMatch[1].trim() : prev?.title ?? basename,
+    status: listHeader(text, "Status") ?? prev?.status ?? "proposed",
+    date: listHeader(text, "Date") ?? prev?.date ?? date,
+  };
+  const supersedes = listHeader(text, "Supersedes");
+  if (supersedes && supersedes !== "—") entry.supersedes = supersedes;
+  const supersededBy = listHeader(text, "Superseded by");
+  if (supersededBy && supersededBy !== "—") entry.superseded_by = supersededBy;
+  const landed = listHeader(text, "Landed");
+  if (landed && landed !== "—") entry.landed = landed;
+  // Scope (M4): the capabilities this decision governs. ADRs are immutable
+  // and never retire, so without a scope every accepted ADR loads into every
+  // context pack forever — the pack grows O(project age) with no decay. An
+  // ADR with no Scope: is GLOBAL by definition, the backward-compatible
+  // default.
+  const scope = parseAdrScope(text);
+  if (scope.length > 0) entry.scope = scope;
+  // Summary: one sentence from the Decision section, so a pack over budget
+  // can degrade an ADR to title + summary instead of dropping it outright.
+  const summary = adrSummary(text);
+  if (summary) entry.summary = summary;
+  return entry;
+}
+
+
 // Regenerate the index object from the artifacts on disk. The files are
 // the source of truth; fields with no on-disk source (project name,
 // framework_version, product metadata) are carried over from `current`.
@@ -52,6 +109,12 @@ export function deriveIndex(projectRoot, current) {
     project: current?.project ?? path.basename(projectRoot),
     framework_version: current?.framework_version ?? "0.0.0",
     last_updated: current?.last_updated ?? date,
+    // Project settings, carried over verbatim. `deriveIndex` rebuilds the
+    // artifact graph FROM DISK, so anything it does not explicitly carry is
+    // silently erased on the next `index rebuild` — config has no on-disk
+    // source to be rederived from, which is exactly why it must be listed
+    // here alongside project and framework_version. Absent means defaults.
+    ...(current?.config !== undefined ? { config: current.config } : {}),
     artifacts: {
       product: cur.product ?? {
         path: ".doctrina/product.md",
@@ -112,23 +175,8 @@ export function deriveIndex(projectRoot, current) {
     const base = path.basename(f);
     const m = base.match(/^(\d{4})-.*\.md$/);
     if (!m) continue;
-    const text = read(f);
     const prev = (cur.decisions ?? []).find((d) => d.id === m[1]);
-    const titleMatch = text.match(/^#\s+ADR\s+\d{4}\s*[—-]\s*(.+)$/m);
-    const entry = {
-      id: m[1],
-      path: `.doctrina/decisions/${base}`,
-      title: titleMatch ? titleMatch[1].trim() : prev?.title ?? base,
-      status: listHeader(text, "Status") ?? prev?.status ?? "proposed",
-      date: listHeader(text, "Date") ?? prev?.date ?? date,
-    };
-    const supersedes = listHeader(text, "Supersedes");
-    if (supersedes && supersedes !== "—") entry.supersedes = supersedes;
-    const supersededBy = listHeader(text, "Superseded by");
-    if (supersededBy && supersededBy !== "—") entry.superseded_by = supersededBy;
-    const landed = listHeader(text, "Landed");
-    if (landed && landed !== "—") entry.landed = landed;
-    out.artifacts.decisions.push(entry);
+    out.artifacts.decisions.push(decisionEntry(read(f), base, prev, date));
   }
 
   // Open changes — every directory except archive/.

package/src/lib/spec-ops.js

@@ -1,3 +1,4 @@
+// @ts-check
 // Structured spec operations (ADR 0007 / review F3). A MODIFIED spec delta
 // historically carried prose ("flip criterion 2 to verified", "bump to
 // 0.3.0") that a human merged by hand — the single most error-prone step in
@@ -32,6 +33,9 @@
 // no ops block, apply falls back to the manual-merge pointer (backward
 // compatible).
 
+// The read grammar is the document model's (M3); this local pattern exists
+// only because the ops verbs REWRITE headers in place and need the prefix
+// captured to preserve it.
 const HEADER_RE = (name) =>
   new RegExp(`^(\\s*(?:-\\s+)?\\*\\*${escapeRe(name)}:\\*\\*)\\s*(.*)$`, "m");
 
@@ -57,14 +61,28 @@ export function extractOps(deltaText) {
 
 // Find the body of the first ```ops fenced block, or null if absent. The
 // info string must be exactly "ops" (case-insensitive) so a normal code
-// fence in the prose is never mistaken for operations. HTML comments are
-// stripped first: the scaffolded delta template carries an EXAMPLE ops block
-// inside its instructional comment, and executing an example against a real
-// spec is exactly the surprise this guard removes.
+// fence in the prose is never mistaken for operations.
+//
+// A fence sitting INSIDE an HTML comment is skipped: the scaffolded delta
+// template carries an EXAMPLE ops block in its instructional comment, and
+// executing an example against a real spec is exactly the surprise this
+// guard removes. The comment is skipped by POSITION, never by deleting the
+// comment text first — stripping mutated ops values that legitimately
+// contain a comment (an `<!-- illustrative -->` marker inside an
+// append-criterion landed in the spec with the marker silently gutted).
 function matchOpsBlock(text) {
-  const visible = text.replace(/<!--[\s\S]*?-->/g, "");
-  const m = visible.match(/^[ \t]*```[ \t]*ops[ \t]*\r?\n([\s\S]*?)^[ \t]*```[ \t]*$/m);
-  return m ? m[1] : null;
+  const commentRanges = [];
+  for (const m of text.matchAll(/<!--[\s\S]*?-->/g)) {
+    commentRanges.push([m.index, m.index + m[0].length]);
+  }
+  const insideComment = (offset) => commentRanges.some(([a, b]) => offset >= a && offset < b);
+
+  const fenceRe = /^[ \t]*```[ \t]*ops[ \t]*\r?\n([\s\S]*?)^[ \t]*```[ \t]*$/gm;
+  let m;
+  while ((m = fenceRe.exec(text))) {
+    if (!insideComment(m.index)) return m[1];
+  }
+  return null;
 }
 
 function parseOpLine(line) {
@@ -322,15 +340,82 @@ function endOfItem(lines, startIndex) {
   return i;
 }
 
+// The EARS subsections in the order the spec template lays them out. A
+// created subsection goes where a reader expects it, not at the end.
+const EARS_ORDER = ["ubiquitous", "event", "state", "unwanted", "optional"];
+const EARS_HEADINGS = {
+  ubiquitous: "### Ubiquitous",
+  event: "### Event-driven",
+  state: "### State-driven",
+  unwanted: "### Unwanted-behavior (must-not)",
+  optional: "### Optional",
+};
+
+// Create an absent `### <EARS>` subsection under `## Requirements (EARS)`,
+// carrying its first requirement, in canonical order: after the last
+// existing subsection that precedes it, or ahead of them all when none
+// does. The requirement goes in with the heading rather than in a second
+// pass, so the blank lines around the new block are exact.
+function createEarsSubsection(loc, section, value) {
+  const heading = EARS_HEADINGS[section];
+  if (!heading) return { error: `append-requirement: unknown EARS subsection "${section}"` };
+  const lines = [...loc.lines];
+
+  let insertAt = null;
+  const rank = EARS_ORDER.indexOf(section);
+  for (const token of EARS_ORDER.slice(0, rank).reverse()) {
+    const prior = loc.sections[token];
+    if (prior) {
+      // End of that subsection, trimmed back past the blank lines it trails.
+      let end = Math.min(prior.endIndex, lines.length);
+      while (end > prior.headingIndex + 1 && lines[end - 1].trim() === "") end -= 1;
+      insertAt = end;
+      break;
+    }
+  }
+  if (insertAt === null) {
+    // Nothing precedes it: place it ahead of whichever subsection currently
+    // comes first, or directly under the Requirements heading.
+    const first = EARS_ORDER.map((t) => loc.sections[t]).find(Boolean);
+    if (first) {
+      insertAt = first.headingIndex;
+    } else {
+      const reqIndex = lines.findIndex((l) => /^##\s+Requirements\b/i.test(l));
+      if (reqIndex < 0) return { error: "append-requirement: spec has no '## Requirements (EARS)' section" };
+      insertAt = reqIndex + 1;
+    }
+  }
+
+  // Exactly one blank line on each side, borrowing whichever the
+  // insertion point already provides rather than adding a second.
+  const block = [heading, "", `- ${value}`];
+  if (insertAt > 0 && lines[insertAt - 1].trim() !== "") block.unshift("");
+  if (lines[insertAt] !== undefined && lines[insertAt].trim() !== "") block.push("");
+  lines.splice(insertAt, 0, ...block);
+  return { text: lines.join("\n") };
+}
+
 // append-requirement <section>: <text> — add "- <text>" at the end of the
 // EARS subsection. A lone "-" placeholder bullet (the untouched scaffold) is
 // replaced instead of appended after, so the first real requirement does not
 // land under an empty stub.
 export function appendRequirement(text, section, value) {
-  const loc = locateRequirements(text);
+  let loc = locateRequirements(text);
   if (!loc) return { error: "append-requirement: spec has no '## Requirements (EARS)' section" };
+  if (!loc.sections[section]) {
+    // The subsection does not exist yet. Refusing here is a dead end: the
+    // author cannot hand-edit the spec (AGENTS.md forbids editing specs
+    // outside a delta) and no op creates a subsection, so a spec that was
+    // split — losing the EARS headings it had no requirements for — could
+    // never receive one again. Create it, in canonical EARS order.
+    const created = createEarsSubsection(loc, section, value);
+    if (created.error) return created;
+    return {
+      text: created.text,
+      summary: `append-requirement ${section} (created subsection): ${value.slice(0, 44)}`,
+    };
+  }
   const sec = loc.sections[section];
-  if (!sec) return { error: `append-requirement: no '### ${section}...' subsection found under Requirements` };
   const placeholder = sec.bullets.length === 1 && /^\s*-\s*$/.test(loc.lines[sec.bullets[0]]);
   if (placeholder) {
     loc.lines[sec.bullets[0]] = `- ${value}`;

package/src/lib/suggest.js

@@ -1,3 +1,4 @@
+// @ts-check
 // Tiny Levenshtein distance + "did you mean" suggester. Zero deps.
 
 export function distance(a, b) {

package/src/lib/templates.js

@@ -1,3 +1,4 @@
+// @ts-check
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { read, toPosix, walk, write } from "./fs-ops.js";
@@ -35,6 +36,94 @@ export function locateTemplatesDir() {
   );
 }
 
+// ---------------------------------------------------------------------------
+// The project-local override chain (audit item M1).
+//
+// `doctrina init` creates `.doctrina/templates/` containing a single
+// `.gitkeep`, and nothing ever read it or wrote to it. The resolver above
+// answers only "where did the CLI install its templates?", so a directory
+// the framework creates in every project was inert — a ghost.
+//
+// Resolution is now a CHAIN, per file: a template present under the
+// project's `.doctrina/templates/` wins; anything absent falls back to the
+// bundled copy. That turns the ghost into the customisation point, and it
+// is the same wiring the custom-adapter support needs (ADR 0016).
+//
+// Deliberately per FILE, not per directory: a team that wants its own
+// `spec.md.template` should not have to vendor the whole tree and then
+// maintain every other template forever.
+
+export function projectTemplatesDir(projectRoot) {
+  return path.join(projectRoot, ".doctrina", "templates");
+}
+
+// Where a named template resolves for this project.
+// Returns { path, source: "project" | "bundled" } or null when neither has
+// it. `relativePath` is POSIX-ish and relative to a templates root, e.g.
+// "spec.md.template" or "change/proposal.md.template".
+export function resolveTemplate(projectRoot, relativePath) {
+  const rel = relativePath.split("/").join(path.sep);
+  if (projectRoot) {
+    const local = path.join(projectTemplatesDir(projectRoot), rel);
+    if (fileExists(local)) return { path: local, source: "project" };
+  }
+  try {
+    const bundled = path.join(locateTemplatesDir(), rel);
+    if (fileExists(bundled)) return { path: bundled, source: "bundled" };
+  } catch { /* no bundled tree (unusual install) */ }
+  return null;
+}
+
+// Read a template through the chain. Throws with both candidates named
+// when neither side has it, because "template not found" with no path is
+// the least actionable error a scaffolder can give.
+export function readTemplate(projectRoot, relativePath) {
+  const resolved = resolveTemplate(projectRoot, relativePath);
+  if (!resolved) {
+    throw new Error(
+      `template "${relativePath}" not found in the project override ` +
+      `(${projectTemplatesDir(projectRoot)}) or in the installed CLI`,
+    );
+  }
+  return { ...resolved, body: read(resolved.path) };
+}
+
+// Every template the chain can serve, with where each one resolved from —
+// what `templates list` prints so the source is never a guess.
+export function listResolvedTemplates(projectRoot) {
+  const seen = new Map();
+  let bundledRoot = null;
+  try {
+    bundledRoot = locateTemplatesDir();
+  } catch { /* none */ }
+
+  if (bundledRoot) {
+    for (const f of walk(bundledRoot)) {
+      const rel = toPosix(path.relative(bundledRoot, f));
+      seen.set(rel, { relativePath: rel, path: f, source: "bundled" });
+    }
+  }
+  const localRoot = projectRoot ? projectTemplatesDir(projectRoot) : null;
+  if (localRoot) {
+    for (const f of walk(localRoot)) {
+      const rel = toPosix(path.relative(localRoot, f));
+      if (rel === ".gitkeep") continue;
+      const overrides = seen.has(rel);
+      seen.set(rel, { relativePath: rel, path: f, source: "project", overrides });
+    }
+  }
+  return [...seen.values()].sort((a, b) => a.relativePath.localeCompare(b.relativePath));
+}
+
+function fileExists(p) {
+  try {
+    read(p);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
 // Single-pass {{TOKEN}} substitution. Tokens are uppercase, digits, or
 // underscore inside double curly braces.
 export function substitute(text, tokens) {

package/src/lib/usage.js

@@ -0,0 +1,89 @@
+// @ts-check
+// Audit item M8: instrument the command surface before shrinking it.
+//
+// The surface is 36 commands and 59 operations. The audit's charge is that
+// some of them exist because they were easy to add, not because anybody
+// reaches for them — and the honest way to find out which is to MEASURE,
+// not to guess from the outside. Guessing is how `prime`, `handoff` and
+// `doctor` were nearly cut in 0.13.0, right before the operator review
+// found they had gone unused only because AGENTS.md never named them.
+//
+// The design constraints this is built under:
+//
+//   OFF unless asked.  No file appears, and nothing is recorded, until the
+//     operator sets DOCTRINA_USAGE_LOG. A tool that starts logging because
+//     it was updated has broken faith regardless of what it logs.
+//   LOCAL only.  One append-only JSONL file at a path the operator names.
+//     The CLI makes no network calls at all (a spec requirement), and this
+//     changes nothing about that.
+//   NO ARGUMENTS.  The command and the sub-operation, never the values.
+//     `change apply 0021-secret-project` records `change apply`. Paths,
+//     titles, prompts and ids are the user's, not the instrument's.
+//   NEVER FATAL.  A failure to record is silent. Losing a usage sample
+//     matters less than nothing, and losing the command's real work to an
+//     instrumentation error would be absurd.
+
+import { appendFileSync } from "node:fs";
+import process from "node:process";
+
+export const USAGE_ENV = "DOCTRINA_USAGE_LOG";
+
+// Which operation was invoked, with no user data attached.
+//
+// The second positional is kept ONLY when the catalog says this command has
+// that sub-operation. Shape alone is not enough to tell a sub-command from
+// an argument: `context cli` and `spec new` are identical in shape, but the
+// first is a capability name. Guessing recorded `context cli` as an
+// operation and left the real `context` looking unused — which is exactly
+// the wrong answer from an instrument whose whole job is deciding what
+// nobody uses.
+export function operationOf(positional, knownOperations) {
+  const command = positional[0];
+  if (!command) return null;
+  const next = positional[1];
+  if (typeof next !== "string" || !/^[a-z][a-z-]{1,20}$/.test(next)) return command;
+  const pair = `${command} ${next}`;
+  return knownOperations?.has(pair) ? pair : command;
+}
+
+// Append one sample. Returns true when it recorded, false otherwise — the
+// tests assert on that rather than on the file, so the "off by default"
+// guarantee is checked directly.
+export function recordUsage(positional, exitCode, knownOperations, env = process.env) {
+  const target = env[USAGE_ENV];
+  if (!target) return false;
+  const operation = operationOf(positional, knownOperations);
+  if (!operation) return false;
+  try {
+    appendFileSync(target, JSON.stringify({
+      at: new Date().toISOString(),
+      operation,
+      exit: exitCode ?? 0,
+    }) + "\n");
+    return true;
+  } catch {
+    // Instrumentation never breaks the command it is measuring.
+    return false;
+  }
+}
+
+// Summarise a usage log: how often each operation ran, and — the number the
+// shrink decision actually turns on — which catalog operations never ran at
+// all. An operation with zero samples is a CANDIDATE for cutting or
+// folding, never a verdict: a command used once a quarter (`init`) and a
+// command nobody wants look identical over one week.
+export function summarise(logText, catalogOperations) {
+  const counts = new Map();
+  let samples = 0;
+  for (const line of String(logText).split("\n")) {
+    if (!line.trim()) continue;
+    let row;
+    try { row = JSON.parse(line); } catch { continue; }
+    if (!row?.operation) continue;
+    counts.set(row.operation, (counts.get(row.operation) ?? 0) + 1);
+    samples += 1;
+  }
+  const used = [...counts.entries()].sort((a, b) => b[1] - a[1] || (a[0] < b[0] ? -1 : 1));
+  const unused = catalogOperations.filter((op) => !counts.has(op)).sort();
+  return { samples, used, unused };
+}

package/src/lib/version.js

@@ -1,3 +1,4 @@
+// @ts-check
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { readFileSync } from "node:fs";