doctrina-cli 0.10.0 → 0.11.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.10.0 — current release. Zero runtime dependencies
+**Status:** v0.11.0 — current release. Zero runtime dependencies
 (Node.js standard library only).
 
 ## Install

package/package.json

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

package/src/commands/completion.js

@@ -0,0 +1,116 @@
+import { OPERATIONS, COMMAND_NAMES } from "../lib/commands.js";
+import { c } from "../lib/colors.js";
+
+// Shell completions, generated from the same OPERATIONS catalog that feeds
+// `--help` and the docs drift tests — so the completion script can never
+// know a different surface than the CLI ships. Static output by design:
+// paste it into your shell config once; regenerate after upgrading.
+
+function subcommandMap() {
+  const map = new Map();
+  for (const [op] of OPERATIONS) {
+    const [cmd, sub] = op.split(" ");
+    if (!sub) continue;
+    if (!map.has(cmd)) map.set(cmd, []);
+    map.get(cmd).push(sub);
+  }
+  return map;
+}
+
+function bashScript() {
+  const subs = subcommandMap();
+  const cases = [...subs.entries()]
+    .map(([cmd, list]) => `    ${cmd}) COMPREPLY=( $(compgen -W "${list.join(" ")}" -- "$cur") );;`)
+    .join("\n");
+  return `# doctrina bash completion — generated by \`doctrina completion bash\`
+# Install: doctrina completion bash >> ~/.bashrc   (or into bash_completion.d)
+_doctrina() {
+  local cur
+  cur="\${COMP_WORDS[COMP_CWORD]}"
+  if [ "$COMP_CWORD" -eq 1 ]; then
+    COMPREPLY=( $(compgen -W "${COMMAND_NAMES.join(" ")}" -- "$cur") )
+    return
+  fi
+  if [ "$COMP_CWORD" -eq 2 ]; then
+    case "\${COMP_WORDS[1]}" in
+${cases}
+    esac
+  fi
+}
+complete -F _doctrina doctrina
+`;
+}
+
+function zshScript() {
+  const subs = subcommandMap();
+  const cases = [...subs.entries()]
+    .map(([cmd, list]) => `    ${cmd}) _values 'subcommand' ${list.map((s) => `'${s}'`).join(" ")} ;;`)
+    .join("\n");
+  return `#compdef doctrina
+# doctrina zsh completion — generated by \`doctrina completion zsh\`
+# Install: doctrina completion zsh > "\${fpath[1]}/_doctrina"   (then restart zsh)
+_doctrina() {
+  if (( CURRENT == 2 )); then
+    _values 'command' ${COMMAND_NAMES.map((n) => `'${n}'`).join(" ")}
+    return
+  fi
+  case "\${words[2]}" in
+${cases}
+  esac
+}
+_doctrina "$@"
+`;
+}
+
+function pwshScript() {
+  const subs = subcommandMap();
+  const entries = [...subs.entries()]
+    .map(([cmd, list]) => `  "${cmd}" = @(${list.map((s) => `"${s}"`).join(", ")})`)
+    .join("\n");
+  return `# doctrina PowerShell completion — generated by \`doctrina completion pwsh\`
+# Install: doctrina completion pwsh >> $PROFILE   (then restart the shell)
+$doctrinaCommands = @(${COMMAND_NAMES.map((n) => `"${n}"`).join(", ")})
+$doctrinaSubcommands = @{
+${entries}
+}
+Register-ArgumentCompleter -Native -CommandName doctrina -ScriptBlock {
+  param($wordToComplete, $commandAst, $cursorPosition)
+  $words = $commandAst.CommandElements | ForEach-Object { $_.ToString() }
+  if ($words.Count -le 1 -or ($words.Count -eq 2 -and $wordToComplete)) {
+    $doctrinaCommands | Where-Object { $_ -like "$wordToComplete*" } |
+      ForEach-Object { [System.Management.Automation.CompletionResult]::new($_, $_, 'ParameterValue', $_) }
+    return
+  }
+  $cmd = $words[1]
+  if ($doctrinaSubcommands.ContainsKey($cmd)) {
+    $doctrinaSubcommands[$cmd] | Where-Object { $_ -like "$wordToComplete*" } |
+      ForEach-Object { [System.Management.Automation.CompletionResult]::new($_, $_, 'ParameterValue', $_) }
+  }
+}
+`;
+}
+
+export async function run(positional, _flags) {
+  const shell = positional[0];
+  const generators = { bash: bashScript, zsh: zshScript, pwsh: pwshScript, powershell: pwshScript };
+  if (!shell || !generators[shell]) {
+    console.error(c.red("error:") + ` completion requires a shell: bash, zsh, or pwsh${shell ? ` (got "${shell}")` : ""}`);
+    console.error(c.gray("hint: ") + "`doctrina completion bash >> ~/.bashrc`");
+    return 2;
+  }
+  process.stdout.write(generators[shell]());
+  return 0;
+}
+
+export const help = `
+Usage: doctrina completion <bash|zsh|pwsh>
+
+Print a shell-completion script for the doctrina CLI, generated from
+the same operation catalog that feeds --help (commands and their
+subcommands; flags are not completed). Static output — install once,
+regenerate after upgrading:
+
+  doctrina completion bash >> ~/.bashrc
+  doctrina completion zsh  > "\${fpath[1]}/_doctrina"
+  doctrina completion pwsh >> $PROFILE
+`;

