doctrina-cli 0.2.2 → 0.4.0

package/README.md

@@ -3,7 +3,7 @@
 > CLI for the Doctrina framework. The package is published as
 > `doctrina-cli`; the executable it installs is `doctrina`.
 
-**Status:** v0.1.0 — first working release. Zero runtime dependencies
+**Status:** v0.4.0 — current release. Zero runtime dependencies
 (Node.js standard library only).
 
 ## Install
@@ -20,14 +20,19 @@ Requires Node.js 20.12 or later.
 
 ```
 doctrina init                              scaffold AGENTS.md + .doctrina/ in cwd
+doctrina intake [<file>]                   store the full description + bootstrap playbook (clarification gate)
+doctrina work "<prompt>"                   brief prompt -> scaffolded change + work playbook (clarification gate)
 doctrina spec new <capability>             create a capability spec
 doctrina spec list                         list specs with version, status, size
 doctrina change new <id> "<title>"         open a change proposal
 doctrina change apply <id>                 apply spec deltas (ADDED/REMOVED auto)
 doctrina change archive <id>               archive an applied change
 doctrina change diff <id>                  preview spec deltas (line diff for MODIFIED)
+doctrina contract new <name>               own the integration surface (ports, env, interfaces)
+doctrina contract check                    verify port collisions, env drift, referenced specs
 doctrina decision new "<title>"            create the next sequential ADR
 doctrina decision accept <num>             flip a proposed ADR to accepted
+doctrina decision land <num> [path...]     stamp an accepted ADR as implemented (non-mutating Landed:)
 doctrina decision supersede <num> "<t>"    supersede an existing ADR
 doctrina decision list                     list ADRs with status, date, title
 doctrina skill new <name>                  scaffold an on-demand procedural-memory skill
@@ -36,8 +41,11 @@ doctrina skill sync                        mirror skill frontmatter descriptions
 doctrina analyze <change-id>               inspect a change folder before applying
 doctrina clarify <path>                    smell-test a Markdown file for ambiguity (--all: tree)
 doctrina context [<capability>]            print the context pack in read order (--concat)
-doctrina search <term> [...]               search artifacts, grouped by category
+doctrina search <term> [...]               search artifacts, grouped by category (ranked)
 doctrina validate                          schema + artifact-existence checks
+doctrina coverage                          acceptance criteria with linked evidence (--strict gates)
+doctrina trace                             intent provenance: product intent -> specs (--strict gates)
+doctrina verify                            run project typecheck/test/build checks (the real gate)
 doctrina templates list                    enumerate shipped templates
 doctrina templates check                   compare project against recommended template shape
 doctrina templates update                  additive fixer for check findings (preview; --write applies)
@@ -109,9 +117,19 @@ For each spec delta found under `.doctrina/changes/<id>/specs/`:
 16. Each skill's frontmatter description matches `index.json` (drift warn; `skill sync` fixes).
 17. EARS grammar shape per section in specs declaring `## Requirements (EARS)` (warn).
 18. Nested `AGENTS.md` files obey the root size caps (warn > 150, error > 200).
+19. No two ADR files share the same `NNNN` number (merge-collision error).
+20. `index.json` records a `framework_version` matching the running CLI
+    (stamp-divergence warn; `index rebuild` migrates it).
+21. Accepted ADRs anchor to reality via `Evidence:` and/or `Landed:`; cited
+    paths must exist on disk (drift warn).
 
 Exit code: 0 if no errors (warnings allowed), 1 otherwise.
 
