doctrina-cli 0.10.0 → 0.12.0

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/upgrade.js

@@ -0,0 +1,129 @@
+import path from "node:path";
+import process from "node:process";
+import { exists } from "../lib/fs-ops.js";
+import * as idx from "../lib/index-json.js";
+import { deriveIndex, indexesMatch } from "../lib/scan.js";
+import { cliVersion } from "../lib/version.js";
+import { flagBool } from "../lib/args.js";
+import { c } from "../lib/colors.js";
+import { today } from "../lib/dates.js";
+import * as templates from "./templates.js";
+import * as validate from "./validate.js";
+
+// Bring an existing project up to the installed CLI (user-reported gap: you
+// `npm update doctrina-cli`, but the project you once `doctrina init`-ed
+// keeps its old scaffold — stale framework stamp, an AGENTS.md that predates
+// new commands, missing recommended sections). `upgrade` is the one command
+// that closes that window, and it is an ORCHESTRATOR over the pieces that
+// already exist — templates update (additive-only), index rebuild (stamp
+// migration), validate --fix — so there is exactly one definition of each
+// step. Preview by default; --write applies. Never rewrites user content
+// (the same additive-only bound as `templates update`).
+
+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 writeMode = flagBool(flags, "write", false);
+  const running = cliVersion();
+
+  // 1. Version gap: what the tree was last managed by vs what is installed.
+  let index = null;
+  let stamped = null;
+  try {
+    index = idx.load(projectRoot);
+    stamped = index.framework_version ?? null;
+  } catch {
+    index = null;
+  }
+  console.log(c.bold("doctrina upgrade") + c.gray(` — project ${stamped ?? "unstamped"} → CLI ${running}${writeMode ? "" : " (preview; --write applies)"}`));
+  console.log("");
+  if (stamped === running) {
+    console.log(c.gray("The framework stamp already matches the installed CLI — checking the scaffold anyway."));
+    console.log("");
+  }
+
+  let pending = 0;
+
+  // 2. Additive template updates (missing recommended sections in AGENTS.md /
+  //    product.md, missing index.json fields). Reuses `templates update`
+  //    verbatim: preview without --write, apply with it.
+  console.log(c.gray("──── 1/3 scaffold shape (templates update)"));
+  const tplFlags = writeMode ? new Map([["write", true]]) : new Map();
+  const tplCode = await templates.run(["update"], tplFlags);
+  if (tplCode !== 0 && !writeMode) pending += 1; // preview exits 1 when updates are pending
+
+  // 3. Index: rebuild from the tree, which also migrates the framework stamp.
+  console.log("");
+  console.log(c.gray("──── 2/3 index + framework stamp"));
+  try {
+    const current = idx.load(projectRoot);
+    const drifted = !indexesMatch(deriveIndex(projectRoot, current), current);
+    const staleStamp = (current.framework_version ?? null) !== running;
+    if (!drifted && !staleStamp) {
+      console.log(c.green("ok") + " index.json matches the tree and the stamp is current");
+    } else if (writeMode) {
+      const derived = deriveIndex(projectRoot, current);
+      derived.last_updated = today();
+      idx.save(projectRoot, derived); // save() stamps framework_version
+      console.log(c.green("rebuilt") + ` index.json${staleStamp ? ` — stamp ${current.framework_version ?? "unstamped"} → ${running}` : ""}`);
+    } else {
+      if (drifted) console.log(c.yellow("would  ") + "rebuild index.json from the tree (drifted)");
+      if (staleStamp) console.log(c.yellow("would  ") + `migrate framework stamp ${current.framework_version ?? "unstamped"} → ${running}`);
+      pending += 1;
+    }
+  } catch {
+    if (writeMode) {
+      console.log(c.red("error: ") + "index.json is missing or unreadable — run `doctrina index rebuild` manually");
+    } else {
+      console.log(c.yellow("would  ") + "rebuild index.json (missing or unreadable)");
+      pending += 1;
+    }
+  }
+
+  // 4. Full structural check — surfaces what an automatic, additive upgrade
+  //    cannot fix: an AGENTS.md documenting a stale command surface, new
+  //    validate checks the old scaffold fails, and so on. --fix under --write
+  //    so the mechanical part self-heals.
+  console.log("");
+  console.log(c.gray("──── 3/3 validate" + (writeMode ? " --fix" : "")));
+  const vFlags = writeMode ? new Map([["fix", true]]) : new Map();
+  const vCode = await validate.run([], vFlags);
+
+  console.log("");
+  if (!writeMode) {
+    if (pending > 0) {
+      console.log(c.yellow("pending") + ` upgrade steps found — apply them: ${c.cyan("doctrina upgrade --write")}`);
+      return 1;
+    }
+    console.log(c.green("ok") + " nothing to upgrade — the project matches the installed CLI");
+    return vCode;
+  }
+  if (vCode === 0) {
+    console.log(c.green(`✓ project upgraded to ${running}`) + c.gray(" — review any warnings above; new commands: `doctrina --help`."));
+    console.log(c.gray("If AGENTS.md lists the command surface, refresh that section so agents see the new commands."));
+  } else {
+    console.log(c.yellow("upgraded with findings") + " — resolve the validate errors above (they predate or exceed what an additive upgrade can fix).");
+  }
+  return vCode;
+}
+
+export const help = `
+Usage: doctrina upgrade [--write]
+
+Bring an existing project up to the installed CLI after an npm update.
+The project keeps the scaffold of the version that init-ed it; this is
+the one command that closes the gap, orchestrating the existing pieces:
+
+  1. templates update   — append missing recommended sections to AGENTS.md
+                          / product.md and missing index.json fields
+                          (additive-only; never rewrites your content)
+  2. index rebuild      — regenerate index.json from the tree and migrate
+                          the framework_version stamp to the running CLI
+  3. validate (--fix)   — surface anything the additive upgrade cannot fix
+                          (e.g. an AGENTS.md documenting a stale command
+                          surface — refresh it so agents see new commands)
+
+Preview by default (exits 1 when steps are pending); --write applies.
+`;