package/src/commands/constitution.js

@@ -70,8 +70,9 @@ function projectName(projectRoot) {
 }
 
 // Accepted ADRs (NNNN-slug.md with Status: accepted), oldest first, with the
-// title read from the `# ADR NNNN — <title>` heading.
-function acceptedDecisions(projectRoot) {
+// title read from the `# ADR NNNN — <title>` heading. Exported for `prime`,
+// which digests the same standing rules into the session primer.
+export function acceptedDecisions(projectRoot) {
   const dir = path.join(projectRoot, ".doctrina", "decisions");
   const out = [];
   if (!isDir(dir)) return out;
@@ -87,8 +88,9 @@ function acceptedDecisions(projectRoot) {
 }
 
 // Bullets under a named `## <section>` of product.md, each accumulated across
-// its continuation lines so a wrapped bullet reads as one rule.
-function productSection(projectRoot, name) {
+// its continuation lines so a wrapped bullet reads as one rule. Exported for
+// `prime`.
+export function productSection(projectRoot, name) {
   const p = path.join(projectRoot, ".doctrina", "product.md");
   if (!isFile(p)) return [];
   const lines = read(p).split(/\r?\n/);

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 { spawnSync } from "node:child_process";
+import { exists, isDir, isFile, read, relPath, walk } from "../lib/fs-ops.js";
 import { listHeader } 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");
@@ -54,11 +86,11 @@ export async function run(positional, flags) {
   } 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 +107,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 +125,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 +139,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 +167,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

@@ -26,21 +26,15 @@ 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 });
-    }
-  }
+  const reports = collect(projectRoot);
 
   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 +43,22 @@ export async function run(_positional, flags) {
   let totalCovered = 0;
   let totalDangling = 0;
   let totalConditional = 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;
+  }
+  const jsonPct = totalCriteria === 0 ? 100 : Math.round((totalCovered / totalCriteria) * 100);
+  const jsonClean = totalCovered === 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 },
+    }, null, 2));
+    return jsonClean ? 0 : strict ? 1 : 0;
+  }
 
   console.log(c.bold("Coverage") + c.gray(" — acceptance criteria with linked evidence:"));
   console.log("");
@@ -57,10 +67,6 @@ 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 notes = [];
     if (conditional > 0) notes.push(c.yellow(`${conditional} conditional`));
@@ -97,6 +103,24 @@ export async function run(_positional, flags) {
   return strict ? 1 : 0;
 }
 
+// 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) {
+  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 });
+    }
+  }
+  return reports;
+}
+
 // 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) {
