doctrina-cli 0.10.0 → 0.12.0

package/src/commands/context.js

@@ -1,20 +1,31 @@
 import path from "node:path";
 import process from "node:process";
 import { readdirSync } from "node:fs";
-import { exists, isDir, isFile, lineCount, read, relPath, walk } from "../lib/fs-ops.js";
-import { listHeader } from "../lib/scan.js";
+import { spawnSync } from "node:child_process";
+import { exists, isDir, isFile, read, relPath, walk } from "../lib/fs-ops.js";
+import { listHeader, parseDependsOn } from "../lib/scan.js";
 import { parseFrontmatter } from "./skill.js";
-import { flagBool } from "../lib/args.js";
+import { flagBool, flagString } from "../lib/args.js";
 import { c } from "../lib/colors.js";
 
 // Materialise the AGENTS.md read order as a command: print the exact
 // context pack for a task, in the order an agent should read it. This is
 // the context-engineering thesis turned into tooling — selection over
 // dumping, ranked by the documented read order.
+//
+// The pack now carries a token estimate per file (chars/4 — the standard
+// rough heuristic; the thesis the product is built on is that token spend
+// predicts performance, so the pack must be measurable in tokens, not only
+// lines). `--budget <n>` turns the estimate into a gate, and `--diff <ref>`
+// scopes the pack to what changed since a git ref — the resume-session read.
+
+const TOKEN_DIVISOR = 4;
 
 export async function run(positional, flags) {
   const capability = positional[0] ?? null;
   const concat = flagBool(flags, "concat", false);
+  const budgetRaw = flagString(flags, "budget");
+  const diffRef = flagString(flags, "diff");
   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.");
@@ -25,22 +36,43 @@ export async function run(positional, flags) {
     return 2;
   }
 
+  let budget = null;
+  if (budgetRaw !== undefined) {
+    budget = Number.parseInt(budgetRaw, 10);
+    if (!Number.isFinite(budget) || budget <= 0) {
+      console.error(c.red("error:") + ` --budget expects a positive token count, got "${budgetRaw}"`);
+      return 2;
+    }
+  }
+
+  // --diff <ref>: restrict the stable artifacts to those changed since the
+  // ref (a resuming session already carries the rest); open changes are
+  // always in — they ARE the work being resumed.
+  let changed = null;
+  if (diffRef !== undefined) {
+    changed = changedPaths(projectRoot, diffRef);
+    if (changed === null) return 1; // changedPaths printed the error
+  }
+  // git emits POSIX paths; relPath emits native separators on Windows.
+  const wanted = (rel) => changed === null || changed.has(rel.replaceAll("\\", "/"));
+
   const pack = [];
   const pushFile = (rel, note) => {
     const full = path.join(projectRoot, rel);
-    if (isFile(full)) pack.push({ rel, lines: lineCount(full), note });
+    if (!isFile(full)) return;
+    const text = read(full);
+    pack.push({ rel, lines: text.split(/\r?\n/).length, tokens: Math.round(text.length / TOKEN_DIVISOR), note });
   };
 
   // 1-2. Root rules and product truth — always first. Displayed paths are
   // POSIX strings (path.join would emit backslashes on Windows).
-  pushFile("AGENTS.md", "root rules");
-  pushFile(".doctrina/product.md", "product truth");
+  if (wanted("AGENTS.md")) pushFile("AGENTS.md", "root rules");
+  if (wanted(".doctrina/product.md")) pushFile(".doctrina/product.md", "product truth");
 
   // 3. The capability spec(s) — the current truth. With a named capability,
   //    just that one. Without one, EVERY active spec: the default orientation
   //    read previously jumped from product.md straight to the ADRs, leaving
-  //    the single source of truth out of the pack entirely (a review/debug/
-  //    question read got history but not current truth). Specs come before
+  //    the single source of truth out of the pack entirely. Specs come before
   //    open changes and ADRs, matching the documented read order.
   let specMissing = false;
   const specsRoot = path.join(projectRoot, ".doctrina", "specs");
@@ -48,17 +80,26 @@ export async function run(positional, flags) {
     const specRel = `.doctrina/specs/${capability}/spec.md`;
     if (isFile(path.join(projectRoot, specRel))) {
       pushFile(specRel, `spec: ${capability}`);
+      // Pull the declared dependencies into the pack (the machine-readable
+      // **Depends on:** header): a task on `risk-map` that builds on
+      // `reporting` needs both truths in one read. One level deep,
+      // deterministic, no cycles (each spec is pushed at most once).
+      for (const dep of parseDependsOn(read(path.join(projectRoot, specRel)))) {
+        if (dep === capability) continue;
+        const depRel = `.doctrina/specs/${dep}/spec.md`;
+        if (isFile(path.join(projectRoot, depRel))) pushFile(depRel, `dependency of ${capability}`);
+      }
     } else {
       specMissing = true;
     }
   } else if (isDir(specsRoot)) {
     for (const cap of readdirSync(specsRoot).sort()) {
       const specRel = `.doctrina/specs/${cap}/spec.md`;
-      if (isFile(path.join(projectRoot, specRel))) pushFile(specRel, `spec: ${cap}`);
+      if (wanted(specRel) && isFile(path.join(projectRoot, specRel))) pushFile(specRel, `spec: ${cap}`);
     }
   }
 
-  // 4. Open changes (their proposal, tasks, and deltas).
+  // 4. Open changes (their proposal, tasks, and deltas) — never diff-filtered.
   const changesDir = path.join(projectRoot, ".doctrina", "changes");
   if (isDir(changesDir)) {
     for (const id of readdirSync(changesDir).sort()) {
@@ -75,11 +116,15 @@ export async function run(positional, flags) {
   const adrDir = path.join(projectRoot, ".doctrina", "decisions");
   for (const f of walk(adrDir)) {
     if (!f.endsWith(".md")) continue;
+    const rel = relPath(projectRoot, f);
+    if (!wanted(rel)) continue;
     const status = (listHeader(read(f), "Status") ?? "").toLowerCase();
-    if (status === "accepted") pushFile(relPath(projectRoot, f), "accepted ADR");
+    if (status === "accepted") pushFile(rel, "accepted ADR");
   }
 
-  // 6. Skills are on-demand: list name + description, never the body.
+  // 6. Skills are on-demand: list name + description + trigger, never the
+  //    body. The `when:` line is what lets an agent fire the right skill
+  //    without loading any of them.
   const onDemand = [];
   const skillsDir = path.join(projectRoot, ".doctrina", "skills");
   for (const f of walk(skillsDir)) {
@@ -89,9 +134,13 @@ export async function run(positional, flags) {
       rel: relPath(projectRoot, f),
       name: parseFrontmatter(text, "name") ?? path.basename(f, ".md"),
       description: parseFrontmatter(text, "description") ?? "<missing description>",
+      when: parseFrontmatter(text, "when") ?? null,
     });
   }
 
+  const totalTokens = pack.reduce((sum, item) => sum + item.tokens, 0);
+  const totalLines = pack.reduce((sum, item) => sum + item.lines, 0);
+
   if (concat) {
     for (const item of pack) {
       console.log(`===== ${item.rel} (${item.note}) =====`);
@@ -99,20 +148,26 @@ export async function run(positional, flags) {
       console.log(read(path.join(projectRoot, item.rel)).trimEnd());
       console.log("");
     }
+    // Keep the pack pipeable: the budget verdict goes to stderr.
+    if (budget !== null) {
+      reportBudget(totalTokens, budget, (msg) => console.error(msg));
+    }
   } else {
-    console.log(c.bold("Context pack") + (capability ? c.gray(` (capability: ${capability})`) : "") + c.gray(" — read in this order:"));
+    const scope = diffRef !== undefined ? c.gray(` (diff vs ${diffRef})`) : "";
+    console.log(c.bold("Context pack") + (capability ? c.gray(` (capability: ${capability})`) : "") + scope + c.gray(" — read in this order:"));
     console.log("");
     pack.forEach((item, i) => {
-      console.log(`${i + 1}. ${c.cyan(item.rel.padEnd(56))} ${String(item.lines).padStart(4)} lines  ${c.gray(item.note)}`);
+      console.log(`${i + 1}. ${c.cyan(item.rel.padEnd(56))} ${String(item.lines).padStart(4)} lines ${c.gray(`~${String(item.tokens).padStart(5)} tok`)}  ${c.gray(item.note)}`);
     });
-    const total = pack.reduce((sum, item) => sum + item.lines, 0);
     console.log("");
-    console.log(c.gray(`${pack.length} files, ${total} lines total · archive excluded by design`));
+    console.log(c.gray(`${pack.length} files, ${totalLines} lines, ~${totalTokens} tokens total (chars/4) · archive excluded by design`));
+    if (budget !== null) reportBudget(totalTokens, budget, (msg) => console.log(msg));
     if (onDemand.length > 0) {
       console.log("");
-      console.log(c.bold("On-demand skills") + c.gray(" (load the body only when the task matches):"));
+      console.log(c.bold("On-demand skills") + c.gray(" (load the body only when the trigger fires):"));
       for (const s of onDemand) {
-        console.log(`   ${c.cyan(s.name.padEnd(24))} ${s.description}  ${c.gray(s.rel)}`);
+        console.log(`   ${c.cyan(s.name.padEnd(26))} ${s.description}`);
+        if (s.when) console.log(`   ${" ".repeat(26)} ${c.gray(`when: ${s.when}`)}`);
       }
     }
   }
@@ -121,21 +176,59 @@ export async function run(positional, flags) {
     console.error("");
     console.error(c.yellow("warn:") + ` no spec for capability "${capability}" — create one with \`doctrina spec new ${capability}\``);
   }
+  if (budget !== null && totalTokens > budget) return 1;
   return 0;
 }
 
+function reportBudget(totalTokens, budget, log) {
+  if (totalTokens > budget) {
+    log(c.red("over budget") + ` ~${totalTokens} tokens > ${budget} — narrow the pack: name a capability, use --diff <ref>, split oversized specs`);
+  } else {
+    log(c.green("within budget") + c.gray(` ~${totalTokens} of ${budget} tokens (${Math.round((totalTokens / budget) * 100)}%)`));
+  }
+}
+
+// Repo-relative POSIX paths changed since <ref> (worktree vs ref, plus
+// untracked files). Returns null (after printing the error) when git or the
+// ref is unavailable — the caller exits rather than silently showing a full
+// pack the user asked to narrow.
+function changedPaths(projectRoot, ref) {
+  const run = (args) => spawnSync("git", args, { cwd: projectRoot, encoding: "utf8" });
+  const diff = run(["diff", "--name-only", ref, "--"]);
+  if (diff.status !== 0) {
+    console.error(c.red("error:") + ` git diff against "${ref}" failed${diff.stderr ? `: ${diff.stderr.trim().split("\n")[0]}` : " (not a git repository?)"}`);
+    return null;
+  }
+  const untracked = run(["ls-files", "--others", "--exclude-standard"]);
+  const out = new Set();
+  for (const chunk of [diff.stdout, untracked.status === 0 ? untracked.stdout : ""]) {
+    for (const line of chunk.split(/\r?\n/)) {
+      const p = line.trim();
+      if (p) out.add(p);
+    }
+  }
+  return out;
+}
+
 export const help = `
-Usage: doctrina context [<capability>] [--concat]
+Usage: doctrina context [<capability>] [--concat] [--budget <tokens>] [--diff <ref>]
 
 Print the exact context pack for a task, in the documented read
 order: AGENTS.md, product.md, the capability spec (when given —
-otherwise every active spec, so the current truth is never absent),
-open changes, accepted ADRs. Skills are listed name + description only
-— they are on-demand by design. The change archive is excluded.
+otherwise every active spec), open changes, accepted ADRs. Skills are
+listed name + description + when-trigger only — they are on-demand by
+design. The change archive is excluded. Every file carries a token
+estimate (chars/4) and the pack reports its total.
 
 Flags:
-  --concat   Print the file contents (with separators) instead of the
-             file list — ready to pipe into an agent.
+  --concat          Print the file contents (with separators) instead of
+                    the list — ready to pipe into an agent. The budget
+                    verdict (if any) goes to stderr, keeping stdout pure.
+  --budget <n>      Token budget for the pack: prints over/under and
+                    exits 1 when the estimate exceeds it (a context gate).
+  --diff <ref>      Scope the stable artifacts (AGENTS.md, product.md,
+                    specs, ADRs) to those changed since the git ref; open
+                    changes are always included. The resume-session read.
 
-Read-only; always exits 0.
+Read-only; exits 0 (or 1 when over --budget).
 `;

package/src/commands/coverage.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, isDir, isFile, read, relPath } from "../lib/fs-ops.js";
-import { flagBool } from "../lib/args.js";
+import { specHeader } from "../lib/scan.js";
+import { flagBool, flagString } from "../lib/args.js";
 import { c } from "../lib/colors.js";
 
 // Traceability report: how many acceptance criteria cite an artifact or
@@ -26,21 +28,29 @@ export async function run(_positional, flags) {
     throw new Error("not a Doctrina project (no .doctrina/ in cwd). Run `doctrina init` first.");
   }
   const strict = flagBool(flags, "strict", false);
+  const json = flagBool(flags, "json", 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 });
-    }
+  // --only <cap,cap>: scope the report/gate to specific capabilities — the
+  // hook `doctrina close` uses so one deliberately deferred spec elsewhere in
+  // the tree cannot block closing a change that never touched it.
+  const onlyRaw = flagString(flags, "only");
+  const only = onlyRaw ? new Set(onlyRaw.split(",").map((s) => s.trim()).filter(Boolean)) : null;
+
+  const reports = collect(projectRoot, { only });
+
+  // --run: execute the cited evidence instead of only checking it exists —
+  // promotes "the file is on disk" to "the proof passes". The runner is
+  // project-declared in .doctrina/verify.json ("evidence_runner": a command
+  // template with a {file} placeholder); the CLI never guesses a test runner.
+  if (flagBool(flags, "run", false)) {
+    return runEvidence(projectRoot, reports, strict);
   }
 
   if (reports.length === 0) {
+    if (json) {
+      console.log(JSON.stringify({ specs: [], summary: { criteria: 0, covered: 0, dangling: 0, conditional: 0, pct: 100 } }, null, 2));
+      return 0;
+    }
     console.log(c.gray("no acceptance criteria found under .doctrina/specs/"));
     return 0;
   }