package/src/commands/validate.js

@@ -451,8 +451,15 @@ export async function run(_positional, flags) {
   if (index?.artifacts && isFile(ledgerPath)) {
     const ledgerIds = new Set();
     for (const line of read(ledgerPath).split(/\r?\n/)) {
-      const m = line.match(/^-\s+\d{4}-\d{2}-\d{2}\s+[—-]\s+(\S+)\s+[—-]\s+/);
-      if (m) ledgerIds.add(m[1]);
+      const m = line.match(/^-\s+\d{4}-\d{2}-\d{2}\s+[—-]\s+(\S+)\s+[—-]\s+(.*)$/);
+      if (!m) continue;
+      // An abandoned change is ledger-only BY DESIGN: `change abandon`
+      // records the discard in history but deletes the folder, so there is
+      // deliberately no archive entry to cross-check. Requiring one made
+      // every abandonment turn validate permanently red (found dogfooding
+      // change 0001-review-followups).
+      if (/^abandoned\b/i.test(m[2].trim())) continue;
+      ledgerIds.add(m[1]);
     }
     const archiveIds = new Set((index.artifacts.changes_archive ?? []).map((ch) => ch.id));
     for (const id of archiveIds) {
@@ -499,7 +506,43 @@ 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)`);
+      }
+    }
+  }
+
+  // Project rules — permanent, lintable constraints (.doctrina/rules.json;
+  // 0.11.0 field review item 12: "never reference company X" lived only in
+  // agent memory, and the remaining mentions sailed through every gate). Each
+  // rule is a forbid-regex over glob-scoped paths; a match is an ERROR with
+  // the rule's own message. Deterministic, zero-deps, and the instruction
+  // survives sessions because it is an artifact, not a memory.
+  for (const line of checkProjectRules(projectRoot)) errors.push(line);
+
   // 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);
 
@@ -513,6 +556,106 @@ export async function run(_positional, flags) {
   return errors.length === 0 ? 0 : 1;
 }
 
+// Enforce .doctrina/rules.json — permanent project constraints as
+// forbid-regexes over glob-scoped paths:
+//   { "rules": [ { "id": "white-label", "forbid": "\\bAcmeCorp\\b",
+//                  "paths": ["src/**", ".doctrina/specs/**"],
+//                  "message": "white-label product; use a generic placeholder" } ] }
+// Returns error strings (one per offending file+rule, capped per rule so a
+// mass violation stays readable). Missing/invalid file → no rules (an
+// invalid JSON is reported once). Binary-ish and vendored dirs are skipped
+// by the same bounded walk validate already uses elsewhere.
+const RULES_SKIP_DIRS = new Set([
+  ".git", "node_modules", "vendor", "dist", "build", "out", "target",
+  ".venv", "venv", "__pycache__", ".next", "coverage",
+]);
+const RULES_MAX_HITS_PER_RULE = 10;
+
+function checkProjectRules(projectRoot) {
+  const rulesPath = path.join(projectRoot, ".doctrina", "rules.json");
+  if (!isFile(rulesPath)) return [];
+  let cfg;
+  try {
+    cfg = JSON.parse(read(rulesPath));
+  } catch (err) {
+    return [`.doctrina/rules.json is not valid JSON: ${err.message}`];
+  }
+  const rules = Array.isArray(cfg?.rules) ? cfg.rules : [];
+  const out = [];
+  const compiled = [];
+  for (const r of rules) {
+    if (!r || typeof r.forbid !== "string" || !r.forbid) {
+      out.push(`.doctrina/rules.json: rule "${r?.id ?? "?"}" needs a non-empty "forbid" regex`);
+      continue;
+    }
+    let re;
+    try {
+      re = new RegExp(r.forbid, "m");
+    } catch (err) {
+      out.push(`.doctrina/rules.json: rule "${r.id ?? r.forbid}" has an invalid regex: ${err.message}`);
+      continue;
+    }
+    const paths = Array.isArray(r.paths) && r.paths.length ? r.paths : ["**"];
+    compiled.push({ id: r.id ?? r.forbid, re, matchers: paths.map(globToRegExp), message: r.message ?? "", hits: 0 });
+  }
+  if (compiled.length === 0) return out;
+
+  // One bounded walk; each text file is read at most once.
+  const stack = [projectRoot];
+  while (stack.length) {
+    const dir = stack.pop();
+    let entries;
+    try {
+      entries = readdirSync(dir, { withFileTypes: true });
+    } catch {
+      continue;
+    }
+    for (const entry of entries) {
+      const full = path.join(dir, entry.name);
+      if (entry.isDirectory()) {
+        if (!RULES_SKIP_DIRS.has(entry.name)) stack.push(full);
+        continue;
+      }
+      const rel = relPath(projectRoot, full).replace(/\\/g, "/");
+      if (rel === ".doctrina/rules.json") continue; // the rule text itself always matches
+      const applicable = compiled.filter((cr) => cr.hits < RULES_MAX_HITS_PER_RULE && cr.matchers.some((m) => m.test(rel)));
+      if (applicable.length === 0) continue;
+      let text;
+      try {
+        text = read(full);
+      } catch {
+        continue;
+      }
+      for (const cr of applicable) {
+        const m = cr.re.exec(text);
+        if (m) {
+          cr.hits += 1;
+          const lineNo = text.slice(0, m.index).split("\n").length;
+          out.push(`rule "${cr.id}": ${rel}:${lineNo} matches forbidden pattern${cr.message ? ` — ${cr.message}` : ""}`);
+        }
+      }
+    }
+  }
+  for (const cr of compiled) {
+    if (cr.hits >= RULES_MAX_HITS_PER_RULE) {
+      out.push(`rule "${cr.id}": more matches suppressed after ${RULES_MAX_HITS_PER_RULE} files`);
+    }
+  }
+  return out;
+}
+
+// Minimal glob → RegExp: ** crosses directories, * stays within a segment.
+// Anchored to the whole repo-relative POSIX path.
+function globToRegExp(glob) {
+  const esc = String(glob).replace(/[.+^${}()|[\]\\]/g, "\\$&");
+  const body = esc
+    .replace(/\*\*\//g, "(?:.*/)?")
+    .replace(/\*\*/g, ".*")
+    .replace(/\*/g, "[^/]*")
+    .replace(/\?/g, "[^/]");
+  return new RegExp(`^${body}$`);
+}
+
 // Per-entry metadata drift between the on-disk index and the tree-derived
 // one, for entries present in BOTH. Presence drift (an artifact on disk but
 // not indexed, or indexed but missing) is left to the orphan warning and the
@@ -613,9 +756,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).
 `;