doctrina-cli 0.9.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.6.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.9.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

@@ -0,0 +1,138 @@
+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 { listHeader } from "../lib/scan.js";
+import { c } from "../lib/colors.js";
+
+// The project's standing rules in one read — Spec Kit parity for its
+// `constitution.md`, but ASSEMBLED, not a new home for facts. Doctrina's
+// constitution is its accepted ADRs (the immutable decisions that govern how
+// the codebase evolves) plus the product's declared non-goals. Both already
+// own those facts elsewhere; this is a read-only digest that gathers them so a
+// human or agent (especially one migrating from Spec Kit, which expects a
+// single constitution) can see "the rules" without reading the whole tree.
+//
+// To change a principle, supersede its ADR; to change a non-goal, edit
+// product.md. The command never writes — it has nothing of its own to own.
+
+export async function run(_positional, _flags) {
+  const projectRoot = process.cwd();
+  if (!exists(path.join(projectRoot, ".doctrina"))) {
+    throw new Error("not a Doctrina project (no .doctrina/ in cwd). Run `doctrina init` first.");
+  }
+
+  const project = projectName(projectRoot);
+  console.log(
+    c.bold("Doctrina constitution") +
+      c.gray(` — ${project}  (standing rules: accepted decisions + non-goals)`),
+  );
+
+  // Principles — the accepted ADRs, by number. Every accepted decision is a
+  // binding rule; superseded/withdrawn/proposed ADRs are not yet (or no longer)
+  // in force and stay out.
+  console.log("");
+  console.log(c.bold("  Principles") + c.gray("  (immutable — supersede an ADR to change one)"));
+  const adrs = acceptedDecisions(projectRoot);
+  if (adrs.length === 0) {
+    console.log(`    ${c.gray("no accepted ADRs yet — record decisions with `doctrina decision new`")}`);
+  } else {
+    for (const a of adrs) console.log(`    ${c.cyan("ADR " + a.id)}  ${a.title}`);
+  }
+
+  // Non-goals — the explicit "what this project will not be", from product.md.
+  console.log("");
+  console.log(c.bold("  Non-goals") + c.gray("  (.doctrina/product.md)"));
+  const nonGoals = productSection(projectRoot, "Non-goals");
+  if (nonGoals.length === 0) {
+    console.log(`    ${c.gray("none declared — add a `## Non-goals` section to product.md")}`);
+  } else {
+    for (const g of nonGoals) console.log(`    ${c.gray("•")} ${g}`);
+  }
+
+  console.log("");
+  console.log(
+    c.gray(
+      `  ${adrs.length} accepted decision${adrs.length === 1 ? "" : "s"} · ` +
+        `${nonGoals.length} non-goal${nonGoals.length === 1 ? "" : "s"} · read-only`,
+    ),
+  );
+  return 0;
+}
+
+function projectName(projectRoot) {
+  try {
+    return JSON.parse(read(path.join(projectRoot, ".doctrina", "index.json"))).project
+      ?? path.basename(projectRoot);
+  } catch {
+    return path.basename(projectRoot);
+  }
+}
+
+// Accepted ADRs (NNNN-slug.md with Status: accepted), oldest first, with the
+// 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;
+  for (const f of readdirSync(dir).sort()) {
+    const m = f.match(/^(\d{4})-.*\.md$/);
+    if (!m) continue;
+    const text = read(path.join(dir, f));
+    if ((listHeader(text, "Status") ?? "").toLowerCase() !== "accepted") 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;
+}
+
+// Bullets under a named `## <section>` of product.md, each accumulated across
+// 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/);
+  let inSection = false;
+  const out = [];
+  let cur = null;
+  const flush = () => {
+    if (cur) out.push(cur.replace(/\s+/g, " ").trim());
+    cur = null;
+  };
+  for (const line of lines) {
+    if (/^##\s+/.test(line)) {
+      if (inSection) {
+        flush();
+        break;
+      }
+      if (new RegExp(`^##\\s+${name}\\b`, "i").test(line)) inSection = true;
+      continue;
+    }
+    if (!inSection) continue;
+    const m = line.match(/^\s*[-*]\s+(.+)$/);
+    if (m) {
+      flush();
+      cur = m[1];
+    } else if (cur && line.trim() !== "") {
+      cur += " " + line.trim();
+    } else if (line.trim() === "") {
+      flush();
+    }
+  }
+  flush();
+  return out;
+}
+
+export const help = `
+Usage: doctrina constitution
+
+Print the project's standing rules in one read: the accepted ADRs (the
+immutable decisions that govern how the codebase evolves) and the product's
+declared non-goals. Read-only — it assembles facts the ADRs and product.md
+already own; it never writes.
+
+This is the Spec Kit \`constitution.md\` analogue: a single place to see the
+non-negotiables. To change one, supersede the ADR or edit product.md.
+`;

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,19 +36,46 @@ 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 under work.
+  // 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. Specs come before
+  //    open changes and ADRs, matching the documented read order.
   let specMissing = false;
+  const specsRoot = path.join(projectRoot, ".doctrina", "specs");
   if (capability) {
     const specRel = `.doctrina/specs/${capability}/spec.md`;
     if (isFile(path.join(projectRoot, specRel))) {
@@ -45,9 +83,14 @@ export async function run(positional, flags) {
     } else {
       specMissing = true;
     }
+  } else if (isDir(specsRoot)) {
+    for (const cap of readdirSync(specsRoot).sort()) {
+      const specRel = `.doctrina/specs/${cap}/spec.md`;
+      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()) {
@@ -64,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)) {
@@ -78,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}) =====`);
@@ -88,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}`)}`);
       }
     }
   }
@@ -110,20 +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), open
-changes, accepted ADRs. Skills are listed name + description only —
-they are on-demand by design. The change archive is excluded.
+order: AGENTS.md, product.md, the capability spec (when given —
+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.
 `;