doctrina-cli 0.12.0 → 0.14.0

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
@@ -17,12 +18,24 @@
 //   set-criterion 1: verified
 //   replace-criterion 2: [verified] new text — verified by `test/x.test.ts`
 //   append-criterion [unverified] new signal — verified by `test/y.test.ts`
+//   append-requirement event: When X occurs, the system shall do Y.
+//   replace-requirement ubiquitous 2: The system shall do Z.
 //   ```
 //
+// The requirement verbs (operator review 2026-07-19 §4.1) cover the dominant
+// MODIFIED case — inserting or rewording EARS bullets in a `## Requirements
+// (EARS)` subsection — so a typical delta no longer falls back to a manual
+// merge. Because append-* verbs resolve their position/number at APPLY time,
+// concurrent open changes appending to the same spec cannot collide on
+// numbering: order of application decides, mechanically.
+//
 // A `# comment` or blank line inside the block is ignored. When a delta has
 // 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");
 
@@ -49,9 +62,27 @@ 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.
+//
+// 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 m = text.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) {
@@ -92,11 +123,50 @@ function parseOpLine(line) {
       if (!rest) return { verb, error: "append-criterion is missing its text" };
       return { verb, value: rest };
     }
+    case "append-requirement": {
+      // append-requirement <section>: <text>
+      const colon = rest.indexOf(":");
+      if (colon < 0) return { verb, error: `append-requirement needs "<section>: <text>" (got "${rest}")` };
+      const section = normalizeSection(rest.slice(0, colon).trim());
+      const value = rest.slice(colon + 1).trim();
+      if (!section) return { verb, error: `append-requirement: unknown section "${rest.slice(0, colon).trim()}" (use ${SECTION_TOKENS})` };
+      if (!value) return { verb, error: "append-requirement is missing the requirement text" };
+      return { verb, section, value };
+    }
+    case "replace-requirement": {
+      // replace-requirement <section> <n>: <text>
+      const colon = rest.indexOf(":");
+      if (colon < 0) return { verb, error: `replace-requirement needs "<section> <n>: <text>" (got "${rest}")` };
+      const head = rest.slice(0, colon).trim().split(/\s+/);
+      const value = rest.slice(colon + 1).trim();
+      const n = Number(head[head.length - 1]);
+      const section = normalizeSection(head.slice(0, -1).join(" "));
+      if (!section) return { verb, error: `replace-requirement: unknown section "${head.slice(0, -1).join(" ")}" (use ${SECTION_TOKENS})` };
+      if (!Number.isInteger(n) || n < 1) return { verb, error: `replace-requirement needs a positive bullet number (got "${rest}")` };
+      if (!value) return { verb, error: `replace-requirement ${n} is missing the requirement text` };
+      return { verb, section, n, value };
+    }
     default:
       return { verb: null, error: `unknown operation "${verb}"` };
   }
 }
 
+// EARS subsection aliases -> the canonical token used to match the spec's
+// `### ` heading under `## Requirements (EARS)`. Deterministic: first word of
+// the heading, folded ("Unwanted-behavior (must-not)" -> "unwanted").
+const SECTIONS = {
+  ubiquitous: "ubiquitous",
+  event: "event", "event-driven": "event",
+  state: "state", "state-driven": "state",
+  unwanted: "unwanted", "unwanted-behavior": "unwanted", "must-not": "unwanted",
+  optional: "optional",
+};
+const SECTION_TOKENS = "ubiquitous|event|state|unwanted|optional";
+
+function normalizeSection(raw) {
+  return SECTIONS[raw.toLowerCase()] ?? null;
+}
+
 // Apply a parsed op list to a spec's Markdown text. Pure: returns
 // { text, applied: string[], errors: string[] } and never throws. A failed
 // op is recorded in `errors` and leaves the text unchanged for that op, so
@@ -132,6 +202,10 @@ function applyOne(text, op) {
       return replaceCriterion(text, op.n, op.value);
     case "append-criterion":
       return appendCriterion(text, op.value);
+    case "append-requirement":
+      return appendRequirement(text, op.section, op.value);
+    case "replace-requirement":
+      return replaceRequirement(text, op.section, op.n, op.value);
     default:
       return { error: `unknown operation "${op.verb}"` };
   }
@@ -221,6 +295,157 @@ export function replaceCriterion(text, n, value) {
   return { text: loc.lines.join("\n"), summary: `replace-criterion ${n}` };
 }
 
