doctrina-cli 0.4.0 → 0.8.0

package/src/commands/verify.js

@@ -1,8 +1,10 @@
 import path from "node:path";
 import process from "node:process";
+import { readdirSync } from "node:fs";
 import { spawnSync } from "node:child_process";
-import { exists, isFile, read, write, relPath } from "../lib/fs-ops.js";
-import { flagBool } from "../lib/args.js";
+import { exists, isDir, isFile, read, write, relPath } from "../lib/fs-ops.js";
+import { flagBool, flagString } from "../lib/args.js";
+import { today } from "../lib/dates.js";
 import { c } from "../lib/colors.js";
 
 // The build/verify gate `validate` is not. `validate` checks the shape of
@@ -14,6 +16,7 @@ import { c } from "../lib/colors.js";
 // `.doctrina/verify.json`, and `verify` runs exactly that, in order.
 
 const CONFIG_REL = ".doctrina/verify.json";
+const SIGNOFF_REL = ".doctrina/verify.signoffs.json";
 
 const STARTER = {
   $comment:
@@ -32,6 +35,17 @@ export async function run(_positional, flags) {
     throw new Error("not a Doctrina project (no .doctrina/ in cwd). Run `doctrina init` first.");
   }
 
+  // --clean is the reproducibility lint (review G4): `verify` runs the
+  // declared checks against the *current* disk, so a repo that only works
+  // because a previous run generated a Prisma client or built a workspace's
+  // dist still passes — "verify green" ≠ "passes from a clean checkout".
+  // This is the static half of that gap: it flags the footguns that make a
+  // fresh `npm install` differ from the dirty machine, without doing a real
+  // (slow, package-manager-specific) clean install.
+  if (flagBool(flags, "clean", false)) {
+    return reproducibilityLint(projectRoot);
+  }
+
   const configPath = path.join(projectRoot, CONFIG_REL);
 
   // --init scaffolds a starter config so the gate is one edit away.
@@ -68,8 +82,11 @@ export async function run(_positional, flags) {
     return 1;
   }
   for (const ch of checks) {
-    if (!ch || typeof ch.run !== "string" || ch.run.trim() === "") {
-      console.error(c.red("error:") + ` every check in ${CONFIG_REL} needs a non-empty "run" string`);
+    // A "manual" check is the qualitative gate (review 2026-06-27 feature #7):
+    // a DoD item judged by a human/eval, recorded as a sign-off, not run as a
+    // command — so it needs no `run`. Every other check still needs one.
+    if (!ch || (ch.type !== "manual" && (typeof ch.run !== "string" || ch.run.trim() === ""))) {
+      console.error(c.red("error:") + ` every check in ${CONFIG_REL} needs a non-empty "run" string (or "type": "manual")`);
       return 1;
     }
   }
@@ -78,21 +95,69 @@ export async function run(_positional, flags) {
     return 1;
   }
 
+  // Sign-off store for manual checks: { "<check name>": { date, note } }.
+  const signoffPath = path.join(projectRoot, SIGNOFF_REL);
+  let signoffs = {};
+  if (isFile(signoffPath)) {
+    try { signoffs = JSON.parse(read(signoffPath)) ?? {}; } catch { signoffs = {}; }
+  }
+
+  // --signoff "<name>=<note>" records a manual check's human/eval sign-off
+  // (date stamped today) and exits. The name must be a declared manual check.
+  const signoffArg = flagString(flags, "signoff");
+  if (signoffArg !== undefined) {
+    const eq = String(signoffArg).indexOf("=");
+    const name = (eq >= 0 ? signoffArg.slice(0, eq) : signoffArg).trim();
+    const note = eq >= 0 ? signoffArg.slice(eq + 1).trim() : "";
+    const target = checks.find((ch) => (ch.name ?? "") === name && ch.type === "manual");
+    if (!target) {
+      console.error(c.red("error:") + ` no manual check named "${name}" in ${CONFIG_REL}`);
+      const manualNames = checks.filter((ch) => ch.type === "manual").map((ch) => ch.name);
+      console.error(c.gray("hint: ") + (manualNames.length
+        ? `manual checks: ${manualNames.join(", ")}`
+        : `add one: { "name": "${name || "quality"}", "type": "manual", "rubric": "<the question>" }`));
+      return 1;
+    }
+    signoffs[name] = { date: today(), note };
+    write(signoffPath, JSON.stringify(signoffs, null, 2) + "\n", { force: true });
+    console.log(c.green("signed off") + ` ${name} on ${today()}${note ? `: ${note}` : ""}`);
+    return 0;
+  }
+
   // --list prints the configured checks without running them.
   if (flagBool(flags, "list", false)) {
     console.log(c.bold("Verify checks") + c.gray(` (from ${CONFIG_REL}):`));
     console.log("");
     checks.forEach((ch, i) => {
-      console.log(`  ${i + 1}. ${c.cyan((ch.name ?? "check").padEnd(16))} ${c.gray(ch.run)}`);
+      const what = ch.type === "manual" ? c.gray(`manual${ch.rubric ? " — " + ch.rubric : ""}`) : c.gray(ch.run);
+      console.log(`  ${i + 1}. ${c.cyan((ch.name ?? "check").padEnd(16))} ${what}`);
     });
     return 0;
   }
 
+  const strict = flagBool(flags, "strict", false);
   console.log(c.bold("doctrina verify") + c.gray(` — ${checks.length} check${checks.length === 1 ? "" : "s"} from ${CONFIG_REL}`));
   const results = [];
   for (const ch of checks) {
     const name = ch.name ?? "check";
     console.log("");
+
+    // Manual (qualitative) check: pass if signed off, else pending. Pending is
+    // non-blocking by default (a report) and fails only under --strict, so CI
+    // can require the human/eval sign-off without blocking local runs.
+    if (ch.type === "manual") {
+      console.log(c.gray(`──── ${name}: `) + c.gray(`manual${ch.rubric ? " — " + ch.rubric : ""}`));
+      const so = signoffs[name];
+      if (so && so.date) {
+        console.log(c.green(`✓ ${name}`) + c.gray(` — signed off ${so.date}${so.note ? `: ${so.note}` : ""}`));
+        results.push({ name, ok: true, kind: "manual" });
+      } else {
+        console.log(c.yellow(`○ ${name} — pending sign-off`) + c.gray(` (doctrina verify --signoff "${name}=<note>")`));
+        results.push({ name, ok: false, kind: "manual", pending: true });
+      }
+      continue;
+    }
+
     const where = ch.cwd ? c.gray(` [${ch.cwd}]`) : "";
     console.log(c.gray(`──── ${name}: `) + ch.run + where);
     // Run through the shell so declared commands can use pipes, &&, env,
@@ -113,41 +178,197 @@ export async function run(_positional, flags) {
     } else {
       console.log(ok ? c.green(`✓ ${name}`) : c.red(`✗ ${name} (exit ${res.status})`));
     }
-    results.push({ name, ok });
+    results.push({ name, ok, kind: "command" });
     // Fail fast is tempting, but running every check surfaces all breakage
     // in one pass — more useful for an agent fixing the gap.
   }
 
+  const cmdFailed = results.filter((r) => r.kind === "command" && !r.ok);
+  const pending = results.filter((r) => r.pending);
   const passed = results.filter((r) => r.ok).length;
   console.log("");
-  if (passed === results.length) {
-    console.log(c.green("ok") + ` ${passed}/${results.length} checks passed`);
+  // The gate fails on any failed command check, or (only under --strict) any
+  // manual check still awaiting sign-off. Pending manual checks are otherwise
+  // a non-blocking report.
+  const failGate = cmdFailed.length > 0 || (strict && pending.length > 0);
+  const pendNote = pending.length > 0 ? c.gray(` (${pending.length} manual pending)`) : "";
+  if (!failGate) {
+    console.log(c.green("ok") + ` ${passed}/${results.length} checks passed${pendNote}`);
+    return 0;
+  }
+  const reasons = [];
+  if (cmdFailed.length > 0) reasons.push(`failed: ${cmdFailed.map((r) => r.name).join(", ")}`);
+  if (strict && pending.length > 0) reasons.push(`pending sign-off: ${pending.map((r) => r.name).join(", ")}`);
+  console.log(c.red("fail") + ` ${passed}/${results.length} checks passed — ${reasons.join("; ")}`);
+  return 1;
+}
+
+// Static reproducibility lint: walk the project's package.json files and
+// report the two "works on my machine" footguns the review hit — a package
+// whose entry points live in a build-output dir with nothing that builds it
+// on install, and a codegen dependency (Prisma) with no install hook that
+// generates. Returns 0 when clean, 1 when any risk is found. Pure read.
+function reproducibilityLint(projectRoot) {
+  const pkgPaths = findPackageJsons(projectRoot);
+  console.log(c.bold("doctrina verify --clean") + c.gray(" — reproducibility lint (static, not a real fresh install)"));
+  console.log("");
+
+  if (pkgPaths.length === 0) {
+    console.log(c.gray("no package.json found — nothing this lint can check (it knows Node/npm footguns)"));
+    return 0;
+  }
+
+  const findings = [];
+  for (const pkgPath of pkgPaths) {
+    const rel = relPath(projectRoot, pkgPath);
+    let pkg;
+    try {
+      pkg = JSON.parse(read(pkgPath));
+    } catch (err) {
+      findings.push(`${rel}: not valid JSON (${err.message})`);
+      continue;
+    }
+    const scripts = pkg.scripts ?? {};
+    const hasInstallBuild = typeof scripts.prepare === "string" || typeof scripts.prepack === "string";
+
+    // 1. Entry point into a build output with nothing to build it on install.
+    const built = entryIntoBuildDir(pkg);
+    if (built && !hasInstallBuild) {
+      findings.push(
+        `${rel}: ${built.field} → \`${built.value}\` is a build output, but no "prepare"/"prepack" ` +
+        `script builds it on install — a fresh install/clone won't have it (add a prepare script, or commit the output)`,
+      );
+    }
+
+    // 2. Codegen dependency with no install hook that generates.
+    const deps = {
+      ...pkg.dependencies, ...pkg.devDependencies,
+      ...pkg.peerDependencies, ...pkg.optionalDependencies,
+    };
+    for (const [dep, gen] of Object.entries(CODEGEN_DEPS)) {
+      if (!(dep in deps)) continue;
+      const installHook = `${scripts.postinstall ?? ""} ${scripts.prepare ?? ""}`;
+      if (!gen.test(installHook)) {
+        findings.push(
+          `${rel}: depends on "${dep}" but no "postinstall"/"prepare" runs its codegen ` +
+          `(\`${gen.source.replace(/\\s\+/g, " ")}\`) — a fresh install has no generated output`,
+        );
+      }
+    }
+  }
+
+  if (findings.length === 0) {
+    console.log(c.green("ok") + ` ${pkgPaths.length} package.json file${pkgPaths.length === 1 ? "" : "s"} — no reproducibility risks found`);
     return 0;
   }
-  const failed = results.filter((r) => !r.ok).map((r) => r.name).join(", ");
-  console.log(c.red("fail") + ` ${passed}/${results.length} checks passed — failed: ${failed}`);
+  for (const f of findings) console.log(`  ${c.yellow("!")} ${f}`);
+  console.log("");
+  console.log(c.red("fail") + ` ${findings.length} reproducibility risk${findings.length === 1 ? "" : "s"} — a clean checkout may not build`);
   return 1;
 }
 
+// Known codegen dependencies → the command an install hook must run so a
+// fresh install produces their generated output.
+const CODEGEN_DEPS = {
+  "@prisma/client": /prisma\s+generate/,
+  "prisma": /prisma\s+generate/,
+};
+
+const BUILD_DIR_RE = /(?:^|\/)(?:dist|build|out)\//;
+
+// The first entry-point field that points into a build-output directory, or
+// null. Scans main/module/types/typings, bin (string or map), and exports
+// (recursively, string leaves only).
+function entryIntoBuildDir(pkg) {
+  for (const field of ["main", "module", "types", "typings"]) {
+    if (typeof pkg[field] === "string" && BUILD_DIR_RE.test(pkg[field])) {
+      return { field, value: pkg[field] };
+    }
+  }
+  if (typeof pkg.bin === "string" && BUILD_DIR_RE.test(pkg.bin)) return { field: "bin", value: pkg.bin };
+  if (pkg.bin && typeof pkg.bin === "object") {
+    for (const v of Object.values(pkg.bin)) {
+      if (typeof v === "string" && BUILD_DIR_RE.test(v)) return { field: "bin", value: v };
+    }
+  }
+  const fromExports = scanExports(pkg.exports);
+  if (fromExports) return { field: "exports", value: fromExports };
+  return null;
+}
+
+function scanExports(node) {
+  if (typeof node === "string") return BUILD_DIR_RE.test(node) ? node : null;
+  if (node && typeof node === "object") {
+    for (const v of Object.values(node)) {
+      const hit = scanExports(v);
+      if (hit) return hit;
+    }
+  }
+  return null;
+}
+
+// Bounded walk for package.json files: skip dependency, build, and VCS
+// directories so the lint stays fast and ignores vendored manifests.
+const LINT_SKIP_DIRS = new Set([
+  ".git", "node_modules", "dist", "build", "out", "vendor", ".next",
+  "coverage", ".venv", "venv", "__pycache__", "target", ".doctrina",
+]);
+
+function findPackageJsons(projectRoot) {
+  const found = [];
+  const stack = [projectRoot];
+  while (stack.length) {
+    const dir = stack.pop();
+    let entries;
+    try {
+      entries = readdirSync(dir, { withFileTypes: true });
+    } catch {
+      continue;
+    }
+    for (const entry of entries) {
+      const full = path.join(dir, entry.name);
+      if (entry.isDirectory()) {
+        if (!LINT_SKIP_DIRS.has(entry.name) && !entry.name.startsWith(".")) stack.push(full);
+      } else if (entry.name === "package.json") {
+        found.push(full);
+      }
+    }
+  }
+  return found.sort();
+}
+
 export const help = `
-Usage: doctrina verify [--list] [--init] [--force]
+Usage: doctrina verify [--list] [--init] [--clean] [--strict] [--signoff "<name>=<note>"] [--force]
 
 Run the project-declared build/verify checks from ${CONFIG_REL} in order,
 streaming their output, and exit non-zero if any check fails. This is the
 real "does the code work" gate, separate from the structural \`validate\`.
 
 ${CONFIG_REL} shape (an optional per-check "cwd", relative to the project
-root, targets a sub-package in a monorepo):
+root, targets a sub-package in a monorepo; a "manual" check is the
+qualitative gate — judged by a human/eval, recorded as a sign-off, not run):
   {
     "checks": [
       { "name": "typecheck", "run": "tsc --noEmit", "cwd": "packages/api" },
       { "name": "test",      "run": "npm test" },
-      { "name": "build",     "run": "npm run build" }
+      { "name": "build",     "run": "npm run build" },
+      { "name": "chronicle", "type": "manual", "rubric": "is the chronicle enjoyable to read?" }
     ]
   }
 
+A manual check passes when it has been signed off and is otherwise reported
+as "pending" — non-blocking by default, failing only under --strict (so CI
+can require the sign-off). Sign-offs are stored in ${SIGNOFF_REL}.
+
 Flags:
   --init     Scaffold a starter ${CONFIG_REL} (refuses to overwrite without --force)
   --list     Print the configured checks without running them
+  --clean    Don't run checks; lint the project's package.json files for
+             reproducibility footguns (entry points in a build dir with no
+             prepare/prepack; a Prisma dep with no generate on install) so
+             "verify green" can't hide a clean checkout that won't build.
+  --strict   Fail the gate when a manual check is still pending sign-off
+  --signoff "<name>=<note>"
+             Record today's sign-off for a manual check, then exit
   --force    With --init, overwrite an existing config
 `;

package/src/commands/watch.js

@@ -0,0 +1,97 @@
+import path from "node:path";
+import process from "node:process";
+import { watch as fsWatch } from "node:fs";
+import { exists } from "../lib/fs-ops.js";
+import { flagBool } from "../lib/args.js";
+import { c } from "../lib/colors.js";
+import * as validate from "./validate.js";
+import * as next from "./next.js";
+
+// Continuous keep-in-sync (review 2026-06-27 passive-user feature #4): re-run
+// `validate --fix` (heal drift, migrate the stamp) and reprint `doctrina next`
+// whenever an artifact changes, so the index stays synced and the agent stays
+// oriented without anyone invoking a command. Passive by construction. The
+// pass is debounced and ignores writes to index.json (which `--fix` itself
+// makes) so it never loops on its own output. `--once` runs a single pass and
+// exits — the testable, scriptable form.
+
+export async function run(_positional, flags) {
+  const projectRoot = process.cwd();
+  const dot = path.join(projectRoot, ".doctrina");
+  if (!exists(dot)) {
+    throw new Error("not a Doctrina project (no .doctrina/ in cwd). Run `doctrina init` first.");
+  }
+
+  if (flagBool(flags, "once", false)) {
+    return pass(projectRoot);
+  }
+
+  console.log(c.bold("doctrina watch") + c.gray(" — validate --fix + next on every change. Ctrl-C to stop."));
+  await pass(projectRoot);
+
+  let timer = null;
+  let running = false;
+  const schedule = () => {
+    if (timer) clearTimeout(timer);
+    timer = setTimeout(async () => {
+      if (running) return;
+      running = true;
+      console.log("");
+      console.log(c.gray(`──── ${new Date().toLocaleTimeString()} change detected`));
+      await pass(projectRoot);
+      running = false;
+    }, 300);
+  };
+
+  let watcher;
+  try {
+    watcher = fsWatch(dot, { recursive: true }, (_event, filename) => {
+      const name = (filename ?? "").replace(/\\/g, "/");
+      // Ignore the index the fix itself rewrites (would self-trigger forever).
+      if (name.endsWith("index.json")) return;
+      schedule();
+    });
+  } catch (err) {
+    console.error(c.red("error:") + ` could not start the watcher: ${err.message}`);
+    return 1;
+  }
+
+  // Keep the process alive until interrupted.
+  return await new Promise((resolve) => {
+    const stop = () => {
+      if (watcher) watcher.close();
+      console.log("");
+      console.log(c.gray("watch stopped."));
+      resolve(0);
+    };
+    process.on("SIGINT", stop);
+    process.on("SIGTERM", stop);
+  });
+}
+
+// One pass: heal drift, then reprint the next actions. Never throws.
+async function pass(projectRoot) {
+  try {
+    await validate.run([], new Map([["fix", true]]));
+    console.log("");
+    await next.run([], new Map());
+  } catch (err) {
+    console.error(c.red("error:") + ` ${err.message}`);
+    return 1;
+  }
+  return 0;
+}
+
+export const help = `
+Usage: doctrina watch [--once]
+
+Watch the .doctrina/ tree and, on every change, run \`doctrina validate
+--fix\` (heal index drift, migrate the framework stamp) and reprint
+\`doctrina next\` — so the index stays in sync and the agent stays oriented
+without anyone invoking a command. Debounced; ignores the index.json the
+fix itself rewrites. Runs until interrupted (Ctrl-C).
+
+Options:
+  --once     Run a single pass (validate --fix + next) and exit, instead of
+             watching. The scriptable / testable form.
+`;

package/src/commands/why.js

@@ -0,0 +1,182 @@
+import path from "node:path";
+import process from "node:process";
+import { readdirSync } from "node:fs";
+import { exists, isDir, isFile, read } from "../lib/fs-ops.js";
+import { specHeader, listHeader } from "../lib/scan.js";
+import { c } from "../lib/colors.js";
+import { suggest } from "../lib/suggest.js";
+
+// Provenance explainer (review 2026-06-27 passive-user feature #5): answer
+// "why does this capability exist / why was it built this way?" by assembling
+// the chain the framework already records — product intent (the [SC1] anchors
+// it Realizes) → the capability's purpose → the acceptance criteria that prove
+// it → the accepted ADRs that decided it — into one read. The human (or agent)
+// asks; the tool answers from the artifacts, instead of grepping by hand.
+// Read-only. Builds on the Realizes:/trace provenance (ADR 0006/0011).
+
+export async function run(positional, _flags) {
+  const cap = positional[0];
+  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 specsDir = path.join(projectRoot, ".doctrina", "specs");
+  const known = isDir(specsDir) ? readdirSync(specsDir).filter((e) => isFile(path.join(specsDir, e, "spec.md"))) : [];
+
+  if (!cap) {
+    console.error(c.red("error:") + " why requires a <capability>");
+    if (known.length) console.error(c.gray("known: ") + known.sort().join(", "));
+    return 2;
+  }
+  const specPath = path.join(specsDir, cap, "spec.md");
+  if (!isFile(specPath)) {
+    console.error(c.red("error:") + ` no spec for capability "${cap}"`);
+    const guess = suggest(cap, known);
+    if (guess) console.error(c.gray("hint: ") + `did you mean "${guess}"?`);
+    else if (known.length) console.error(c.gray("known: ") + known.sort().join(", "));
+    return 1;
+  }
+
+  const text = read(specPath);
+  console.log(c.bold(`Why "${cap}"`) + c.gray(" — provenance chain (intent → capability → proof → decisions)"));
+  console.log("");
+
+  // 1. Product intent it realizes.
+  const realizesRaw = specHeader(text, "Realizes");
+  const anchorIds = realizesRaw ? (realizesRaw.match(/[A-Z]+\d+/g) ?? []) : [];
+  console.log(c.bold("  Product intent"));
+  if (realizesRaw && /^n\/a\b/i.test(realizesRaw.trim())) {
+    console.log(`    ${c.gray("n/a — " + realizesRaw.trim().replace(/^n\/a\s*[—-]?\s*/i, ""))}`);
+  } else if (anchorIds.length === 0) {
+    console.log(`    ${c.yellow("none declared")} ${c.gray("— add a **Realizes:** header (doctrina trace)")}`);
+  } else {
+    const anchors = productAnchors(projectRoot);
+    for (const id of anchorIds) {
+      const line = anchors.get(id);
+      console.log(`    ${c.cyan(id)}  ${line ? line : c.yellow("(no matching anchor in product.md)")}`);
+    }
+  }
+
+  // 2. The capability itself.
+  console.log("");
+  console.log(c.bold("  Capability"));
+  const status = specHeader(text, "Status") ?? "—";
+  const impl = specHeader(text, "Implementation") ?? "—";
+  console.log(`    ${c.gray("status:")} ${status}   ${c.gray("implementation:")} ${impl}`);
+  const purpose = sectionParagraph(text, "Purpose");
+  if (purpose) console.log("    " + purpose.replace(/\s+/g, " ").trim());
+
+  // 3. The proof (acceptance criteria with cited evidence).
+  console.log("");
+  console.log(c.bold("  Proof"));
+  const criteria = acceptanceWithEvidence(text);
+  if (criteria.length === 0) {
+    console.log(`    ${c.gray("no acceptance criteria declared")}`);
+  } else {
+    for (const cr of criteria) {
+      const proof = cr.proof.length ? c.gray(cr.proof.map((p) => `\`${p}\``).join(", ")) : c.yellow("no evidence cited");
+      console.log(`    ${cr.mark} #${cr.n}  ${proof}`);
+    }
+  }
+
+  // 4. The decisions that shaped it (accepted ADRs naming the capability).
+  console.log("");
+  console.log(c.bold("  Decisions"));
+  const adrs = decisionsMentioning(projectRoot, cap);
+  if (adrs.length === 0) {
+    console.log(`    ${c.gray("no accepted ADR names this capability")}`);
+  } else {
+    for (const a of adrs) console.log(`    ${c.cyan("ADR " + a.id)}  ${a.title}`);
+  }
+
+  return 0;
+}
+
+// Map of anchor id -> the product.md bullet text that declares it.
+function productAnchors(projectRoot) {
+  const out = new Map();
+  const p = path.join(projectRoot, ".doctrina", "product.md");
+  if (!isFile(p)) return out;
+  for (const line of read(p).split(/\r?\n/)) {
+    const m = line.match(/^\s*[-*]\s+\[([A-Z]+\d+)\]\s+(.+)$/);
+    if (m && !out.has(m[1])) out.set(m[1], m[2].trim());
+  }
+  return out;
+}
+
+// First non-comment paragraph under a "## <name>" heading.
+function sectionParagraph(text, name) {
+  const lines = text.split(/\r?\n/);
+  let inSection = false;
+  const buf = [];
+  for (const line of lines) {
+    if (/^##\s+/.test(line)) {
+      if (inSection) break;
+      if (new RegExp(`^##\\s+${name}\\b`, "i").test(line)) inSection = true;
+      continue;
+    }
+    if (!inSection) continue;
+    if (/^\s*<!--/.test(line) || /-->/.test(line)) continue;
+    if (line.trim() === "") {
+      if (buf.length) break;
+      continue;
+    }
+    buf.push(line.trim());
+  }
+  return buf.join(" ");
+}
+
+// Numbered acceptance criteria with their [mark] and any backtick proof paths.
+function acceptanceWithEvidence(text) {
+  const lines = text.split(/\r?\n/);
+  let inSection = false;
+  const out = [];
+  for (const line of lines) {
+    if (/^##\s+/.test(line)) {
+      inSection = /^##\s+Acceptance criteria\b/i.test(line);
+      continue;
+    }
+    if (!inSection) continue;
+    const m = line.match(/^\s*(\d+)\.\s+(.*)$/);
+    if (!m) continue;
+    const body = m[2];
+    const markMatch = body.match(/^\[([^\]]+)\]/);
+    const mark = markMatch
+      ? (/^verified/i.test(markMatch[1]) ? c.green("✓") : c.yellow("○"))
+      : c.gray("·");
+    const proof = [...body.matchAll(/`([^`]+)`/g)].map((x) => x[1]).filter((s) => s.includes("/") || /\.[a-z0-9]{1,8}$/i.test(s));
+    out.push({ n: m[1], mark, proof });
+  }
+  return out;
+}
+
+// Accepted ADRs whose body names the capability (word-ish boundary).
+function decisionsMentioning(projectRoot, cap) {
+  const adrDir = path.join(projectRoot, ".doctrina", "decisions");
+  const out = [];
+  if (!isDir(adrDir)) return out;
+  const re = new RegExp(`\\b${cap.replace(/[-]/g, "[- ]?")}\\b`, "i");
+  for (const f of readdirSync(adrDir).sort()) {
+    const m = f.match(/^(\d{4})-.*\.md$/);
+    if (!m) continue;
+    const text = read(path.join(adrDir, f));
+    const status = (listHeader(text, "Status") ?? "").toLowerCase();
+    if (status !== "accepted") continue;
+    if (!re.test(text)) continue;
+    const titleMatch = text.match(/^#\s+ADR\s+\d{4}\s*[—-]\s*(.+)$/m);
+    out.push({ id: m[1], title: titleMatch ? titleMatch[1].trim() : f });
+  }
+  return out;
+}
+
+export const help = `
+Usage: doctrina why <capability>
+
+Explain a capability's provenance by assembling the chain Doctrina already
+records into one read: the product intent it **Realizes:** ([SC1] anchors),
+the capability's purpose and status, the acceptance criteria that prove it
+(with cited evidence), and the accepted ADRs that name it. Read-only.
+
+Builds on the intent provenance (ADR 0006/0011) — answer "why was X built,
+and built this way?" without grepping the tree by hand.
+`;