doctrina-cli 0.11.0 → 0.13.0

package/src/commands/close.js

@@ -1,14 +1,17 @@
 import path from "node:path";
 import process from "node:process";
-import { exists, isFile } from "../lib/fs-ops.js";
+import { exists, isFile, read, walk } from "../lib/fs-ops.js";
 import { flagBool } from "../lib/args.js";
 import { c } from "../lib/colors.js";
+import { parseCapabilityFromDelta } from "./change.js";
+import { printAdrCheckpoint } from "../lib/adr-guard.js";
 import * as analyze from "./analyze.js";
 import * as change from "./change.js";
 import * as verify from "./verify.js";
 import * as coverage from "./coverage.js";
 import * as trace from "./trace.js";
 import * as validate from "./validate.js";
+import * as skill from "./skill.js";
 
 // One-command close (review 2026-06-27 passive-user feature #2). The work
 // playbook lists the closing sequence — analyze → apply → verify → coverage →
@@ -19,8 +22,7 @@ import * as validate from "./validate.js";
 // driver over the existing commands; it adds no new checks of its own.
 
 export async function run(positional, flags) {
-  const id = positional[0];
-  if (!id) {
+  if (positional.length === 0) {
     console.error(c.red("error:") + " close requires a change <id> (e.g. doctrina close 0001-add-login)");
     return 2;
   }
@@ -29,21 +31,72 @@ export async function run(positional, flags) {
     throw new Error("not a Doctrina project (no .doctrina/ in cwd). Run `doctrina init` first.");
   }
 
+  // Batch close (operator review 2026-07-19 §4.5): each id closes
+  // independently, worst exit code wins, so a 9-change implementation lot is
+  // one command, not nine.
+  let worst = 0;
+  for (const id of positional) {
+    if (positional.length > 1) {
+      console.log("");
+      console.log(c.bold(`════ close ${id}`));
+    }
+    worst = Math.max(worst, await closeOne(projectRoot, id, flags));
+  }
+  if (positional.length > 1) {
+    console.log("");
+    console.log(worst === 0
+      ? c.green("ok") + ` all ${positional.length} changes closed`
+      : c.red("fail") + " at least one close stopped — see above");
+  }
+  return worst;
+}
+
+async function closeOne(projectRoot, id, flags) {
   const force = flagBool(flags, "force", false);
-  const strict = new Map([["strict", true]]);
   const archiveFlags = force ? new Map([["force", true]]) : new Map();
 
+  // Scope the coverage gate to the capabilities THIS change touches (its
+  // deltas), so one deliberately deferred spec elsewhere in the tree cannot
+  // block closing a change that never went near it (0.11.0 field review
+  // item 4). A change with no deltas (chore / metadata-only) falls back to
+  // the whole-tree gate — there is no narrower honest scope for it.
+  const touched = touchedCapabilities(projectRoot, id);
+  const coverageFlags = new Map([["strict", true]]);
+  let coverageRerun = "doctrina coverage --strict";
+  if (touched.length > 0) {
+    coverageFlags.set("only", touched.join(","));
+    coverageRerun = `doctrina coverage --strict --only ${touched.join(",")}`;
+  }
+
   // Each step: a label, the command that runs it, and the literal command to
   // rerun on failure. verify is conditional (skipped, with a loud note, when no
   // verify.json is declared — a project may not have wired the real gate yet).
   const verifyConfigured = isFile(path.join(projectRoot, ".doctrina", "verify.json"));
   const steps = [
     { label: "analyze", rerun: `doctrina analyze ${id}`, run: () => analyze.run([id], new Map()) },
+    // ADR checkpoint (operator review §4.6): the playbook's "record an ADR"
+    // step was skippable in silence. Advisory — it names the accepted ADRs
+    // whose text cites the touched capabilities and the amend commands, but
+    // an ADR merely mentioning a capability is normal, so it never blocks.
+    {
+      label: "ADR checkpoint (advisory)",
+      rerun: "doctrina decision list",
+      run: async () => {
+        if (printAdrCheckpoint(projectRoot, touched, { c }) === 0) {
+          console.log(c.green("ok") + " no accepted ADR cites the touched capabilities");
+        }
+        return 0;
+      },
+    },
     { label: "apply", rerun: `doctrina change apply ${id}`, run: () => change.run(["apply", id], new Map()) },
     verifyConfigured
       ? { label: "verify", rerun: "doctrina verify", run: () => verify.run([], new Map()) }
       : { label: "verify", skip: "no .doctrina/verify.json — declare the real gate with `doctrina verify --init`" },
-    { label: "coverage", rerun: "doctrina coverage --strict", run: () => coverage.run([], strict) },
+    {
+      label: touched.length > 0 ? `coverage (scoped: ${touched.join(", ")})` : "coverage",
+      rerun: coverageRerun,
+      run: () => coverage.run([], coverageFlags),
+    },
     // trace is advisory (provenance is a warning, not a hard gate): report it,
     // never let it block the close.
     { label: "trace", rerun: "doctrina trace", run: async () => { await trace.run([], new Map()); return 0; } },
@@ -51,7 +104,7 @@ export async function run(positional, flags) {
     { label: "validate", rerun: "doctrina validate", run: () => validate.run([], new Map()) },
   ];
 
-  console.log(c.bold(`Closing change ${id}`) + c.gray(" — analyze → apply → verify → coverage → trace → archive → validate"));
+  console.log(c.bold(`Closing change ${id}`) + c.gray(" — analyze → ADR checkpoint → apply → verify → coverage → trace → archive → validate"));
 
   for (let i = 0; i < steps.length; i++) {
     const step = steps[i];
@@ -78,25 +131,58 @@ export async function run(positional, flags) {
     }
   }
 
+  // Capture the lesson while it is fresh (operator review §4.7): surface the
+  // fix-shaped lessons not yet written as skills, right where the operator
+  // just proved they finish what they start. Advisory — a listing, never a
+  // gate, and a suggest failure never un-closes the change.
+  console.log("");
+  console.log(c.gray("──── skills (advisory)"));
+  try {
+    await skill.run(["suggest"], new Map());
+  } catch { /* advisory only */ }
+
   console.log("");
   console.log(c.green(`✓ change ${id} closed`) + c.gray(" — verified, archived, and validated."));
   console.log(c.gray("Next: ") + c.cyan("doctrina next"));
   return 0;
 }
 
+// The capabilities this change's deltas target — the honest scope for its
+// coverage gate. Read from the change folder's specs/**/delta.md files.
+function touchedCapabilities(projectRoot, id) {
+  const specsDir = path.join(projectRoot, ".doctrina", "changes", id, "specs");
+  const caps = new Set();
+  for (const deltaPath of walk(specsDir)) {
+    if (!deltaPath.endsWith("delta.md")) continue;
+    const cap = parseCapabilityFromDelta(read(deltaPath), deltaPath);
+    if (cap) caps.add(cap);
+  }
+  return [...caps].sort();
+}
+
 export const help = `
-Usage: doctrina close <id> [--force]
+Usage: doctrina close <id...> [--force]
 
 Run the whole closing sequence for a change in one pass, stopping at the
 first failure with the exact command to rerun:
 
-  analyze → change apply → verify → coverage --strict → trace → change
-  archive → validate
+  analyze → ADR checkpoint (advisory) → change apply → verify → coverage
+  --strict (scoped to the change's touched capabilities) → trace → change
+  archive → validate → skill suggest (advisory)
+
+The coverage gate is scoped to the capabilities the change's deltas touch,
+so a deliberately deferred spec elsewhere cannot block an unrelated close;
+a change with no deltas gates on the whole tree. verify is skipped (with a
+note) when no .doctrina/verify.json is declared; trace, the ADR checkpoint
+(accepted ADRs citing the touched capabilities — amend via \`decision
+supersede\`, not silence), and the closing skill-suggest listing are
+advisory (reports, never blockers). This is a driver over the existing
+commands so the agent makes one call instead of nine and the human
+approves once.
 
-verify is skipped (with a note) when no .doctrina/verify.json is declared;
-trace is advisory (a report, never a blocker). This is a driver over the
-existing commands — it adds no checks of its own — so the agent makes one
-call instead of seven and the human approves once.
+Multiple ids close in sequence, each independently; the exit code is the
+worst per-id result. Preview what close would refuse: \`doctrina change
+check <id>\`.
 
 Options:
   --force    Pass through to \`change archive\` (archive even if verification

package/src/commands/context.js

@@ -3,7 +3,7 @@ import process from "node:process";
 import { readdirSync } from "node:fs";
 import { spawnSync } from "node:child_process";
 import { exists, isDir, isFile, read, relPath, walk } from "../lib/fs-ops.js";
-import { listHeader } from "../lib/scan.js";
+import { listHeader, parseDependsOn } from "../lib/scan.js";
 import { parseFrontmatter } from "./skill.js";
 import { flagBool, flagString } from "../lib/args.js";
 import { c } from "../lib/colors.js";
@@ -80,6 +80,15 @@ 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;
     }

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
@@ -28,7 +30,21 @@ export async function run(_positional, flags) {
   const strict = flagBool(flags, "strict", false);
   const json = flagBool(flags, "json", false);
 
-  const reports = collect(projectRoot);
+  // --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) {
@@ -43,19 +59,22 @@ 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);
-  const jsonClean = totalCovered === totalCriteria && totalDangling === 0 && totalConditional === 0;
+  // 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, criteria: rep.rows })),
-      summary: { criteria: totalCriteria, covered: totalCovered, dangling: totalDangling, conditional: totalConditional, pct: jsonPct },
+      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;
   }
@@ -67,15 +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;
+    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(", ")}`);
@@ -88,64 +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;
 }
 