+// The `### <Section>` blocks under `## Requirements (EARS)`. Returns
+// { lines, sections: { <token>: { headingIndex, endIndex, bullets: [lineIndex] } } }
+// or null when the Requirements section is absent. A section's token is the
+// first word of its heading, folded through SECTIONS ("Unwanted-behavior
+// (must-not)" -> "unwanted"). endIndex is exclusive: the line index of the
+// next heading (### or ##) after the section, or lines.length.
+function locateRequirements(text) {
+  const lines = text.split(/\r?\n/);
+  let inRequirements = false;
+  let current = null;
+  const sections = {};
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    if (/^##\s+/.test(line) && !/^###/.test(line)) {
+      if (current) { current.endIndex = i; current = null; }
+      inRequirements = /^##\s+Requirements\b/i.test(line);
+      continue;
+    }
+    if (!inRequirements) continue;
+    const h = line.match(/^###\s+(\S+)/);
+    if (h) {
+      if (current) current.endIndex = i;
+      const token = SECTIONS[h[1].toLowerCase().replace(/[^a-z-]/g, "")] ?? null;
+      current = { headingIndex: i, endIndex: lines.length, bullets: [] };
+      if (token) sections[token] = current;
+      continue;
+    }
+    if (current && /^\s*-(\s|$)/.test(line)) current.bullets.push(i);
+  }
+  return Object.keys(sections).length > 0 || /^##\s+Requirements\b/im.test(text)
+    ? { lines, sections }
+    : null;
+}
+
+// A list item may wrap over indented continuation lines ("- When X,\n
+// the system shall ..."). Inserting right after the item's FIRST line
+// splits it from its continuation — the bug the 0.13.0 dogfood close
+// caught on this very repo's cli spec. From the item's first line, the
+// item ends after every following line that is indented content.
+function endOfItem(lines, startIndex) {
+  let i = startIndex;
+  while (i + 1 < lines.length && /^\s+\S/.test(lines[i + 1])) i += 1;
+  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) {
+  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];
+  const placeholder = sec.bullets.length === 1 && /^\s*-\s*$/.test(loc.lines[sec.bullets[0]]);
+  if (placeholder) {
+    loc.lines[sec.bullets[0]] = `- ${value}`;
+  } else if (sec.bullets.length > 0) {
+    loc.lines.splice(endOfItem(loc.lines, sec.bullets[sec.bullets.length - 1]) + 1, 0, `- ${value}`);
+  } else {
+    // Empty section: insert after the heading (skipping one blank line if present).
+    let at = sec.headingIndex + 1;
+    while (at < sec.endIndex && loc.lines[at].trim() === "") at += 1;
+    loc.lines.splice(at, 0, `- ${value}`);
+  }
+  return { text: loc.lines.join("\n"), summary: `append-requirement ${section}: ${value.slice(0, 60)}` };
+}
+
+// replace-requirement <section> <n>: <text> — replace the nth bullet (1-based)
+// of the EARS subsection.
+export function replaceRequirement(text, section, n, value) {
+  const loc = locateRequirements(text);
+  if (!loc) return { error: "replace-requirement: spec has no '## Requirements (EARS)' section" };
+  const sec = loc.sections[section];
+  if (!sec) return { error: `replace-requirement: no '### ${section}...' subsection found under Requirements` };
+  const real = sec.bullets.filter((i) => !/^\s*-\s*$/.test(loc.lines[i]));
+  if (n > real.length) {
+    return { error: `replace-requirement: section "${section}" has ${real.length} requirement${real.length === 1 ? "" : "s"}, no #${n}` };
+  }
+  const indent = loc.lines[real[n - 1]].match(/^(\s*)/)[1];
+  loc.lines[real[n - 1]] = `${indent}- ${value}`;
+  return { text: loc.lines.join("\n"), summary: `replace-requirement ${section} ${n}` };
+}
+
 // append-criterion <text> — add a new numbered criterion after the last one
 // in the section.
 export function appendCriterion(text, value) {
@@ -231,6 +456,6 @@ export function appendCriterion(text, value) {
   }
   const last = loc.items[loc.items.length - 1];
   const nextN = Math.max(...loc.items.map((it) => it.n)) + 1;
-  loc.lines.splice(last.lineIndex + 1, 0, `${last.indent}${nextN}. ${value}`);
+  loc.lines.splice(endOfItem(loc.lines, last.lineIndex) + 1, 0, `${last.indent}${nextN}. ${value}`);
   return { text: loc.lines.join("\n"), summary: `append-criterion ${nextN}` };
 }

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";