doctrina-cli 0.6.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

@@ -266,6 +266,27 @@ 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

package/src/commands/verify.js

@@ -3,7 +3,8 @@ import process from "node:process";
 import { readdirSync } from "node:fs";
 import { spawnSync } from "node:child_process";
 import { exists, isDir, isFile, read, write, relPath } from "../lib/fs-ops.js";
-import { flagBool } from "../lib/args.js";
+import { flagBool, flagString } from "../lib/args.js";
+import { today } from "../lib/dates.js";
 import { c } from "../lib/colors.js";
 
 // The build/verify gate `validate` is not. `validate` checks the shape of
@@ -15,6 +16,7 @@ import { c } from "../lib/colors.js";
 // `.doctrina/verify.json`, and `verify` runs exactly that, in order.
 
 const CONFIG_REL = ".doctrina/verify.json";
+const SIGNOFF_REL = ".doctrina/verify.signoffs.json";
 
 const STARTER = {
   $comment:
@@ -80,8 +82,11 @@ export async function run(_positional, flags) {
     return 1;
   }
   for (const ch of checks) {
-    if (!ch || typeof ch.run !== "string" || ch.run.trim() === "") {
-      console.error(c.red("error:") + ` every check in ${CONFIG_REL} needs a non-empty "run" string`);
+    // A "manual" check is the qualitative gate (review 2026-06-27 feature #7):
+    // a DoD item judged by a human/eval, recorded as a sign-off, not run as a
+    // command — so it needs no `run`. Every other check still needs one.
+    if (!ch || (ch.type !== "manual" && (typeof ch.run !== "string" || ch.run.trim() === ""))) {
+      console.error(c.red("error:") + ` every check in ${CONFIG_REL} needs a non-empty "run" string (or "type": "manual")`);
       return 1;
     }
   }
@@ -90,21 +95,69 @@ export async function run(_positional, flags) {
     return 1;
   }
 
+  // Sign-off store for manual checks: { "<check name>": { date, note } }.
+  const signoffPath = path.join(projectRoot, SIGNOFF_REL);
+  let signoffs = {};
+  if (isFile(signoffPath)) {
+    try { signoffs = JSON.parse(read(signoffPath)) ?? {}; } catch { signoffs = {}; }
+  }
+
+  // --signoff "<name>=<note>" records a manual check's human/eval sign-off
+  // (date stamped today) and exits. The name must be a declared manual check.
+  const signoffArg = flagString(flags, "signoff");
+  if (signoffArg !== undefined) {
+    const eq = String(signoffArg).indexOf("=");
+    const name = (eq >= 0 ? signoffArg.slice(0, eq) : signoffArg).trim();
+    const note = eq >= 0 ? signoffArg.slice(eq + 1).trim() : "";
+    const target = checks.find((ch) => (ch.name ?? "") === name && ch.type === "manual");
+    if (!target) {
+      console.error(c.red("error:") + ` no manual check named "${name}" in ${CONFIG_REL}`);
+      const manualNames = checks.filter((ch) => ch.type === "manual").map((ch) => ch.name);
+      console.error(c.gray("hint: ") + (manualNames.length
+        ? `manual checks: ${manualNames.join(", ")}`
+        : `add one: { "name": "${name || "quality"}", "type": "manual", "rubric": "<the question>" }`));
+      return 1;
+    }
+    signoffs[name] = { date: today(), note };
+    write(signoffPath, JSON.stringify(signoffs, null, 2) + "\n", { force: true });
+    console.log(c.green("signed off") + ` ${name} on ${today()}${note ? `: ${note}` : ""}`);
+    return 0;
+  }
+
   // --list prints the configured checks without running them.
   if (flagBool(flags, "list", false)) {
     console.log(c.bold("Verify checks") + c.gray(` (from ${CONFIG_REL}):`));
     console.log("");
     checks.forEach((ch, i) => {
-      console.log(`  ${i + 1}. ${c.cyan((ch.name ?? "check").padEnd(16))} ${c.gray(ch.run)}`);
+      const what = ch.type === "manual" ? c.gray(`manual${ch.rubric ? " — " + ch.rubric : ""}`) : c.gray(ch.run);
+      console.log(`  ${i + 1}. ${c.cyan((ch.name ?? "check").padEnd(16))} ${what}`);
     });
     return 0;
   }
 
+  const strict = flagBool(flags, "strict", false);
   console.log(c.bold("doctrina verify") + c.gray(` — ${checks.length} check${checks.length === 1 ? "" : "s"} from ${CONFIG_REL}`));
   const results = [];
   for (const ch of checks) {
     const name = ch.name ?? "check";
     console.log("");
+
+    // Manual (qualitative) check: pass if signed off, else pending. Pending is
+    // non-blocking by default (a report) and fails only under --strict, so CI
+    // can require the human/eval sign-off without blocking local runs.
+    if (ch.type === "manual") {
+      console.log(c.gray(`──── ${name}: `) + c.gray(`manual${ch.rubric ? " — " + ch.rubric : ""}`));
+      const so = signoffs[name];
+      if (so && so.date) {
+        console.log(c.green(`✓ ${name}`) + c.gray(` — signed off ${so.date}${so.note ? `: ${so.note}` : ""}`));
+        results.push({ name, ok: true, kind: "manual" });
+      } else {
+        console.log(c.yellow(`○ ${name} — pending sign-off`) + c.gray(` (doctrina verify --signoff "${name}=<note>")`));
+        results.push({ name, ok: false, kind: "manual", pending: true });
+      }
+      continue;
+    }
+
     const where = ch.cwd ? c.gray(` [${ch.cwd}]`) : "";
     console.log(c.gray(`──── ${name}: `) + ch.run + where);
     // Run through the shell so declared commands can use pipes, &&, env,
@@ -125,19 +178,28 @@ export async function run(_positional, flags) {
     } else {
       console.log(ok ? c.green(`✓ ${name}`) : c.red(`✗ ${name} (exit ${res.status})`));
     }
-    results.push({ name, ok });
+    results.push({ name, ok, kind: "command" });
     // Fail fast is tempting, but running every check surfaces all breakage
     // in one pass — more useful for an agent fixing the gap.
   }
 
+  const cmdFailed = results.filter((r) => r.kind === "command" && !r.ok);
+  const pending = results.filter((r) => r.pending);
   const passed = results.filter((r) => r.ok).length;
   console.log("");
-  if (passed === results.length) {
-    console.log(c.green("ok") + ` ${passed}/${results.length} checks passed`);
+  // The gate fails on any failed command check, or (only under --strict) any
+  // manual check still awaiting sign-off. Pending manual checks are otherwise
+  // a non-blocking report.
+  const failGate = cmdFailed.length > 0 || (strict && pending.length > 0);
+  const pendNote = pending.length > 0 ? c.gray(` (${pending.length} manual pending)`) : "";
+  if (!failGate) {
+    console.log(c.green("ok") + ` ${passed}/${results.length} checks passed${pendNote}`);
     return 0;
   }
-  const failed = results.filter((r) => !r.ok).map((r) => r.name).join(", ");
-  console.log(c.red("fail") + ` ${passed}/${results.length} checks passed — failed: ${failed}`);
+  const reasons = [];
+  if (cmdFailed.length > 0) reasons.push(`failed: ${cmdFailed.map((r) => r.name).join(", ")}`);
+  if (strict && pending.length > 0) reasons.push(`pending sign-off: ${pending.map((r) => r.name).join(", ")}`);
+  console.log(c.red("fail") + ` ${passed}/${results.length} checks passed — ${reasons.join("; ")}`);
   return 1;
 }
 
@@ -276,22 +338,28 @@ function findPackageJsons(projectRoot) {
 }
 
 export const help = `
-Usage: doctrina verify [--list] [--init] [--clean] [--force]
+Usage: doctrina verify [--list] [--init] [--clean] [--strict] [--signoff "<name>=<note>"] [--force]
 
 Run the project-declared build/verify checks from ${CONFIG_REL} in order,
 streaming their output, and exit non-zero if any check fails. This is the
 real "does the code work" gate, separate from the structural \`validate\`.
 
 ${CONFIG_REL} shape (an optional per-check "cwd", relative to the project
-root, targets a sub-package in a monorepo):
+root, targets a sub-package in a monorepo; a "manual" check is the
+qualitative gate — judged by a human/eval, recorded as a sign-off, not run):
   {
     "checks": [
       { "name": "typecheck", "run": "tsc --noEmit", "cwd": "packages/api" },
       { "name": "test",      "run": "npm test" },
-      { "name": "build",     "run": "npm run build" }
+      { "name": "build",     "run": "npm run build" },
+      { "name": "chronicle", "type": "manual", "rubric": "is the chronicle enjoyable to read?" }
     ]
   }
 
+A manual check passes when it has been signed off and is otherwise reported
+as "pending" — non-blocking by default, failing only under --strict (so CI
+can require the sign-off). Sign-offs are stored in ${SIGNOFF_REL}.
+
 Flags:
   --init     Scaffold a starter ${CONFIG_REL} (refuses to overwrite without --force)
   --list     Print the configured checks without running them
@@ -299,5 +367,8 @@ Flags:
              reproducibility footguns (entry points in a build dir with no
              prepare/prepack; a Prisma dep with no generate on install) so
              "verify green" can't hide a clean checkout that won't build.
+  --strict   Fail the gate when a manual check is still pending sign-off
+  --signoff "<name>=<note>"
+             Record today's sign-off for a manual check, then exit
   --force    With --init, overwrite an existing config
 `;

package/src/commands/watch.js

@@ -0,0 +1,97 @@
+import path from "node:path";
+import process from "node:process";
+import { watch as fsWatch } from "node:fs";
+import { exists } from "../lib/fs-ops.js";
+import { flagBool } from "../lib/args.js";
+import { c } from "../lib/colors.js";
+import * as validate from "./validate.js";
+import * as next from "./next.js";
+
+// Continuous keep-in-sync (review 2026-06-27 passive-user feature #4): re-run
+// `validate --fix` (heal drift, migrate the stamp) and reprint `doctrina next`
+// whenever an artifact changes, so the index stays synced and the agent stays
+// oriented without anyone invoking a command. Passive by construction. The
+// pass is debounced and ignores writes to index.json (which `--fix` itself
+// makes) so it never loops on its own output. `--once` runs a single pass and
+// exits — the testable, scriptable form.
+
+export async function run(_positional, flags) {
+  const projectRoot = process.cwd();
+  const dot = path.join(projectRoot, ".doctrina");
+  if (!exists(dot)) {
+    throw new Error("not a Doctrina project (no .doctrina/ in cwd). Run `doctrina init` first.");
+  }
+
+  if (flagBool(flags, "once", false)) {
+    return pass(projectRoot);
+  }
+
+  console.log(c.bold("doctrina watch") + c.gray(" — validate --fix + next on every change. Ctrl-C to stop."));
+  await pass(projectRoot);
+
+  let timer = null;
+  let running = false;
+  const schedule = () => {
+    if (timer) clearTimeout(timer);
+    timer = setTimeout(async () => {
+      if (running) return;
+      running = true;
+      console.log("");
+      console.log(c.gray(`──── ${new Date().toLocaleTimeString()} change detected`));
+      await pass(projectRoot);
+      running = false;
+    }, 300);
+  };
+
+  let watcher;
+  try {
+    watcher = fsWatch(dot, { recursive: true }, (_event, filename) => {
+      const name = (filename ?? "").replace(/\\/g, "/");
+      // Ignore the index the fix itself rewrites (would self-trigger forever).
+      if (name.endsWith("index.json")) return;
+      schedule();
+    });
+  } catch (err) {
+    console.error(c.red("error:") + ` could not start the watcher: ${err.message}`);
+    return 1;
+  }
+
+  // Keep the process alive until interrupted.
+  return await new Promise((resolve) => {
+    const stop = () => {
+      if (watcher) watcher.close();
+      console.log("");
+      console.log(c.gray("watch stopped."));
+      resolve(0);
+    };
+    process.on("SIGINT", stop);
+    process.on("SIGTERM", stop);
+  });
+}
+
+// One pass: heal drift, then reprint the next actions. Never throws.
+async function pass(projectRoot) {
+  try {
+    await validate.run([], new Map([["fix", true]]));
+    console.log("");
+    await next.run([], new Map());
+  } catch (err) {
+    console.error(c.red("error:") + ` ${err.message}`);
+    return 1;
+  }
+  return 0;
+}
+
+export const help = `
+Usage: doctrina watch [--once]
+
+Watch the .doctrina/ tree and, on every change, run \`doctrina validate
+--fix\` (heal index drift, migrate the framework stamp) and reprint
+\`doctrina next\` — so the index stays in sync and the agent stays oriented
+without anyone invoking a command. Debounced; ignores the index.json the
+fix itself rewrites. Runs until interrupted (Ctrl-C).
+
+Options:
+  --once     Run a single pass (validate --fix + next) and exit, instead of
+             watching. The scriptable / testable form.
+`;