+// --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? }.
-export function collect(projectRoot) {
+//
+// 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");
   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)));
-      reports.push({ cap, specPath, rows });
+      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) {
-  const specsDir = path.join(projectRoot, ".doctrina", "specs");
-  let totalCriteria = 0, totalCovered = 0, totalDangling = 0, totalConditional = 0;
+  let totalCriteria = 0, totalCovered = 0, totalDangling = 0, totalConditional = 0, totalDeferred = 0;
   const perCap = [];
-  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)));
-      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 });
-    }
+  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.
@@ -206,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
@@ -265,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
@@ -275,10 +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).
-  --json     Emit per-spec criterion rows + summary as JSON.
+  --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.
 `;

package/src/commands/init.js

@@ -2,6 +2,7 @@ import path from "node:path";
 import process from "node:process";
 import { exists, isDir, isFile, read, relPath, write } from "../lib/fs-ops.js";
 import { locateTemplatesDir, loadTemplateTree, materialiseEntry, substitute } from "../lib/templates.js";
+import { surfaceBlock, findSurfaceBlock } from "../lib/commands.js";
 import { today } from "../lib/dates.js";
 import { cliVersion } from "../lib/version.js";
 import { flagBool, flagString } from "../lib/args.js";
@@ -108,10 +109,13 @@ export async function run(_positional, flags) {
     FRAMEWORK_VERSION: cliVersion(),
   };
 
-  // Root AGENTS.md — with optional --from base content prepended.
+  // Root AGENTS.md — with optional --from base content prepended. The
+  // doctrina:surface block is regenerated from the installed catalog at init
+  // time, so a freshly scaffolded hub can never document a stale surface even
+  // if the static template lags a release (ADR 0015).
   const agentsTemplatePath = path.join(templatesDir, "AGENTS.md.template");
   const agentsTemplateBody = read(agentsTemplatePath);
-  const projectAgents = substitute(agentsTemplateBody, tokens);
+  const projectAgents = refreshSurfaceBlock(substitute(agentsTemplateBody, tokens));
   const finalAgents = fromAgentsContent
     ? fromAgentsContent.replace(/\n+$/, "") + "\n\n---\n\n## Project-specific\n\n" + projectAgents
     : projectAgents;
@@ -178,6 +182,15 @@ export async function run(_positional, flags) {
   return 0;
 }
 
+// Replace the template's doctrina:surface span with the one generated from
+// the running CLI's catalog; pass the text through untouched when the
+// template carries no markers (older custom templates).
+function refreshSurfaceBlock(text) {
+  const block = findSurfaceBlock(text);
+  if (!block) return text;
+  return text.slice(0, block.start) + surfaceBlock() + text.slice(block.end);
+}
+
 // First non-empty line of the intake, stripped of Markdown heading marks
 // and clipped, as the one-line description token for the templates.
 function firstLineSummary(text) {