doctrina-cli 0.4.0 → 0.8.0

package/src/commands/status.js

@@ -0,0 +1,178 @@
+import path from "node:path";
+import process from "node:process";
+import { readdirSync } from "node:fs";
+import { exists, isDir, isFile, read, walk } from "../lib/fs-ops.js";
+import * as idx from "../lib/index-json.js";
+import { deriveIndex, indexesMatch, specHeader, listHeader } from "../lib/scan.js";
+import { cliVersion } from "../lib/version.js";
+import { summarize as coverageSummary } from "./coverage.js";
+import { summarize as traceSummary } from "./trace.js";
+import { c } from "../lib/colors.js";
+
+// One-glance project health (review 2026-06-27 passive-user feature #1): a
+// dashboard that answers "where do things stand?" in a single read, so neither
+// the human nor the agent has to run validate + coverage + trace + next
+// separately. Strictly read-only; never mutates and always exits 0. It reports
+// the gate signals it can compute cheaply (index drift, the framework stamp,
+// coverage/trace ratios, whether verify is configured) and the artifact counts;
+// `doctrina validate` / `verify` remain the full, authoritative gates.
+
+const CONFIG_REL = ".doctrina/verify.json";
+
+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 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("");
+
+  // --- Gates ---
+  console.log(c.bold("  Gates"));
+  // Index drift (the silent rot validate now errors on).
+  let driftLine;
+  if (!index) {
+    driftLine = c.red("missing/unreadable") + c.gray(" — run `doctrina index rebuild`");
+  } else if (indexesMatch(deriveIndex(projectRoot, index), index)) {
+    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
+    ? c.green("current")
+    : c.yellow(`${stamp} (CLI ${cli})`) + c.gray(" — `doctrina index rebuild`");
+  console.log(`    ${"stamp".padEnd(11)} ${stampLine}`);
+
+  // Coverage and trace ratios.
+  const cov = coverageSummary(projectRoot);
+  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 trExtra = tr.untraceable + tr.dropped + tr.dangling > 0
+    ? c.yellow(` ${tr.dropped} dropped, ${tr.untraceable} untraceable`)
+    : "";
+  const trColor = tr.anchors === 0 ? c.gray : (tr.realized === tr.anchors && tr.untraceable === 0 ? c.green : c.yellow);
+  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");
+    }
+  }
+  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 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}`);
+
+  console.log("");
+  console.log(c.gray("  Full gates: `doctrina validate` · `doctrina verify`.  Next step: `doctrina next`."));
+  return 0;
+}
+
+function countSpecs(projectRoot) {
+  const specsDir = path.join(projectRoot, ".doctrina", "specs");
+  const impl = {};
+  let total = 0;
+  if (isDir(specsDir)) {
+    for (const cap of readdirSync(specsDir).sort()) {
+      const p = path.join(specsDir, cap, "spec.md");
+      if (!isFile(p)) continue;
+      total += 1;
+      const implRaw = specHeader(read(p), "Implementation");
+      if (implRaw) {
+        const word = implRaw.trim().split(/[\s—-]+/)[0].toLowerCase();
+        impl[word] = (impl[word] ?? 0) + 1;
+      }
+    }
+  }
+  const changesDir = path.join(projectRoot, ".doctrina", "changes");
+  let openChanges = 0;
+  if (isDir(changesDir)) {
+    for (const e of readdirSync(changesDir)) {
+      if (e === "archive" || e.startsWith(".")) continue;
+      if (isDir(path.join(changesDir, e))) openChanges += 1;
+    }
+  }
+  return { total, impl, openChanges };
+}
+
+function countDecisions(projectRoot) {
+  const adrDir = path.join(projectRoot, ".doctrina", "decisions");
+  let total = 0, proposed = 0, bare = 0;
+  const isBare = (v) => {
+    const t = (v ?? "").trim();
+    return t === "" || t === "—" || t === "-";
+  };
+  if (isDir(adrDir)) {
+    for (const f of walk(adrDir)) {
+      if (!/^\d{4}-.+\.md$/.test(path.basename(f))) continue;
+      total += 1;
+      const text = read(f);
+      const status = (listHeader(text, "Status") ?? "").toLowerCase();
+      if (status === "proposed") proposed += 1;
+      if (status === "accepted") {
+        const evidence = listHeader(text, "Evidence");
+        const landed = listHeader(text, "Landed");
+        if (evidence !== null && isBare(evidence) && isBare(landed)) bare += 1;
+      }
+    }
+  }
+  return { total, proposed, bare };
+}
+
+function countSkills(projectRoot) {
+  const skillsDir = path.join(projectRoot, ".doctrina", "skills");
+  if (!isDir(skillsDir)) return 0;
+  return walk(skillsDir).filter((f) => f.endsWith(".md")).length;
+}
+
+export const help = `
+Usage: doctrina status
+
+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.
+
+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