+Two related read-only reports gate separately: `doctrina coverage`
+(each acceptance criterion cites a real test) and `doctrina trace`
+(each product intent has a capability, each capability traces to an
+intent). Both exit 1 under `--strict` for CI.
+
 ## Tests
 
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "doctrina-cli",
-  "version": "0.2.2",
+  "version": "0.4.0",
   "description": "Doctrina CLI — spec-driven, AGENTS.md-native framework for multi-agent AI development.",
   "license": "MIT",
   "keywords": [

package/src/commands/change.js

@@ -144,6 +144,7 @@ function changeApply(args, _flags) {
   // Flip proposal status from "proposed" to "applied" when fully successful.
   // Zero-delta changes are trivially successful (no work to fail), so they
   // also flip — otherwise metadata-only changes are stuck at "proposed".
+  let flippedToApplied = false;
   if (errors === 0 && manual === 0) {
     const proposalPath = path.join(changeDir, "proposal.md");
     if (exists(proposalPath)) {
@@ -155,30 +156,41 @@ function changeApply(args, _flags) {
       if (updated !== txt) {
         write(proposalPath, updated, { force: true });
         console.log(c.green("status") + " proposal.md → applied");
+        flippedToApplied = true;
       }
     }
   }
 
-  // Update index for ADDED/REMOVED that affected specs
-  if (writes > 0) {
+  // Update the index when specs changed (ADDED/REMOVED) and/or the proposal
+  // flipped to applied. The change entry's status must mirror the proposal —
+  // the same value `index rebuild` derives from the file — or the index
+  // drifts from the tree in the apply→archive window (caught by
+  // `index rebuild --check`, e.g. in the pre-commit hook).
+  if (writes > 0 || flippedToApplied) {
     const index = idx.load(projectRoot);
-    for (const deltaPath of deltaFiles) {
-      const text = read(deltaPath);
-      const op = parseOperation(text);
-      const capability = parseCapabilityFromDelta(text, deltaPath);
-      if (!capability) continue;
-      if (op === "ADDED") {
-        idx.addSpec(index, {
-          id: capability,
-          path: `.doctrina/specs/${capability}/spec.md`,
-          status: "active",
-          version: "0.1.0",
-          last_updated: date,
-        });
-      } else if (op === "REMOVED") {
-        idx.removeSpec(index, capability);
+    if (writes > 0) {
+      for (const deltaPath of deltaFiles) {
+        const text = read(deltaPath);
+        const op = parseOperation(text);
+        const capability = parseCapabilityFromDelta(text, deltaPath);
+        if (!capability) continue;
+        if (op === "ADDED") {
+          idx.addSpec(index, {
+            id: capability,
+            path: `.doctrina/specs/${capability}/spec.md`,
+            status: "active",
+            version: "0.1.0",
+            last_updated: date,
+          });
+        } else if (op === "REMOVED") {
+          idx.removeSpec(index, capability);
+        }
       }
     }
+    if (flippedToApplied) {
+      const entry = index.artifacts.changes.find((ch) => ch.id === id);
+      if (entry) entry.status = "applied";
+    }
     idx.touch(index, date);
     idx.save(projectRoot, index);
   }
@@ -193,7 +205,7 @@ function changeApply(args, _flags) {
   return errors > 0 ? 1 : 0;
 }
 
-function changeArchive(args, _flags) {
+function changeArchive(args, flags) {
   const id = args[0];
   if (!id) {
     console.error(c.red("error:") + " change archive requires <id>");
@@ -208,6 +220,28 @@ function changeArchive(args, _flags) {
     return 1;
   }
 
+  // Verification gate. "Done" is a claim until it is checked. Archiving is
+  // the act of declaring a change finished, so it must refuse while any
+  // task (including closing steps) or any declared verification item is
+  // still unchecked. This is the difference between "boxes marked" and
+  // "verification passed" the framework was faulted for collapsing.
+  // --force is the escape hatch: it archives anyway and records the gap.
+  const force = flagBool(flags, "force", false);
+  const blockers = collectArchiveBlockers(changeDir);
+  if (blockers.length > 0) {
+    if (!force) {
+      console.error(c.red("error:") + ` refusing to archive "${id}" — verification incomplete:`);
+      for (const b of blockers) console.error(`  - ${b}`);
+      console.error(
+        c.gray("hint: ") +
+          "finish and check the items, or pass --force to archive anyway (records the gap)",
+      );
+      return 1;
+    }
+    console.log(c.yellow("warn:") + ` archiving "${id}" with verification incomplete (--force):`);
+    for (const b of blockers) console.log(c.yellow("  - ") + b);
+  }
+
   const date = today();
   const archiveName = `${date}-${id}`;
   const archiveDir = path.join(projectRoot, ".doctrina", "changes", "archive", archiveName);
@@ -364,6 +398,45 @@ function extractDeltaBody(text) {
   return text.slice(idxSep + 5).replace(/^\n+/, "");
 }
 
+// Reasons a change is not finished enough to archive. Counts unchecked
+// GitHub-style checkboxes (`- [ ]`) in tasks.md (every task, including the
+// closing steps) and in the proposal's "## Verification" section. Returns
+// a list of human-readable blocker strings; empty means clear to archive.
+function collectArchiveBlockers(changeDir) {
+  const blockers = [];
+  const countUnchecked = (s) => (s.match(/^\s*-\s*\[ \]/gm) ?? []).length;
+
+  const tasksPath = path.join(changeDir, "tasks.md");
+  if (exists(tasksPath)) {
+    const n = countUnchecked(read(tasksPath));
+    if (n > 0) blockers.push(`${n} unchecked task${n === 1 ? "" : "s"} in tasks.md (closing steps count)`);
+  }
+
+  const proposalPath = path.join(changeDir, "proposal.md");
+  if (exists(proposalPath)) {
+    const n = countUnchecked(extractSection(read(proposalPath), "Verification"));
+    if (n > 0) blockers.push(`${n} unmet verification item${n === 1 ? "" : "s"} in proposal.md (## Verification)`);
+  }
+  return blockers;
+}
+
+// Return the body of a "## <name>" section (lines after the heading up to
+// the next "## " heading). Empty string when the section is absent.
+function extractSection(text, name) {
+  const lines = text.split(/\r?\n/);
+  const head = new RegExp(`^##\\s+${name}\\b`, "i");
+  let inSection = false;
+  const out = [];
+  for (const line of lines) {
+    if (/^##\s+/.test(line)) {
+      inSection = head.test(line);
+      continue;
+    }
+    if (inSection) out.push(line);
+  }
+  return out.join("\n");
+}
+
 function ensureDoctrinaProject(projectRoot) {
   if (!exists(path.join(projectRoot, ".doctrina"))) {
     throw new Error("not a Doctrina project (no .doctrina/ in cwd). Run `doctrina init` first.");

package/src/commands/contract.js

@@ -0,0 +1,254 @@
+import path from "node:path";
+import process from "node:process";
+import { readdirSync } from "node:fs";
+import { exists, isDir, isFile, read, relPath, write } from "../lib/fs-ops.js";
+import { locateTemplatesDir, substitute } from "../lib/templates.js";
+import { specHeader } from "../lib/scan.js";
+import * as idx from "../lib/index-json.js";
+import { today } from "../lib/dates.js";
+import { flagBool } from "../lib/args.js";
+import { c } from "../lib/colors.js";
+import { suggest } from "../lib/suggest.js";
+
+// Contracts are the first-class home for the integration/runtime surface
+// no single capability owns: the port map, the env/dependency contract,
+// and the API/WS/event interface shapes. The criticism this answers: each
+// capability was built against its own spec in isolation, and the seams
+// between them fell in the gap with nobody accountable. `contract check`
+// turns the parts that are mechanically verifiable (port collisions, env
+// drift vs .env.example, referenced specs that must exist) into a gate.
+
+const SUBCOMMANDS = ["new", "list", "check"];
+
+export async function run(positional, flags) {
+  const sub = positional[0];
+  switch (sub) {
+    case "new":
+      return contractNew(positional.slice(1), flags);
+    case "list":
+      return contractList();
+    case "check":
+      return contractCheck(positional.slice(1), flags);
+    default:
+      console.error(c.red("error:") + ` unknown contract subcommand "${sub ?? ""}"`);
+      const guess = suggest(sub, SUBCOMMANDS);
+      console.error(c.gray("hint: ") + (guess
+        ? `did you mean \`doctrina contract ${guess}\`?`
+        : `available: ${SUBCOMMANDS.join(", ")}`));
+      return 2;
+  }
+}
+
+function contractNew(args, flags) {
+  const name = args[0];
+  if (!name || !/^[a-z][a-z0-9-]*$/.test(name)) {
+    console.error(c.red("error:") + " contract name must be lowercase letters, digits, or hyphens (e.g. \"system\", \"api\").");
+    return 2;
+  }
+  const force = flagBool(flags, "force", false);
+  const projectRoot = process.cwd();
+  ensureDoctrinaProject(projectRoot);
+
+  const targetPath = path.join(projectRoot, ".doctrina", "contracts", `${name}.md`);
+  if (exists(targetPath) && !force) {
+    console.error(c.red("error:") + ` ${relPath(projectRoot, targetPath)} already exists (pass --force to overwrite)`);
+    return 1;
+  }
+
+  const templatesDir = locateTemplatesDir();
+  const date = today();
+  const body = substitute(read(path.join(templatesDir, "contract.md.template")), { CONTRACT_NAME: name, DATE: date });
+  write(targetPath, body, { force });
+  console.log(c.green("created") + ` ${relPath(projectRoot, targetPath)}`);
+
+  const index = idx.load(projectRoot);
+  idx.addContract(index, {
+    id: name,
+    path: `.doctrina/contracts/${name}.md`,
+    status: "active",
+    last_updated: date,
+  });
+  idx.touch(index, date);
+  idx.save(projectRoot, index);
+  console.log(c.green("indexed") + ` contract "${name}"`);
+  console.log("");
+  console.log("Fill in the Ports / Environment / Interfaces tables, then run " + c.cyan("doctrina contract check") + ".");
+  return 0;
+}
+
+function contractList() {
+  const projectRoot = process.cwd();
+  ensureDoctrinaProject(projectRoot);
+  const dir = path.join(projectRoot, ".doctrina", "contracts");
+  const rows = [];
+  if (isDir(dir)) {
+    for (const f of readdirSync(dir).sort()) {
+      if (!f.endsWith(".md")) continue;
+      const text = read(path.join(dir, f));
+      rows.push({ id: f.replace(/\.md$/, ""), status: specHeader(text, "Status") ?? "active", updated: specHeader(text, "Last updated") ?? "—" });
+    }
+  }
+  if (rows.length === 0) {
+    console.log(c.gray("no contracts found in .doctrina/contracts/ (create one with `doctrina contract new <name>`)"));
+    return 0;
+  }
+  console.log(c.bold("Contracts:"));
+  console.log("");
+  for (const r of rows) console.log(`  ${c.cyan(r.id.padEnd(20))} ${r.status.padEnd(10)} ${r.updated}`);
+  console.log("");
+  console.log(c.gray(`${rows.length} contract${rows.length === 1 ? "" : "s"}`));
+  return 0;
+}
+
+function contractCheck(args, _flags) {
+  const projectRoot = process.cwd();
+  ensureDoctrinaProject(projectRoot);
+  const dir = path.join(projectRoot, ".doctrina", "contracts");
+
+  let names;
+  if (args[0]) {
+    names = [args[0].replace(/\.md$/, "")];
+  } else if (isDir(dir)) {
+    names = readdirSync(dir).filter((f) => f.endsWith(".md")).map((f) => f.replace(/\.md$/, "")).sort();
+  } else {
+    names = [];
+  }
+  if (names.length === 0) {
+    console.log(c.gray("no contracts to check in .doctrina/contracts/"));
+    return 0;
+  }
+
+  // The env contract is checked against .env.example when one exists.
+  const envExamplePath = path.join(projectRoot, ".env.example");
+  const envExample = isFile(envExamplePath) ? read(envExamplePath) : null;
+
+  let errors = 0;
+  let warnings = 0;
+  for (const name of names) {
+    const file = path.join(dir, `${name}.md`);
+    if (!isFile(file)) {
+      console.log(c.red("error: ") + `contract "${name}" not found at ${relPath(projectRoot, file)}`);
+      errors += 1;
+      continue;
+    }
+    const text = read(file);
+    console.log(c.bold(name) + c.gray(` (${relPath(projectRoot, file)})`));
+
+    // 1. Port collisions — two services must not claim the same port.
+    const ports = parseTable(sectionOf(text, "Ports"));
+    if (ports) {
+      const portCol = colIndex(ports.headers, "port");
+      const svcCol = colIndex(ports.headers, "service");
+      const seen = new Map();
+      for (const row of ports.rows) {
+        const port = (row[portCol] ?? "").trim();
+        if (!/^\d+$/.test(port)) continue;
+        const svc = (row[svcCol] ?? "?").trim();
+        if (seen.has(port)) {
+          console.log(c.red("  ✗ ") + `port ${port} is claimed by both "${seen.get(port)}" and "${svc}"`);
+          errors += 1;
+        } else {
+          seen.set(port, svc);
+        }
+      }
+    }
+
+    // 2. Environment drift — every declared variable must exist in
+    //    .env.example (when present), so code, example, and infra agree.
+    const env = parseTable(sectionOf(text, "Environment"));
+    if (env && envExample !== null) {
+      const varCol = colIndex(env.headers, "variable");
+      for (const row of env.rows) {
+        const name2 = (row[varCol] ?? "").trim();
+        if (!/^[A-Z][A-Z0-9_]*$/.test(name2)) continue;
+        const declared = new RegExp(`^\\s*(export\\s+)?${name2}\\s*=`, "m").test(envExample);
+        if (!declared) {
+          console.log(c.yellow("  ! ") + `env var ${name2} is in the contract but absent from .env.example`);
+          warnings += 1;
+        }
+      }
+    }
+
+    // 3. Referenced capability specs must exist.
+    for (const refCap of referencedCapabilities(sectionOf(text, "References"))) {
+      const specPath = path.join(projectRoot, ".doctrina", "specs", refCap, "spec.md");
+      if (!isFile(specPath)) {
+        console.log(c.red("  ✗ ") + `references spec "${refCap}" but ${relPath(projectRoot, specPath)} does not exist`);
+        errors += 1;
+      }
+    }
+  }
+
+  console.log("");
+  if (errors === 0 && warnings === 0) {
+    console.log(c.green("ok") + ` ${names.length} contract${names.length === 1 ? "" : "s"} consistent`);
+    return 0;
+  }
+  const summary = `${errors} error${errors === 1 ? "" : "s"}, ${warnings} warning${warnings === 1 ? "" : "s"}`;
+  console.log((errors === 0 ? c.green("ok") : c.red("fail")) + " " + summary);
+  return errors === 0 ? 0 : 1;
+}
+
+// Return the body of a "## <name>" section, up to the next "## " heading.
+function sectionOf(text, name) {
+  const lines = text.split(/\r?\n/);
+  const head = new RegExp(`^##\\s+${name}\\b`, "i");
+  let inSection = false;
+  const out = [];
+  for (const line of lines) {
+    if (/^##\s+/.test(line)) {
+      inSection = head.test(line);
+      continue;
+    }
+    if (inSection) out.push(line);
+  }
+  return out.join("\n");
+}
+
+// Parse a GitHub-flavoured Markdown table into { headers, rows }.
+function parseTable(text) {
+  const lines = text.split(/\r?\n/).filter((l) => /^\s*\|/.test(l));
+  if (lines.length < 2) return null;
+  const cells = (line) => line.trim().replace(/^\||\|$/g, "").split("|").map((cl) => cl.trim());
+  const headers = cells(lines[0]);
+  const rows = [];
+  for (let i = 1; i < lines.length; i++) {
+    const row = cells(lines[i]);
+    if (row.every((cl) => /^:?-+:?$/.test(cl) || cl === "")) continue; // separator row
+    rows.push(row);
+  }
+  return { headers, rows };
+}
+
+function colIndex(headers, name) {
+  const i = headers.findIndex((h) => h.toLowerCase() === name.toLowerCase());
+  return i < 0 ? 0 : i;
+}
+
+// Capability names referenced as `specs/<cap>` (placeholder <...> ignored).
+function referencedCapabilities(text) {
+  const out = new Set();
+  for (const m of text.matchAll(/specs\/([a-z][a-z0-9-]*)/g)) out.add(m[1]);
+  return [...out];
+}
+
+function ensureDoctrinaProject(projectRoot) {
+  if (!exists(path.join(projectRoot, ".doctrina"))) {
+    throw new Error("not a Doctrina project (no .doctrina/ in cwd). Run `doctrina init` first.");
+  }
+}
+
+export const help = `
+Usage: doctrina contract <subcommand> [args]
+
+Own the integration/runtime surface no single capability spec owns:
+the port map, the environment contract, and API/WS/event interfaces.
+
+Subcommands:
+  new <name>          Scaffold .doctrina/contracts/<name>.md and index it
+  list                One line per contract: id, status, last updated
+  check [<name>]      Verify the mechanically checkable parts: no two
+                      services share a port, every declared env var exists
+                      in .env.example, and every referenced spec exists.
+                      Exits 1 on errors (port collisions, missing specs).
+`;

package/src/commands/coverage.js

@@ -0,0 +1,179 @@
+import path from "node:path";
+import process from "node:process";
+import { readdirSync } from "node:fs";
+import { exists, isDir, isFile, read, relPath } from "../lib/fs-ops.js";
+import { flagBool } from "../lib/args.js";
+import { c } from "../lib/colors.js";
+
+// Traceability report: how many acceptance criteria cite an artifact or
+// test that actually exists on disk. Doctrina otherwise has no link
+// between what a spec promises and what proves it — this command makes
+// that link a first-class, measurable signal (the gap the framework was
+// criticised for: validating form, never truth).
+//
+// Convention: each numbered acceptance criterion may cite its evidence as
+// a backtick path span, e.g.
+//   1. Returns HTTP 429 above the quota — verified by `test/quota.test.ts`.
+// A criterion is "covered" when at least one cited path resolves to a
+// file. A cited path that does not resolve is "dangling" (broken
+// traceability) and reported separately. Criteria with no cited path are
+// "bare" — the spec promises something nothing is shown to satisfy.
+
+export async function run(_positional, flags) {
+  const projectRoot = process.cwd();
+  if (!exists(path.join(projectRoot, ".doctrina"))) {
+    throw new Error("not a Doctrina project (no .doctrina/ in cwd). Run `doctrina init` first.");
+  }
+  const strict = flagBool(flags, "strict", false);
+
+  const specsDir = path.join(projectRoot, ".doctrina", "specs");
+  const reports = [];
+  if (isDir(specsDir)) {
+    for (const cap of readdirSync(specsDir).sort()) {
+      const specPath = path.join(specsDir, cap, "spec.md");
+      if (!isFile(specPath)) continue;
+      const criteria = extractAcceptanceCriteria(read(specPath));
+      if (criteria.length === 0) continue;
+      const rows = criteria.map((crit, i) => classify(crit, i + 1, projectRoot, path.dirname(specPath)));
+      reports.push({ cap, specPath, rows });
+    }
+  }
+
+  if (reports.length === 0) {
+    console.log(c.gray("no acceptance criteria found under .doctrina/specs/"));
+    return 0;
+  }
+
+  let totalCriteria = 0;
+  let totalCovered = 0;
+  let totalDangling = 0;
+
+  console.log(c.bold("Coverage") + c.gray(" — acceptance criteria with linked evidence:"));
+  console.log("");
+
+  for (const rep of reports) {
+    const covered = rep.rows.filter((r) => r.kind === "covered").length;
+    const dangling = rep.rows.filter((r) => r.kind === "dangling").length;
+    totalCriteria += rep.rows.length;
+    totalCovered += covered;
+    totalDangling += dangling;
+
+    const danglingNote = dangling > 0 ? c.yellow(`  (${dangling} dangling)`) : "";
+    console.log(`  ${c.cyan(rep.cap.padEnd(20))} ${covered}/${rep.rows.length} criteria${danglingNote}`);
+    for (const r of rep.rows) {
+      if (r.kind === "covered") continue;
+      if (r.kind === "bare") {
+        console.log(`    ${c.red("✗")} #${r.n}  no evidence linked — cite the file/test that proves it in backticks`);
+      } else {
+        console.log(`    ${c.yellow("!")} #${r.n}  evidence not found on disk: ${r.missing.map((m) => `\`${m}\``).join(", ")}`);
+      }
+    }
+  }
+
+  const pct = totalCriteria === 0 ? 100 : Math.round((totalCovered / totalCriteria) * 100);
+  console.log("");
+  const summary = `${totalCovered} of ${totalCriteria} acceptance criteria across ${reports.length} spec${reports.length === 1 ? "" : "s"} have linked evidence (${pct}%)`;
+  const clean = totalCovered === totalCriteria && totalDangling === 0;
+  if (clean) {
+    console.log(c.green("ok") + " " + summary);
+    return 0;
+  }
+  const danglingSummary = totalDangling > 0 ? `, ${totalDangling} dangling` : "";
+  console.log((strict ? c.red("fail") : c.yellow("gap")) + " " + summary + danglingSummary);
+  // A report by default (exit 0); a gate under --strict (exit 1 for CI).
+  return strict ? 1 : 0;
+}
+
+// Pull the numbered items out of the "## Acceptance criteria" section.
+// Each item may span multiple lines (continuation prose); accumulate until
+// the next number or the next "## " heading. Returns an array of strings.
+function extractAcceptanceCriteria(text) {
+  const lines = text.split(/\r?\n/);
+  const out = [];
+  let inSection = false;
+  let buf = null;
+  const flush = () => {
+    if (buf !== null) out.push(buf.trim());
+    buf = null;
+  };
+  for (const line of lines) {
+    if (/^##\s+/.test(line)) {
+      // Entering or leaving a section.
+      if (inSection) {
+        flush();
+        inSection = false;
+      }
+      if (/^##\s+Acceptance criteria\b/i.test(line)) inSection = true;
+      continue;
+    }
+    if (!inSection) continue;
+    if (/^\s*\d+\.\s+/.test(line)) {
+      flush();
+      buf = line.replace(/^\s*\d+\.\s+/, "");
+    } else if (buf !== null) {
+      // Continuation line of the current criterion.
+      if (line.trim() === "") buf += " ";
+      else buf += " " + line.trim();
+    }
+  }
+  flush();
+  // Drop empty placeholder items (a lone "1." with no text).
+  return out.filter((s) => s.length > 0);
+}
+
+// Decide whether a single criterion is covered, dangling, or bare.
+function classify(criterion, n, projectRoot, specDir) {
+  const cited = extractBacktickPaths(criterion);
+  if (cited.length === 0) return { kind: "bare", n };
+  const missing = [];
+  let resolved = 0;
+  for (const token of cited) {
+    const candidates = [
+      path.resolve(projectRoot, token),
+      path.resolve(specDir, token),
+    ];
+    if (candidates.some(exists)) resolved += 1;
+    else missing.push(token);
+  }
+  if (resolved > 0) return { kind: "covered", n };
+  return { kind: "dangling", n, missing };
+}
+
+// Backtick spans that look like repository file paths. Mirrors the
+// validate stale-link heuristic: a token is a path if it has a slash or a
+// file extension and is not a URL/placeholder.
+function extractBacktickPaths(text) {
+  const out = new Set();
+  for (const m of text.matchAll(/`([^`]+)`/g)) {
+    const token = m[1].trim();
+    if (looksLikePath(token)) out.add(token);
+  }
+  return [...out];
+}
+
+function looksLikePath(s) {
+  if (!s) return false;
+  if (/^(https?:|mailto:|ftp:|#|@)/i.test(s)) return false;
+  if (/[\s<>*?{}]/.test(s)) return false;
+  const hasSlash = s.includes("/");
+  const hasExt = /\.[a-z0-9]{1,8}$/i.test(s);
+  if (!hasSlash && !hasExt) return false;
+  if (s.startsWith("-")) return false;
+  return true;
+}
+
+export const help = `
+Usage: doctrina coverage [--strict]
+
+Report how many acceptance criteria across .doctrina/specs/ cite an
+artifact or test that exists on disk. Each numbered criterion may cite
+its evidence as a backtick path span, e.g. \`test/quota.test.ts\`.
+
+A criterion is covered when at least one cited path resolves to a file,
+dangling when a cited path is missing on disk, and bare when nothing is
+cited. Read-only.
+
+Flags:
+  --strict   Exit 1 when any criterion is bare or dangling (CI gate).
+             Without it the command always exits 0 (a report).
+`;