doctrina-cli 0.9.0 → 0.11.0

package/src/commands/show.js

@@ -0,0 +1,173 @@
+import path from "node:path";
+import process from "node:process";
+import { readdirSync } from "node:fs";
+import { exists, isDir, isFile, read, relPath } from "../lib/fs-ops.js";
+import { parseAcceptanceCriteria } from "../lib/criteria.js";
+import { suggest } from "../lib/suggest.js";
+import { c } from "../lib/colors.js";
+
+// Point reads. An agent that needs ONE requirement re-reads a whole spec —
+// hundreds of lines for a two-line fact. `show` resolves a compact reference
+// to exactly the lines that own it:
+//
+//   doctrina show cli-R12    twelfth requirement of the cli spec (file order)
+//   doctrina show gates-C3   acceptance criterion 3 (the spec's own numbering)
+//   doctrina show 0007       ADR 0007, whole decision (already a bounded read)
+//   doctrina show cli        the spec's header block + Purpose only
+//
+// R-refs are positional (file order across the EARS sections), so they shift
+// when a requirement is inserted above — cite them for point reads and
+// conversation, not as immutable identifiers. C-refs use the criteria's own
+// explicit numbers and are as stable as the spec keeps them.
+
+export async function run(positional, _flags) {
+  const ref = positional[0];
+  const projectRoot = process.cwd();
+  if (!exists(path.join(projectRoot, ".doctrina"))) {
+    throw new Error("not a Doctrina project (no .doctrina/ in cwd). Run `doctrina init` first.");
+  }
+  if (!ref) {
+    console.error(c.red("error:") + " show requires a reference");
+    console.error(c.gray("hint: ") + "`doctrina show cli-R12` (requirement), `doctrina show cli-C3` (criterion), `doctrina show 0007` (ADR), `doctrina show cli` (spec header + purpose)");
+    return 2;
+  }
+
+  // ADR by number.
+  if (/^\d{4}$/.test(ref)) return showAdr(projectRoot, ref);
+
+  const m = ref.match(/^([a-z][a-z0-9-]*)-([RC])(\d+)$/);
+  if (m) return showSpecItem(projectRoot, m[1], m[2], Number(m[3]));
+
+  if (/^[a-z][a-z0-9-]*$/.test(ref)) return showSpecHead(projectRoot, ref);
+
+  console.error(c.red("error:") + ` unrecognised reference "${ref}"`);
+  console.error(c.gray("hint: ") + "use <cap>-R<n>, <cap>-C<n>, an ADR number (0007), or a capability name");
+  return 2;
+}
+
+function showAdr(projectRoot, num) {
+  const dir = path.join(projectRoot, ".doctrina", "decisions");
+  const file = isDir(dir) ? readdirSync(dir).find((f) => f.startsWith(`${num}-`) && f.endsWith(".md")) : null;
+  if (!file) {
+    console.error(c.red("error:") + ` no ADR ${num} under .doctrina/decisions/`);
+    return 1;
+  }
+  const full = path.join(dir, file);
+  console.log(c.gray(`— ${relPath(projectRoot, full)} —`));
+  console.log(read(full).trimEnd());
+  return 0;
+}
+
+function loadSpec(projectRoot, cap) {
+  const specsDir = path.join(projectRoot, ".doctrina", "specs");
+  const specPath = path.join(specsDir, cap, "spec.md");
+  if (isFile(specPath)) return { specPath, text: read(specPath) };
+  const known = isDir(specsDir) ? readdirSync(specsDir).filter((e) => isFile(path.join(specsDir, e, "spec.md"))) : [];
+  console.error(c.red("error:") + ` no spec for capability "${cap}"`);
+  const guess = suggest(cap, known);
+  if (guess) console.error(c.gray("hint: ") + `did you mean "${guess}"?`);
+  else if (known.length) console.error(c.gray("known: ") + known.sort().join(", "));
+  return null;
+}
+
+function showSpecHead(projectRoot, cap) {
+  const spec = loadSpec(projectRoot, cap);
+  if (!spec) return 1;
+  const lines = spec.text.split(/\r?\n/);
+  const out = [];
+  let mode = "head"; // header block -> seek Purpose -> purpose body -> stop
+  for (const line of lines) {
+    const isH2 = /^##\s+/.test(line);
+    if (mode === "head" && isH2) mode = /^##\s+Purpose\b/i.test(line) ? "purpose" : "seek";
+    else if (mode === "seek" && isH2 && /^##\s+Purpose\b/i.test(line)) mode = "purpose";
+    else if (mode === "purpose" && isH2) break;
+
+    if (mode === "head" || (mode === "purpose")) out.push(line);
+  }
+  console.log(c.gray(`— ${relPath(projectRoot, spec.specPath)} (header + purpose; \`doctrina context ${cap}\` for the full spec) —`));
+  console.log(out.join("\n").trimEnd());
+  return 0;
+}
+
+function showSpecItem(projectRoot, cap, kind, n) {
+  const spec = loadSpec(projectRoot, cap);
+  if (!spec) return 1;
+
+  if (kind === "C") {
+    const criteria = parseAcceptanceCriteria(spec.text);
+    const crit = criteria.find((r) => r.n === n);
+    if (!crit) {
+      console.error(c.red("error:") + ` ${cap} has no acceptance criterion #${n} (it declares ${criteria.length})`);
+      return 1;
+    }
+    console.log(c.gray(`— ${cap}-C${n} · ${relPath(projectRoot, spec.specPath)} · ## Acceptance criteria —`));
+    console.log(`${n}. ${crit.body}`);
+    if (crit.proofPaths.length > 0) {
+      console.log(c.gray(`   evidence: ${crit.proofPaths.join(", ")}`));
+    }
+    return 0;
+  }
+
+  const reqs = parseRequirements(spec.text);
+  const req = reqs[n - 1];
+  if (!req) {
+    console.error(c.red("error:") + ` ${cap} has no requirement R${n} (it declares ${reqs.length})`);
+    return 1;
+  }
+  console.log(c.gray(`— ${cap}-R${n} · ${relPath(projectRoot, spec.specPath)} · ${req.section} —`));
+  console.log(req.text);
+  return 0;
+}
+
+// Top-level bullets of the "## Requirements (EARS)" section, in file order,
+// each with its `### <grammar>` sub-section name and continuation lines.
+export function parseRequirements(text) {
+  const lines = text.split(/\r?\n/);
+  const out = [];
+  let inSection = false;
+  let sub = "";
+  let cur = null;
+  const flush = () => {
+    if (cur) out.push({ section: cur.section, text: cur.lines.join("\n").trimEnd() });
+    cur = null;
+  };
+  for (const line of lines) {
+    if (/^##\s+/.test(line)) {
+      flush();
+      inSection = /^##\s+Requirements\b/i.test(line);
+      sub = "";
+      continue;
+    }
+    if (!inSection) continue;
+    const subMatch = line.match(/^###\s+(.+)$/);
+    if (subMatch) {
+      flush();
+      sub = subMatch[1].trim();
+      continue;
+    }
+    if (/^-\s+/.test(line)) {
+      flush();
+      cur = { section: sub || "Requirements", lines: [line] };
+    } else if (cur && (line.startsWith("  ") || line.trim() === "")) {
+      cur.lines.push(line);
+    } else {
+      flush();
+    }
+  }
+  flush();
+  return out;
+}
+
+export const help = `
+Usage: doctrina show <ref>
+
+Point-read one artifact fragment instead of a whole file:
+
+  doctrina show cli-R12    requirement 12 of the cli spec (file order)
+  doctrina show cli-C3     acceptance criterion 3 (the spec's numbering)
+  doctrina show 0007       ADR 0007 (the whole decision)
+  doctrina show cli        the spec's header block + Purpose only
+
+R-refs are positional (they shift when a requirement is inserted above);
+C-refs use the criteria's own numbers. Read-only.
+`;

package/src/commands/status.js

@@ -7,6 +7,7 @@ import { deriveIndex, indexesMatch, specHeader, listHeader } from "../lib/scan.j
 import { cliVersion } from "../lib/version.js";
 import { summarize as coverageSummary } from "./coverage.js";
 import { summarize as traceSummary } from "./trace.js";
+import { flagBool } from "../lib/args.js";
 import { c } from "../lib/colors.js";
 
 // One-glance project health (review 2026-06-27 passive-user feature #1): a
@@ -19,53 +20,47 @@ import { c } from "../lib/colors.js";
 
 const CONFIG_REL = ".doctrina/verify.json";
 
-export async function run(_positional, _flags) {
+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.");
   }
 
-  let index = null;
-  try {
-    index = idx.load(projectRoot);
-  } catch {
-    index = null;
+  const s = collectStatus(projectRoot);
+
+  if (flagBool(flags, "json", false)) {
+    console.log(JSON.stringify(s, null, 2));
+    return 0;
   }
 
-  const project = index?.project ?? path.basename(projectRoot);
-  const stamp = index?.framework_version ?? "—";
-  const cli = cliVersion();
-  console.log(c.bold("Doctrina status") + c.gray(` — ${project}  (framework ${stamp} / CLI ${cli})`));
+  console.log(c.bold("Doctrina status") + c.gray(` — ${s.project}  (framework ${s.stamp ?? "—"} / CLI ${s.cli})`));
   console.log("");
 
   // --- Gates ---
   console.log(c.bold("  Gates"));
-  // Index drift (the silent rot validate now errors on).
   let driftLine;
-  if (!index) {
+  if (s.indexState === "missing") {
     driftLine = c.red("missing/unreadable") + c.gray(" — run `doctrina index rebuild`");
-  } else if (indexesMatch(deriveIndex(projectRoot, index), index)) {
+  } else if (s.indexState === "in-sync") {
     driftLine = c.green("in sync");
   } else {
     driftLine = c.yellow("drifted") + c.gray(" — run `doctrina validate --fix`");
   }
   console.log(`    ${"index".padEnd(11)} ${driftLine}`);
 
-  // Framework stamp divergence.
-  const stampLine = stamp === cli
+  const stampLine = s.stamp === s.cli
     ? c.green("current")
-    : c.yellow(`${stamp} (CLI ${cli})`) + c.gray(" — `doctrina index rebuild`");
+    : c.yellow(`${s.stamp ?? "—"} (CLI ${s.cli})`) + c.gray(" — `doctrina index rebuild`");
   console.log(`    ${"stamp".padEnd(11)} ${stampLine}`);
 
-  // Coverage and trace ratios.
-  const cov = coverageSummary(projectRoot);
+  const cov = s.coverage;
   const covExtra = cov.totalDangling + cov.totalConditional > 0
     ? c.yellow(` ${cov.totalDangling} dangling, ${cov.totalConditional} conditional`)
     : "";
   const covColor = cov.pct === 100 ? c.green : cov.pct >= 50 ? c.yellow : c.red;
   console.log(`    ${"coverage".padEnd(11)} ${covColor(`${cov.pct}%`)} ${c.gray(`(${cov.totalCovered}/${cov.totalCriteria} criteria)`)}${covExtra}`);
 
-  const tr = traceSummary(projectRoot);
+  const tr = s.trace;
   const trExtra = tr.untraceable + tr.dropped + tr.dangling > 0
     ? c.yellow(` ${tr.dropped} dropped, ${tr.untraceable} untraceable`)
     : "";
@@ -73,40 +68,72 @@ export async function run(_positional, _flags) {
   const trText = tr.anchors === 0 ? "no anchors" : `${tr.realized}/${tr.anchors} anchors`;
   console.log(`    ${"trace".padEnd(11)} ${trColor(trText)}${trExtra}`);
 
-  // Verify config presence (running it is the slow, authoritative gate).
-  const verifyCfg = path.join(projectRoot, CONFIG_REL);
   let verifyLine = c.gray("not configured") + c.gray(" — `doctrina verify --init`");
-  if (isFile(verifyCfg)) {
-    try {
-      const cfg = JSON.parse(read(verifyCfg));
-      const n = Array.isArray(cfg?.checks) ? cfg.checks.length : 0;
-      verifyLine = c.cyan(`${n} check${n === 1 ? "" : "s"}`) + c.gray(" — run `doctrina verify`");
-    } catch {
-      verifyLine = c.red("invalid JSON");
-    }
+  if (s.verify.invalid) {
+    verifyLine = c.red("invalid JSON");
+  } else if (s.verify.configured) {
+    const n = s.verify.checks;
+    verifyLine = c.cyan(`${n} check${n === 1 ? "" : "s"}`) + c.gray(" — run `doctrina verify`");
   }
   console.log(`    ${"verify".padEnd(11)} ${verifyLine}`);
 
   // --- Work ---
   console.log("");
   console.log(c.bold("  Work"));
-  const specs = countSpecs(projectRoot);
-  const implBreak = Object.entries(specs.impl).map(([k, v]) => `${v} ${k}`).join(", ");
-  console.log(`    ${"specs".padEnd(11)} ${specs.total}${implBreak ? c.gray(`  (${implBreak})`) : ""}`);
-  console.log(`    ${"changes".padEnd(11)} ${specs.openChanges} open`);
-  const adr = countDecisions(projectRoot);
+  const implBreak = Object.entries(s.specs.impl).map(([k, v]) => `${v} ${k}`).join(", ");
+  console.log(`    ${"specs".padEnd(11)} ${s.specs.total}${implBreak ? c.gray(`  (${implBreak})`) : ""}`);
+  console.log(`    ${"changes".padEnd(11)} ${s.specs.openChanges} open`);
   const adrNotes = [];
-  if (adr.proposed > 0) adrNotes.push(c.yellow(`${adr.proposed} proposed`));
-  if (adr.bare > 0) adrNotes.push(c.yellow(`${adr.bare} unproven`));
-  console.log(`    ${"decisions".padEnd(11)} ${adr.total}${adrNotes.length ? c.gray("  (") + adrNotes.join(c.gray(", ")) + c.gray(")") : ""}`);
-  const skills = countSkills(projectRoot);
-  console.log(`    ${"skills".padEnd(11)} ${skills}`);
+  if (s.decisions.proposed > 0) adrNotes.push(c.yellow(`${s.decisions.proposed} proposed`));
+  if (s.decisions.bare > 0) adrNotes.push(c.yellow(`${s.decisions.bare} unproven`));
+  console.log(`    ${"decisions".padEnd(11)} ${s.decisions.total}${adrNotes.length ? c.gray("  (") + adrNotes.join(c.gray(", ")) + c.gray(")") : ""}`);
+  console.log(`    ${"skills".padEnd(11)} ${s.skills}`);
 
   console.log("");
   console.log(c.gray("  Full gates: `doctrina validate` · `doctrina verify`.  Next step: `doctrina next`."));
   return 0;
 }
 
+// Pure, render-free status snapshot — the data behind the dashboard, shared
+// with `prime`, `handoff`, `doctor`, and the `--json` output so every consumer
+// reads the same numbers.
+export function collectStatus(projectRoot) {
+  let index = null;
+  try {
+    index = idx.load(projectRoot);
+  } catch {
+    index = null;
+  }
+  let indexState = "missing";
+  if (index) {
+    indexState = indexesMatch(deriveIndex(projectRoot, index), index) ? "in-sync" : "drifted";
+  }
+
+  const verifyCfg = path.join(projectRoot, CONFIG_REL);
+  let verify = { configured: false, checks: 0, invalid: false };
+  if (isFile(verifyCfg)) {
+    try {
+      const cfg = JSON.parse(read(verifyCfg));
+      verify = { configured: true, checks: Array.isArray(cfg?.checks) ? cfg.checks.length : 0, invalid: false };
+    } catch {
+      verify = { configured: true, checks: 0, invalid: true };
+    }
+  }
+
+  return {
+    project: index?.project ?? path.basename(projectRoot),
+    stamp: index?.framework_version ?? null,
+    cli: cliVersion(),
+    indexState,
+    coverage: coverageSummary(projectRoot),
+    trace: traceSummary(projectRoot),
+    verify,
+    specs: countSpecs(projectRoot),
+    decisions: countDecisions(projectRoot),
+    skills: countSkills(projectRoot),
+  };
+}
+
 function countSpecs(projectRoot) {
   const specsDir = path.join(projectRoot, ".doctrina", "specs");
   const impl = {};
@@ -165,13 +192,16 @@ function countSkills(projectRoot) {
 }
 
 export const help = `
-Usage: doctrina status
+Usage: doctrina status [--json]
 
 Print a one-glance health dashboard for the .doctrina/ project: the gate
 signals (index drift, framework stamp, coverage %, trace anchors, whether
 verify is configured) and the artifact counts (specs by implementation
 state, open changes, decisions, skills). Read-only; always exits 0.
 
+Flags:
+  --json   Emit the snapshot as JSON (stable shape for agents and CI).
+
 It is a fast summary, not the authoritative gate: run \`doctrina validate\`
 and \`doctrina verify\` for the full structural and build checks, and
 \`doctrina next\` for the recommended next action.

package/src/commands/trace.js

@@ -32,6 +32,7 @@ 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 anchors = collectAnchors(projectRoot); // [{ id }], in document order
   const specs = collectSpecs(projectRoot); // [{ cap, status, realizes: [id] }]
@@ -41,6 +42,10 @@ export async function run(_positional, flags) {
 
   // The feature is unused: do not nag a project that never opted in.
   if (anchors.length === 0 && !anyRealizes) {
+    if (json) {
+      console.log(JSON.stringify({ anchors: [], dangling: [], untraceable: [], summary: summarize(projectRoot) }, null, 2));
+      return 0;
+    }
     console.log(
       c.gray(
         "no intent-provenance markers found — tag product.md bullets with `[SC1]` " +
@@ -69,6 +74,13 @@ export async function run(_positional, flags) {
     .filter((s) => s.realizes === null && s.status === "active")
     .map((s) => s.cap);
 
+  if (json) {
+    const rows = anchors.map((a) => ({ id: a.id, realizedBy: (realizedBy.get(a.id) ?? []).sort() }));
+    const clean = rows.every((r) => r.realizedBy.length > 0) && dangling.length === 0 && untraceable.length === 0;
+    console.log(JSON.stringify({ anchors: rows, dangling, untraceable, summary: summarize(projectRoot) }, null, 2));
+    return clean ? 0 : strict ? 1 : 0;
+  }
+
   console.log(c.bold("Trace") + c.gray(" — product intent → capability provenance:"));
   console.log("");
 
@@ -183,6 +195,7 @@ trace reports three provenance breaks:
   untraceable spec   an active spec with no Realizes: header
 
 Read-only. Exits 0 as a report; with --strict, exits 1 when any break
-exists (CI gate). It checks that the link exists and is complete — not
-that a criterion is faithful to the intent (that stays a human/LLM call).
+exists (CI gate). --json emits anchors/dangling/untraceable + summary
+as JSON. It checks that the link exists and is complete — not that a
+criterion is faithful to the intent (that stays a human/LLM call).
 `;

package/src/commands/validate.js

@@ -11,6 +11,13 @@ import { c } from "../lib/colors.js";
 import { parseFrontmatter } from "./skill.js";
 import { checkEars, isEarsSpec } from "../lib/ears.js";
 import { specHeader, listHeader, deriveIndex, indexesMatch, stableStringify } from "../lib/scan.js";
+import { COMMAND_NAMES, referencedCommands } from "../lib/commands.js";
+import { parseAcceptanceCriteria, isVerified } from "../lib/criteria.js";
+
+// AGENTS.md is treated as a maintained doctrina-command catalog only once it
+// documents at least this many real commands; below it, the file defers to
+// `doctrina --help` and is never nagged about omissions.
+const CATALOG_THRESHOLD = 8;
 
 export async function run(_positional, flags) {
   const projectRoot = process.cwd();
@@ -25,6 +32,46 @@ export async function run(_positional, flags) {
     const lines = lineCount(agentsMd);
     if (lines > 200) errors.push(`AGENTS.md is ${lines} lines (>200, hard limit)`);
     else if (lines > 150) warnings.push(`AGENTS.md is ${lines} lines (>150 soft limit)`);
+
+    // 1c. AGENTS.md command-surface drift. AGENTS.md is the hub the agent reads
+    //     first, so the doctrina commands it documents must match the real CLI.
+    //     Two drifts are flagged: a reference to a command that does not exist
+    //     (a typo or a removed command — the agent will try to run it and fail),
+    //     and a maintained catalog that has fallen behind the CLI (commands the
+    //     agent never discovers because the hub never names them). validate only
+    //     checked AGENTS.md *size* before, so the hub could rot while staying
+    //     green; this closes that gap.
+    const agentsText = read(agentsMd);
+    const referenced = referencedCommands(agentsText);
+    const known = new Set(COMMAND_NAMES);
+    // Reverse drift is always flagged — a dangling command reference misleads
+    // the agent regardless of how the file is structured.
+    for (const cmd of [...referenced].sort()) {
+      if (!known.has(cmd)) {
+        warnings.push(
+          `AGENTS.md references \`doctrina ${cmd}\` which is not a CLI command ` +
+            `(typo or removed command — agents reading the hub will try to run it)`,
+        );
+      }
+    }
+    // Forward drift (omitted commands) is flagged only when the file presents
+    // itself as an exhaustive catalog: it documents many commands AND does not
+    // defer to `doctrina --help`. A file that defers is declaring its list
+    // illustrative (the shipped template does this), so its omissions are
+    // intentional and stay silent.
+    const documented = [...referenced].filter((cmd) => known.has(cmd));
+    const defersToHelp = /doctrina(?:-cli)?\s+--help/.test(agentsText);
+    if (documented.length >= CATALOG_THRESHOLD && !defersToHelp) {
+      const missing = COMMAND_NAMES.filter((cmd) => !referenced.has(cmd));
+      if (missing.length > 0) {
+        warnings.push(
+          `AGENTS.md documents the doctrina command surface but omits ` +
+            `${missing.length} command${missing.length === 1 ? "" : "s"} ` +
+            `(${missing.join(", ")}) — agents reading the hub will not discover ` +
+            `them (add them, or defer to \`doctrina --help\` for the full list)`,
+        );
+      }
+    }
   }
 
   // 1b. Nested AGENTS.md files ("nearest wins" hierarchy) obey the same
@@ -306,6 +353,23 @@ export async function run(_positional, flags) {
             }
           }
         }
+
+        // 8f. Self-certified acceptance criteria (honest gates, ADR 0008). A
+        //     criterion that asserts [verified] but cites no proof path is a
+        //     claim with nothing behind it — the dishonest-green case. `coverage`
+        //     reports every bare criterion; this names the specific combo
+        //     (claims verified, proves nothing) in the always-run gate. It reads
+        //     through the shared multi-line parser, so a proof cited on a
+        //     continuation line still counts (no false positive).
+        for (const crit of parseAcceptanceCriteria(text)) {
+          if (isVerified(crit) && crit.proofPaths.length === 0) {
+            warnings.push(
+              `${relPath(projectRoot, specPath)}: acceptance criterion #${crit.n} is marked ` +
+                `[verified] but cites no proof path — self-certified (cite the file/test in ` +
+                `backticks, or drop the marker; \`doctrina coverage\`)`,
+            );
+          }
+        }
       }
     }
   }
@@ -435,7 +499,35 @@ export async function run(_positional, flags) {
     }
   }
 
+  // 16. Bilingual docs parity. Projects that keep an EN-source docs tree
+  //     with a PT mirror (docs/en + docs/pt) get filename-parity checking:
+  //     a file added in one language and missing in the other is invisible
+  //     to every other gate, and the mirror silently falls behind. Only the
+  //     deterministic half (file sets) is checked — content staleness stays
+  //     a human judgement. Projects without both trees never see this.
+  const docsEn = path.join(projectRoot, "docs", "en");
+  const docsPt = path.join(projectRoot, "docs", "pt");
+  if (isDir(docsEn) && isDir(docsPt)) {
+    const mdSet = (dir) => new Set(readdirSync(dir).filter((f) => f.endsWith(".md")));
+    const enSet = mdSet(docsEn);
+    const ptSet = mdSet(docsPt);
+    for (const f of [...enSet].sort()) {
+      if (!ptSet.has(f)) {
+        warnings.push(`docs/en/${f} has no docs/pt/${f} counterpart (EN is the source; the PT mirror fell behind)`);
+      }
+    }
+    for (const f of [...ptSet].sort()) {
+      if (!enSet.has(f)) {
+        warnings.push(`docs/pt/${f} has no docs/en/${f} counterpart (PT translates an EN source, never leads it)`);
+      }
+    }
+  }
+
   // Output
+  if (flagBool(flags, "json", false)) {
+    console.log(JSON.stringify({ ok: errors.length === 0, errors, warnings }, null, 2));
+    return errors.length === 0 ? 0 : 1;
+  }
   for (const w of warnings) console.log(c.yellow("warn:  ") + w);
   for (const e of errors) console.log(c.red("error: ") + e);
 
@@ -549,9 +641,13 @@ function isLikelyPath(s) {
 }
 
 export const help = `
-Usage: doctrina validate
+Usage: doctrina validate [--fix] [--json]
 
 Run schema, artifact-existence, and structural checks against the
 .doctrina/ tree in the current working directory. Exits 0 if no errors
 (warnings allowed), 1 otherwise.
+
+Flags:
+  --fix    Rebuild index.json from the tree before checking (heals drift).
+  --json   Emit { ok, errors, warnings } as JSON (stable shape for agents/CI).
 `;