@@ -106,6 +106,37 @@ export async function run(_positional, flags) {
   return strict ? 1 : 0;
 }
 
+// Pure summary of intent provenance, for other commands (`status`, `review`)
+// that need the numbers without the report output.
+export function summarize(projectRoot) {
+  const anchors = collectAnchors(projectRoot);
+  const specs = collectSpecs(projectRoot);
+  const anchorIds = new Set(anchors.map((a) => a.id));
+  const realizedBy = new Map();
+  let dangling = 0;
+  for (const s of specs) {
+    if (s.realizes === null) continue;
+    for (const id of s.realizes) {
+      if (anchorIds.has(id)) {
+        if (!realizedBy.has(id)) realizedBy.set(id, []);
+        realizedBy.get(id).push(s.cap);
+      } else {
+        dangling += 1;
+      }
+    }
+  }
+  const untraceable = specs.filter((s) => s.realizes === null && s.status === "active").length;
+  let realized = 0;
+  for (const a of anchors) if ((realizedBy.get(a.id) ?? []).length > 0) realized += 1;
+  return {
+    anchors: anchors.length,
+    realized,
+    dropped: anchors.length - realized,
+    dangling,
+    untraceable,
+  };
+}
+
 // Every "[A-Z]+\d+" tag at the head of a bullet in product.md is an intent
 // anchor. Section-agnostic so Success-criteria and In-scope bullets both work.
 function collectAnchors(projectRoot) {

package/src/commands/validate.js

@@ -5,12 +5,14 @@ import { exists, isDir, isFile, lineCount, read, relPath, walk } from "../lib/fs
 import * as idx from "../lib/index-json.js";
 import { SCHEMA_VERSION } from "../lib/index-json.js";
 import { cliVersion } from "../lib/version.js";
+import { today } from "../lib/dates.js";
+import { flagBool } from "../lib/args.js";
 import { c } from "../lib/colors.js";
 import { parseFrontmatter } from "./skill.js";
 import { checkEars, isEarsSpec } from "../lib/ears.js";
-import { specHeader, listHeader } from "../lib/scan.js";
+import { specHeader, listHeader, deriveIndex, indexesMatch, stableStringify } from "../lib/scan.js";
 
-export async function run(_positional, _flags) {
+export async function run(_positional, flags) {
   const projectRoot = process.cwd();
   const errors = [];
   const warnings = [];
@@ -47,6 +49,22 @@ export async function run(_positional, _flags) {
   }
 
   if (index) {
+    // --fix (F5): regenerate the index from the tree before validating, so a
+    // drifted index is repaired rather than reported. A full rebuild — it also
+    // absorbs orphans and migrates the framework stamp, matching
+    // `index rebuild`. Subsequent checks then see the repaired index.
+    if (flagBool(flags, "fix", false)) {
+      const derived = deriveIndex(projectRoot, index);
+      const staleStamp = (index.framework_version ?? null) !== cliVersion();
+      if (!indexesMatch(derived, index) || staleStamp) {
+        derived.framework_version = cliVersion();
+        derived.last_updated = today();
+        idx.save(projectRoot, derived);
+        console.log(c.green("fixed") + " rebuilt .doctrina/index.json from the tree");
+        index = derived;
+      }
+    }
+
     if (index.$schema_version !== SCHEMA_VERSION) {
       warnings.push(`index.json $schema_version is "${index.$schema_version}" (expected "${SCHEMA_VERSION}")`);
     }
@@ -78,15 +96,18 @@ export async function run(_positional, _flags) {
         if (!exists(full)) errors.push(`index.json references missing artifact: ${rel}`);
       }
 
-      // 4b. Spec version drift — the Version: header inside each spec
-      //     must match the version recorded in index.json.
-      for (const s of index.artifacts.specs ?? []) {
-        const full = path.join(projectRoot, s.path);
-        if (!isFile(full)) continue;
-        const m = read(full).match(/^(?:-\s+)?\*\*Version:\*\*\s+(\S+)/m);
-        if (m && s.version && m[1] !== s.version) {
-          warnings.push(`${s.path} declares version ${m[1]} but index.json records ${s.version} (sync the index)`);
-        }
+      // 4b. Index metadata drift (F5 / review G5 / G7). validate is the single
+      //     source of truth about whether the project is OK, so an indexed
+      //     artifact whose recorded metadata (version, implementation, status,
+      //     ...) no longer matches its file is an ERROR here — not a
+      //     pass-with-warning that only `index rebuild --check` would catch
+      //     (the "validate says OK while next says drift" footgun). Presence
+      //     drift (orphan on disk / missing file) stays the orphan warning and
+      //     the missing-artifact error above; this targets the metadata that
+      //     silently lies. `validate --fix` (above) regenerates instead.
+      const derived = deriveIndex(projectRoot, index);
+      for (const line of metadataDrift(index, derived)) {
+        errors.push(`${line} — run \`doctrina validate --fix\` or \`doctrina index rebuild\``);
       }
     }
   }
@@ -206,6 +227,7 @@ export async function run(_positional, _flags) {
   const specsDir = path.join(projectRoot, ".doctrina", "specs");
   if (isDir(specsDir)) {
     const { readdirSync } = await import("node:fs");
+    const KNOWN_SPEC_HEADERS = ["Capability", "Status", "Implementation", "Version", "Last updated", "Realizes"];
     for (const cap of readdirSync(specsDir)) {
       const specPath = path.join(specsDir, cap, "spec.md");
       if (isFile(specPath)) {
@@ -243,6 +265,47 @@ export async function run(_positional, _flags) {
             );
           }
         }
+
+        // 8e. Provenance adoption (review 2026-06-27, §5/§9). `trace` is the
+        //     intent→capability link, but it stays inert when nothing forces
+        //     the tag, so an active capability with no Realizes: header is an
+        //     untraced promise — warn here (validate is always run) rather than
+        //     only in the opt-in `trace`. Advisory, with the same escape hatch
+        //     pattern as Implementation: any value silences it, including a
+        //     deliberate "n/a — <why>" for an internal capability that maps to
+        //     no product anchor. Bug specs (off the implementation axis) and
+        //     draft/deprecated documents are exempt — only active capability
+        //     specs make the promise.
+        const docStatusForRealizes = (specHeader(text, "Status") ?? "active").toLowerCase();
+        const onImplAxis = specHeader(text, "Implementation") !== null;
+        if (docStatusForRealizes === "active" && onImplAxis && specHeader(text, "Realizes") === null) {
+          warnings.push(
+            `${relPath(projectRoot, specPath)}: active spec has no Realizes: header — ` +
+              `it traces to no product intent (\`doctrina trace\`). Tag a product.md ` +
+              `success-criteria bullet "- [SC1] ..." and add "**Realizes:** SC1", or ` +
+              `record "**Realizes:** n/a — <why>" if it maps to no product anchor`,
+          );
+        }
+
+        // 8d. Metadata-header shape (review G11). In the header block (before
+        //     the first `## ` section or `<!--` comment), a known key written
+        //     without the canonical `**Key:** value` form silently fails to
+        //     parse — the index then falls back to a default and drifts. Warn
+        //     with the fix rather than letting the mis-typed header vanish.
+        const headerLines = text.split(/\r?\n/);
+        for (let i = 0; i < headerLines.length; i++) {
+          if (/^\s*(##\s|<!--)/.test(headerLines[i])) break;
+          for (const key of KNOWN_SPEC_HEADERS) {
+            const attempt = new RegExp(`^\\s*-?\\s*\\**${key}\\**\\s*:`, "i");
+            const canonical = new RegExp(`^(?:-\\s+)?\\*\\*${key}:\\*\\*\\s+\\S`);
+            if (attempt.test(headerLines[i]) && !canonical.test(headerLines[i])) {
+              warnings.push(
+                `${relPath(projectRoot, specPath)}:${i + 1} metadata header "${key}" is not in ` +
+                  `canonical "**${key}:** value" form — it will not parse (G11)`,
+              );
+            }
+          }
+        }
       }
     }
   }
@@ -386,6 +449,29 @@ export async function run(_positional, _flags) {
   return errors.length === 0 ? 0 : 1;
 }
 
+// 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
+// missing-artifact error; this isolates the case the review hit — an indexed
+// artifact whose recorded metadata no longer matches its file.
+function metadataDrift(current, derived) {
+  const lines = [];
+  // Skills are deliberately excluded: their description has a dedicated
+  // reconciliation command (`doctrina skill sync`) and stays an advisory
+  // warning (see section 15), not a hard error.
+  const cats = ["specs", "decisions", "changes", "changes_archive", "contracts"];
+  for (const cat of cats) {
+    const cur = new Map((current.artifacts?.[cat] ?? []).map((e) => [e.id, e]));
+    const der = new Map((derived.artifacts?.[cat] ?? []).map((e) => [e.id, e]));
+    for (const [id, entry] of cur) {
+      if (der.has(id) && stableStringify(entry) !== stableStringify(der.get(id))) {
+        lines.push(`index.json: ${cat} "${id}" metadata differs from its file`);
+      }
+    }
+  }
+  return lines;
+}
+
 // Find AGENTS.md files below the root (the "nearest AGENTS.md wins"
 // hierarchy). Bounded walk: dependency, build, and VCS directories are
 // skipped so validate stays fast on large repositories.