@@ -256,4 +280,5 @@ nothing is cited. Read-only.
 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.
 `;

package/src/commands/doctor.js

@@ -0,0 +1,135 @@
+import path from "node:path";
+import process from "node:process";
+import { spawnSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import { exists } from "../lib/fs-ops.js";
+import { collectStatus } from "./status.js";
+import { c } from "../lib/colors.js";
+
+// Aggregate diagnostic: the one command to run when "something looks wrong"
+// and you do not know which gate to ask. It sequences the existing checks —
+// validate, index drift, clean-checkout lint, template shape — and reports
+// each with its exact remediation command. A DRIVER over existing commands
+// (like `close`): it adds no checks of its own, so it can never disagree
+// with the authoritative gates it fronts.
+
+const cliEntry = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "index.js");
+
+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.");
+  }
+
+  console.log(c.bold("Doctrina doctor") + c.gray(" — aggregate diagnostic (read-only):"));
+  console.log("");
+
+  let failures = 0;
+  let warningsTotal = 0;
+  const row = (state, name, detail, fix) => {
+    const mark = state === "ok" ? c.green("ok  ") : state === "warn" ? c.yellow("warn") : c.red("FAIL");
+    console.log(`  ${mark}  ${name.padEnd(16)} ${detail}`);
+    if (fix) console.log(`        ${" ".repeat(16)} ${c.gray(`fix: ${fix}`)}`);
+    if (state === "fail") failures += 1;
+  };
+
+  // 1. Structural gate (validate), machine-read so the counts are exact.
+  const v = runSelf(["validate", "--json"], projectRoot);
+  let vParsed = null;
+  try {
+    vParsed = JSON.parse(v.stdout);
+  } catch {
+    vParsed = null;
+  }
+  if (!vParsed) {
+    row("fail", "validate", "did not produce a report", "doctrina validate");
+  } else if (!vParsed.ok) {
+    row("fail", "validate", `${vParsed.errors.length} error${vParsed.errors.length === 1 ? "" : "s"}, ${vParsed.warnings.length} warning${vParsed.warnings.length === 1 ? "" : "s"}`, "doctrina validate  (then `doctrina validate --fix` for index drift)");
+    for (const e of vParsed.errors.slice(0, 3)) console.log(`        ${" ".repeat(16)} ${c.red("·")} ${e}`);
+  } else if (vParsed.warnings.length > 0) {
+    warningsTotal += vParsed.warnings.length;
+    row("warn", "validate", `0 errors, ${vParsed.warnings.length} warning${vParsed.warnings.length === 1 ? "" : "s"}`, "doctrina validate  (warnings listed there)");
+  } else {
+    row("ok", "validate", "all structural checks pass");
+  }
+
+  // 2. Index ↔ tree drift.
+  const drift = runSelf(["index", "rebuild", "--check"], projectRoot);
+  if (drift.status === 0) row("ok", "index", "index.json matches the tree");
+  else row("fail", "index", "index.json has drifted from the tree", "doctrina validate --fix   (or `doctrina index rebuild`)");
+
+  // 3. Evidence and provenance ratios (cheap summaries; strict gates confirm).
+  const s = collectStatus(projectRoot);
+  if (s.coverage.totalCriteria === 0) {
+    row("warn", "coverage", "no acceptance criteria declared yet", "write criteria with evidence — see `doctrina coverage`");
+    warningsTotal += 1;
+  } else if (s.coverage.pct === 100 && s.coverage.totalDangling === 0 && s.coverage.totalConditional === 0) {
+    row("ok", "coverage", `${s.coverage.pct}% (${s.coverage.totalCovered}/${s.coverage.totalCriteria} criteria)`);
+  } else {
+    row("warn", "coverage", `${s.coverage.pct}% (${s.coverage.totalCovered}/${s.coverage.totalCriteria}${s.coverage.totalDangling ? `, ${s.coverage.totalDangling} dangling` : ""}${s.coverage.totalConditional ? `, ${s.coverage.totalConditional} conditional` : ""})`, "doctrina coverage   (cite the missing evidence)");
+    warningsTotal += 1;
+  }
+  if (s.trace.anchors === 0) {
+    row("warn", "trace", "no intent anchors declared in product.md", "tag bullets `- [SC1] ...`, add `**Realizes:**` to specs");
+    warningsTotal += 1;
+  } else if (s.trace.realized === s.trace.anchors && s.trace.untraceable === 0 && s.trace.dangling === 0) {
+    row("ok", "trace", `${s.trace.realized}/${s.trace.anchors} anchors realized`);
+  } else {
+    row("warn", "trace", `${s.trace.realized}/${s.trace.anchors} realized, ${s.trace.dropped} dropped, ${s.trace.untraceable} untraceable`, "doctrina trace");
+    warningsTotal += 1;
+  }
+
+  // 4. Clean-checkout reproducibility lint (ADR 0008).
+  const clean = runSelf(["verify", "--clean"], projectRoot);
+  if (clean.status === 0) row("ok", "clean-checkout", "no reproducibility footguns detected");
+  else row("fail", "clean-checkout", "a fresh clone would not build/run as-is", "doctrina verify --clean   (fix the listed package.json footguns)");
+
+  // 5. Template shape vs the running CLI's recommendation.
+  const tmpl = runSelf(["templates", "check"], projectRoot);
+  if (tmpl.status === 0) row("ok", "templates", "project follows the current template shape");
+  else {
+    row("warn", "templates", "recommended sections/fields are missing", "doctrina templates update   (--write applies)");
+    warningsTotal += 1;
+  }
+
+  // 6. Verify configuration (the real build gate must exist to be run).
+  if (s.verify.invalid) row("fail", "verify config", ".doctrina/verify.json is invalid JSON", "fix the JSON, then `doctrina verify`");
+  else if (!s.verify.configured) {
+    row("warn", "verify config", "no verify.json — the build gate is undeclared", "doctrina verify --init");
+    warningsTotal += 1;
+  } else {
+    row("ok", "verify config", `${s.verify.checks} check${s.verify.checks === 1 ? "" : "s"} declared (run \`doctrina verify\` to execute)`);
+  }
+
+  console.log("");
+  if (failures > 0) {
+    console.log(c.red("fail") + ` ${failures} failing area${failures === 1 ? "" : "s"} — fix commands above, then re-run \`doctrina doctor\``);
+    return 1;
+  }
+  if (warningsTotal > 0) {
+    console.log(c.yellow("warn") + ` no failures; ${warningsTotal} advisory item${warningsTotal === 1 ? "" : "s"} above`);
+    return 0;
+  }
+  console.log(c.green("ok") + " every diagnostic is green — `doctrina verify` remains the build gate to execute");
+  return 0;
+}
+
+function runSelf(args, cwd) {
+  return spawnSync(process.execPath, [cliEntry, ...args], {
+    cwd,
+    encoding: "utf8",
+    env: { ...process.env, NO_COLOR: "1" },
+  });
+}
+
+export const help = `
+Usage: doctrina doctor
+
+Aggregate diagnostic: run the structural gate (validate), the index
+drift check, the coverage/trace ratios, the clean-checkout lint
+(verify --clean), the template-shape check, and the verify-config
+presence — each reported with its exact remediation command.
+
+A driver over the existing commands; it adds no checks of its own.
+Read-only. Exits 1 when any area fails, 0 otherwise (warnings allowed).
+`;