@@ -49,6 +59,25 @@ export async function run(_positional, flags) {
   let totalCovered = 0;
   let totalDangling = 0;
   let totalConditional = 0;
+  let totalDeferred = 0;
+  for (const rep of reports) {
+    totalCriteria += rep.rows.length;
+    totalCovered += rep.rows.filter((r) => r.kind === "covered").length;
+    totalDangling += rep.rows.filter((r) => r.kind === "dangling").length;
+    totalConditional += rep.rows.filter((r) => r.kind === "conditional").length;
+    totalDeferred += rep.rows.filter((r) => r.kind === "deferred").length;
+  }
+  const jsonPct = totalCriteria === 0 ? 100 : Math.round((totalCovered / totalCriteria) * 100);
+  // Deferred criteria are visible but never gate: declared debt ≠ hidden debt.
+  const jsonClean = totalCovered + totalDeferred === totalCriteria && totalDangling === 0 && totalConditional === 0;
+
+  if (json) {
+    console.log(JSON.stringify({
+      specs: reports.map((rep) => ({ capability: rep.cap, deferred: rep.deferred, criteria: rep.rows })),
+      summary: { criteria: totalCriteria, covered: totalCovered, dangling: totalDangling, conditional: totalConditional, deferred: totalDeferred, pct: jsonPct },
+    }, null, 2));
+    return jsonClean ? 0 : strict ? 1 : 0;
+  }
 
   console.log(c.bold("Coverage") + c.gray(" — acceptance criteria with linked evidence:"));
   console.log("");
@@ -57,19 +86,19 @@ export async function run(_positional, flags) {
     const covered = rep.rows.filter((r) => r.kind === "covered").length;
     const dangling = rep.rows.filter((r) => r.kind === "dangling").length;
     const conditional = rep.rows.filter((r) => r.kind === "conditional").length;
-    totalCriteria += rep.rows.length;
-    totalCovered += covered;
-    totalDangling += dangling;
-    totalConditional += conditional;
+    const deferredN = rep.rows.filter((r) => r.kind === "deferred").length;
 
     const notes = [];
     if (conditional > 0) notes.push(c.yellow(`${conditional} conditional`));
     if (dangling > 0) notes.push(c.yellow(`${dangling} dangling`));
+    if (deferredN > 0) notes.push(c.gray(`${deferredN} deferred`));
     const note = notes.length > 0 ? `  (${notes.join(", ")})` : "";
     console.log(`  ${c.cyan(rep.cap.padEnd(20))} ${covered}/${rep.rows.length} criteria${note}`);
     for (const r of rep.rows) {
       if (r.kind === "covered") continue;
-      if (r.kind === "bare") {
+      if (r.kind === "deferred") {
+        console.log(`    ${c.gray("○")} #${r.n}  deferred — spec declares "Implementation: planned — <why>" (visible, not gated)`);
+      } else if (r.kind === "bare") {
         console.log(`    ${c.red("✗")} #${r.n}  no evidence linked — cite the file/test that proves it in backticks`);
       } else if (r.kind === "conditional") {
         console.log(`    ${c.yellow("!")} #${r.n}  evidence is a skipped test (proves nothing): ${r.skipped.map((m) => `\`${m}\``).join(", ")}`);
@@ -82,46 +111,141 @@ export async function run(_positional, flags) {
   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 && totalConditional === 0;
-  if (clean) {
-    console.log(c.green("ok") + " " + summary);
-    return 0;
-  }
+  const clean = totalCovered + totalDeferred === totalCriteria && totalDangling === 0 && totalConditional === 0;
   const extras = [];
   if (totalConditional > 0) extras.push(`${totalConditional} conditional`);
   if (totalDangling > 0) extras.push(`${totalDangling} dangling`);
+  if (totalDeferred > 0) extras.push(`${totalDeferred} deferred (not gated)`);
   const extraSummary = extras.length > 0 ? `, ${extras.join(", ")}` : "";
+  if (clean) {
+    console.log(c.green("ok") + " " + summary + extraSummary);
+    return 0;
+  }
   console.log((strict ? c.red("fail") : c.yellow("gap")) + " " + summary + extraSummary);
   // A report by default (exit 0); a gate under --strict (exit 1 for CI). A
   // conditional criterion fails the gate too: a skipped test is not proof.
+  // Deferred criteria never fail: the deferral is declared in the spec.
   return strict ? 1 : 0;
 }
 
-// Pure summary of coverage across the spec tree, for other commands
-// (`status`, `review`) that need the numbers without the report output.
-export function summarize(projectRoot) {
+// --run: execute every unique cited-and-resolving evidence file through the
+// project-declared runner. Declared in .doctrina/verify.json as
+//   "evidence_runner": "python -m pytest {file}"
+// ({file} is replaced per file). Exit 1 when any run fails (or under --strict
+// when nothing is runnable). Deferred specs are skipped like everywhere else.
+function runEvidence(projectRoot, reports, strict) {
+  const cfgPath = path.join(projectRoot, ".doctrina", "verify.json");
+  let runner = null;
+  if (isFile(cfgPath)) {
+    try { runner = JSON.parse(read(cfgPath))?.evidence_runner ?? null; } catch { runner = null; }
+  }
+  if (!runner || typeof runner !== "string" || !runner.includes("{file}")) {
+    console.error(c.red("error:") + " coverage --run needs an \"evidence_runner\" in .doctrina/verify.json");
+    console.error(c.gray("hint: ") + `add e.g. "evidence_runner": "python -m pytest {file}" (the {file} placeholder is required — the CLI never guesses a test runner)`);
+    return 1;
+  }
+
+  // Unique evidence files: cited by a non-deferred criterion, resolving on
+  // disk, and test-shaped (running a cited source artifact proves nothing).
+  const files = new Set();
+  for (const rep of reports) {
+    for (const r of rep.rows) {
+      if (rep.deferred || r.kind === "deferred") continue;
+      for (const token of r.evidence ?? []) files.add(token);
+    }
+  }
+
+  if (files.size === 0) {
+    console.log(c.gray("no runnable evidence found (no non-deferred criterion cites a resolving test file)"));
+    return strict ? 1 : 0;
+  }
+
+  console.log(c.bold("coverage --run") + c.gray(` — executing ${files.size} evidence file${files.size === 1 ? "" : "s"} via: ${runner}`));
+  let failed = 0;
+  for (const file of [...files].sort()) {
+    const cmd = runner.replaceAll("{file}", file);
+    console.log("");
+    console.log(c.gray(`──── ${cmd}`));
+    const res = spawnSync(cmd, { cwd: projectRoot, shell: true, stdio: "inherit" });
+    const ok = !res.error && res.status === 0;
+    console.log(ok ? c.green(`✓ ${file}`) : c.red(`✗ ${file}${res.error ? ` — ${res.error.message}` : ` (exit ${res.status})`}`));
+    if (!ok) failed += 1;
+  }
+  console.log("");
+  if (failed === 0) {
+    console.log(c.green("ok") + ` ${files.size}/${files.size} evidence runs passed — cited proof actually proves`);
+    return 0;
+  }
+  console.log(c.red("fail") + ` ${files.size - failed}/${files.size} evidence runs passed — a cited proof does not pass`);
+  return 1;
+}
+
+// Per-spec criterion rows — the full classification behind both the report
+// and the --json output. Each row: { n, kind, missing?, skipped? }.
+//
+// A spec that declares a deliberate deferral — `Implementation: planned —
+// <why>`, the exact escape hatch `validate` already honours — has its
+// non-covered criteria remapped to kind "deferred": visible in every report,
+// never a --strict failure. Declared debt and hidden debt stop being punished
+// identically (0.11.0 field review item 4: one deferred capability poisoned
+// the close of every unrelated change).
+export function collect(projectRoot, { only = null } = {}) {
   const specsDir = path.join(projectRoot, ".doctrina", "specs");
-  let totalCriteria = 0, totalCovered = 0, totalDangling = 0, totalConditional = 0;
-  const perCap = [];
+  const reports = [];
   if (isDir(specsDir)) {
     for (const cap of readdirSync(specsDir).sort()) {
+      if (only && !only.has(cap)) continue;
       const specPath = path.join(specsDir, cap, "spec.md");
       if (!isFile(specPath)) continue;
-      const criteria = extractAcceptanceCriteria(read(specPath));
+      const text = read(specPath);
+      const criteria = extractAcceptanceCriteria(text);
       if (criteria.length === 0) continue;
-      const rows = criteria.map((crit, i) => classify(crit, i + 1, projectRoot, path.dirname(specPath)));
-      const covered = rows.filter((r) => r.kind === "covered").length;
-      const dangling = rows.filter((r) => r.kind === "dangling").length;
-      const conditional = rows.filter((r) => r.kind === "conditional").length;
-      totalCriteria += rows.length;
-      totalCovered += covered;
-      totalDangling += dangling;
-      totalConditional += conditional;
-      perCap.push({ cap, total: rows.length, covered, dangling, conditional });
+      const deferred = isDeclaredDeferral(text);
+      const rows = criteria.map((crit, i) => {
+        const row = classify(crit, i + 1, projectRoot, path.dirname(specPath));
+        if (deferred && row.kind !== "covered") {
+          return { ...row, kind: "deferred", was: row.kind };
+        }
+        return row;
+      });
+      reports.push({ cap, specPath, rows, deferred });
     }
   }
+  return reports;
+}
+
+// The declared-deferral escape hatch, matching validate's two-axis check:
+// Implementation is "planned" WITH an explanatory note after the state word.
+// A bare "planned" is an inventory claim, not a deferral, and gets no pass.
+function isDeclaredDeferral(specText) {
+  const implRaw = specHeader(specText, "Implementation");
+  if (!implRaw) return false;
+  const tokens = implRaw.trim().split(/\s+/);
+  const word = (tokens[0] ?? "").replace(/[—-]+$/, "").toLowerCase();
+  return word === "planned" && tokens.length > 1;
+}
+
+// Pure summary of coverage across the spec tree, for other commands
+// (`status`, `review`) that need the numbers without the report output.
+// Deferred criteria (declared deferral, see collect) are counted separately
+// and excluded from the problem counts, matching the gate semantics.
+export function summarize(projectRoot) {
+  let totalCriteria = 0, totalCovered = 0, totalDangling = 0, totalConditional = 0, totalDeferred = 0;
+  const perCap = [];
+  for (const rep of collect(projectRoot)) {
+    const covered = rep.rows.filter((r) => r.kind === "covered").length;
+    const dangling = rep.rows.filter((r) => r.kind === "dangling").length;
+    const conditional = rep.rows.filter((r) => r.kind === "conditional").length;
+    const deferred = rep.rows.filter((r) => r.kind === "deferred").length;
+    totalCriteria += rep.rows.length;
+    totalCovered += covered;
+    totalDangling += dangling;
+    totalConditional += conditional;
+    totalDeferred += deferred;
+    perCap.push({ cap: rep.cap, total: rep.rows.length, covered, dangling, conditional, deferred });
+  }
   const pct = totalCriteria === 0 ? 100 : Math.round((totalCovered / totalCriteria) * 100);
-  return { perCap, totalCriteria, totalCovered, totalDangling, totalConditional, pct };
+  return { perCap, totalCriteria, totalCovered, totalDangling, totalConditional, totalDeferred, pct };
 }
 
 // Pull the numbered items out of the "## Acceptance criteria" section.
@@ -182,11 +306,14 @@ function classify(criterion, n, projectRoot, specDir) {
     resolved.push({ token, isTest, skipped });
   }
   if (resolved.length === 0) return { kind: "dangling", n, missing };
+  // Runnable evidence: the resolving test-shaped citations, recorded so
+  // `coverage --run` can execute them (existence → passing proof).
+  const evidence = resolved.filter((r) => r.isTest && !r.skipped).map((r) => r.token);
   // Real proof = a non-test artifact, or a test file whose suite runs. If the
   // only thing that resolves is a skipped test, the criterion is conditional.
   const hasRealProof = resolved.some((r) => !r.isTest || !r.skipped);
-  if (hasRealProof) return { kind: "covered", n };
-  return { kind: "conditional", n, skipped: resolved.map((r) => r.token) };
+  if (hasRealProof) return { kind: "covered", n, evidence };
+  return { kind: "conditional", n, skipped: resolved.map((r) => r.token), evidence: [] };
 }
 
 // A cited path is a test file when it sits under a tests directory or carries
@@ -241,7 +368,7 @@ function looksLikePath(s) {
 }
 
 export const help = `
-Usage: doctrina coverage [--strict]
+Usage: doctrina coverage [--strict] [--only <cap,cap>] [--run] [--json]
 
 Report how many acceptance criteria across .doctrina/specs/ cite an
 artifact or test that exists on disk. Each numbered criterion may cite
@@ -251,9 +378,23 @@ A criterion is covered when a cited path resolves to real proof,
 conditional when its only resolving proof is a test file whose suite is
 skipped (\`describe.skip\` / \`xit\` / \`@pytest.mark.skip\` — proves
 nothing), dangling when a cited path is missing on disk, and bare when
-nothing is cited. Read-only.
+nothing is cited. A spec that declares a deliberate deferral —
+\`Implementation: planned — <why>\`, the same escape hatch validate
+honours — has its unproven criteria reported as DEFERRED: visible, but
+never a --strict failure (declared debt is not hidden debt).
 
 Flags:
-  --strict   Exit 1 when any criterion is bare, dangling, or conditional
-             (CI gate). Without it the command always exits 0 (a report).
+  --strict           Exit 1 when any criterion is bare, dangling, or
+                     conditional (CI gate). Deferred never fails. Without
+                     it the command always exits 0 (a report).
+  --only <cap,cap>   Scope the report/gate to specific capabilities
+                     (\`doctrina close\` uses this so an unrelated deferred
+                     spec cannot block a change's close).
+  --run              Execute the cited evidence via the project-declared
+                     "evidence_runner" in .doctrina/verify.json (a command
+                     template with a {file} placeholder, e.g.
+                     "python -m pytest {file}"). Exits 1 when any run
+                     fails — promotes "the file exists" to "the proof
+                     passes". The CLI never guesses a test runner.
+  --json             Emit per-spec criterion rows + summary as JSON.
 `;