doctrina-cli 0.2.2 → 0.4.0

package/src/commands/decision.js

@@ -8,7 +8,7 @@ import { today, slugify, padNumber } from "../lib/dates.js";
 import { c } from "../lib/colors.js";
 import { suggest } from "../lib/suggest.js";
 
-const SUBCOMMANDS = ["new", "supersede", "accept", "list"];
+const SUBCOMMANDS = ["new", "supersede", "accept", "land", "list"];
 
 export async function run(positional, _flags) {
   const sub = positional[0];
@@ -19,6 +19,8 @@ export async function run(positional, _flags) {
       return decisionSupersede(positional.slice(1));
     case "accept":
       return decisionAccept(positional.slice(1));
+    case "land":
+      return decisionLand(positional.slice(1));
     case "list":
       return decisionList();
     default:
@@ -198,6 +200,81 @@ function decisionAccept(args) {
   return 0;
 }
 
+// Record that an accepted ADR is now implemented and verified, without
+// editing the immutable body. Mutates ONLY the **Landed:** header line (the
+// same "headers are updatable, the decision prose is not" pattern that accept
+// and supersede already use), stamping today's date plus any cited proof
+// paths. This closes the gap where a design-time ADR ("Evidence: n/a — no
+// implementation yet") had no first-class way to record that reality caught up
+// short of a heavyweight supersede. (3.4)
+function decisionLand(args) {
+  const target = args[0];
+  if (!target) {
+    console.error(c.red("error:") + " decision land requires the target ADR number (e.g. 0003)");
+    return 2;
+  }
+  const projectRoot = process.cwd();
+  ensureDoctrinaProject(projectRoot);
+
+  const padded = padNumber(parseInt(target, 10));
+  const adrDir = path.join(projectRoot, ".doctrina", "decisions");
+  const file = walk(adrDir).find((f) => path.basename(f).startsWith(`${padded}-`));
+  if (!file) {
+    console.error(c.red("error:") + ` no ADR found with number ${padded} in ${relPath(projectRoot, adrDir)}`);
+    return 1;
+  }
+  const text = read(file);
+  const statusMatch = text.match(/^-\s+\*\*Status:\*\*\s+(.+)$/m);
+  if (!statusMatch) {
+    console.error(c.red("error:") + ` ADR at ${relPath(projectRoot, file)} has no Status: header`);
+    return 1;
+  }
+  const status = statusMatch[1].trim().toLowerCase();
+  if (status !== "accepted") {
+    console.error(
+      c.red("error:") +
+        ` ADR ${padded} is "${statusMatch[1].trim()}", not "accepted" — accept it before recording that it landed`,
+    );
+    return 1;
+  }
+
+  const date = today();
+  const proofPaths = args.slice(1).filter(Boolean);
+  const cited = proofPaths.map((p) => `\`${p}\``).join(", ");
+  const landedValue = cited ? `${date} — ${cited}` : date;
+
+  // Rewrite the existing Landed header, or insert one (after Evidence, else
+  // after Status) for ADRs that predate the field. The body stays untouched.
+  let updated;
+  if (/^-\s+\*\*Landed:\*\*/m.test(text)) {
+    updated = text.replace(/^(-\s+\*\*Landed:\*\*)\s+.*$/m, `$1 ${landedValue}`);
+  } else if (/^-\s+\*\*Evidence:\*\*.*$/m.test(text)) {
+    updated = text.replace(/^(-\s+\*\*Evidence:\*\*.*)$/m, `$1\n- **Landed:** ${landedValue}`);
+  } else {
+    updated = text.replace(/^(-\s+\*\*Status:\*\*.*)$/m, `$1\n- **Landed:** ${landedValue}`);
+  }
+  write(file, updated, { force: true });
+  console.log(c.green("landed") + ` ${relPath(projectRoot, file)} on ${date}`);
+
+  const index = idx.load(projectRoot);
+  // Store the same value the header now carries, so the index matches what
+  // `index rebuild` would derive from the file (no perpetual drift).
+  idx.updateDecision(index, padded, () => ({ landed: landedValue }));
+  idx.touch(index, date);
+  idx.save(projectRoot, index);
+  console.log(c.green("indexed") + ` decision ${padded} landed`);
+
+  // Parity with `validate`: cited proof that does not resolve is a dangling
+  // citation, surfaced now rather than at the next validate.
+  for (const p of proofPaths) {
+    const candidates = [path.resolve(path.dirname(file), p), path.resolve(projectRoot, p)];
+    if (!candidates.some(exists)) {
+      console.log(c.yellow("warn:") + ` cited proof \`${p}\` not found on disk`);
+    }
+  }
+  return 0;
+}
+
 function decisionList() {
   const projectRoot = process.cwd();
   ensureDoctrinaProject(projectRoot);
@@ -259,6 +336,11 @@ Subcommands:
   new "<title>"                        Create the next sequentially numbered ADR
   accept <number>                      Flip a proposed ADR to accepted (rewrites
                                        only the Status: header) and update the index
+  land <number> [path ...]             Stamp an accepted ADR as implemented:
+                                       rewrites only the Landed: header with today's
+                                       date plus any cited proof paths. The decision
+                                       body stays immutable. Satisfies the accepted-
+                                       ADR evidence check without a supersede.
   supersede <number> "<new title>"     Create a new ADR that supersedes the target
                                        and rewrite the target's Status: header
   list                                 One line per ADR: number, status, date,

package/src/commands/index-rebuild.js

@@ -3,6 +3,7 @@ import process from "node:process";
 import { exists } from "../lib/fs-ops.js";
 import * as idx from "../lib/index-json.js";
 import { deriveIndex, indexesMatch, stableStringify } from "../lib/scan.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";
@@ -42,6 +43,11 @@ function rebuild(flags) {
   }
 
   const derived = deriveIndex(projectRoot, current);
+  // Migrate the framework stamp to the running CLI (3.6). deriveIndex carries
+  // the old value over (so `next` does not nag on a version-only difference);
+  // overriding it here lets a stale stamp count as drift, so `index rebuild`
+  // both reports and fixes it instead of short-circuiting on "nothing to do".
+  derived.framework_version = cliVersion();
 
   if (indexesMatch(derived, current)) {
     console.log(c.green("ok") + " index.json matches the tree (nothing to do)");
@@ -72,6 +78,9 @@ function rebuild(flags) {
 function describeDrift(current, derived) {
   const lines = [];
   if (!current) return ["index.json missing or unreadable"];
+  if ((current.framework_version ?? null) !== (derived.framework_version ?? null)) {
+    lines.push(`framework_version: ${current.framework_version ?? "unset"} -> ${derived.framework_version}`);
+  }
   const categories = ["specs", "decisions", "changes", "changes_archive", "skills"];
   for (const cat of categories) {
     const cur = new Map((current.artifacts?.[cat] ?? []).map((e) => [e.id, e]));

package/src/commands/init.js

@@ -3,10 +3,11 @@ import process from "node:process";
 import { exists, isDir, isFile, read, relPath, write } from "../lib/fs-ops.js";
 import { locateTemplatesDir, loadTemplateTree, materialiseEntry, substitute } from "../lib/templates.js";
 import { today } from "../lib/dates.js";
+import { cliVersion } from "../lib/version.js";
 import { flagBool, flagString } from "../lib/args.js";
 import { c } from "../lib/colors.js";
 import { ask } from "../lib/prompt.js";
-import { writeIntakeFile, printBootstrapPlaybook } from "./intake.js";
+import { writeIntakeFile, printBootstrapPlaybook, warnIfThinIntake } from "./intake.js";
 
 const SUPPORTED_AGENTS = [
   "claude",
@@ -90,6 +91,10 @@ export async function run(_positional, flags) {
     PROJECT_DESCRIPTION: description,
     DATE: date,
     AGENTS_MD_PATH: "AGENTS.md",
+    // Stamp the framework version into the scaffolded index.json. init writes
+    // it straight from the template (bypassing idx.save), so the token is the
+    // stamp point here. (3.6)
+    FRAMEWORK_VERSION: cliVersion(),
   };
 
   // Root AGENTS.md — with optional --from base content prepended.
@@ -154,6 +159,7 @@ export async function run(_positional, flags) {
     console.log(`${c.cyan(".doctrina/product.md")} and capability specs. Any AGENTS.md-aware agent`);
     console.log(`runs it on its own; reprint anytime with ${c.cyan("doctrina intake")}.`);
     console.log("");
+    warnIfThinIntake(intakeBody);
     printBootstrapPlaybook(projectRoot);
   } else {
     console.log(`Next: edit ${c.cyan("AGENTS.md")} and ${c.cyan(".doctrina/product.md")} for your project.`);

package/src/commands/intake.js

@@ -2,6 +2,7 @@ import path from "node:path";
 import process from "node:process";
 import { exists, isFile, read, relPath, write } from "../lib/fs-ops.js";
 import { listHeader } from "../lib/scan.js";
+import { assessBrief } from "../lib/clarity.js";
 import * as idx from "../lib/index-json.js";
 import { today } from "../lib/dates.js";
 import { flagBool, flagString } from "../lib/args.js";
@@ -69,10 +70,23 @@ export async function run(positional, flags) {
   writeIntakeFile(projectRoot, { body, source, projectName, date: today(), force });
   console.log(c.green("created") + ` ${relPath(projectRoot, intakePath)}`);
   console.log("");
+  warnIfThinIntake(body);
   printBootstrapPlaybook(projectRoot);
   return 0;
 }
 
+// Clarification gate (review Topic A). A description too thin to spec from is
+// the moment to ask the user, not to let the agent invent requirements. Prints
+// the specific gaps before the bootstrap playbook; advisory, never blocking —
+// the intake is still captured verbatim (the playbook step 6 resolves it).
+export function warnIfThinIntake(body) {
+  const assessment = assessBrief(body, { kind: "intake" });
+  if (!assessment.thin) return;
+  console.log(c.yellow("⚠ thin intake — clarify with the user before converting to specs:"));
+  for (const reason of assessment.reasons) console.log(`    - ${reason}`);
+  console.log("");
+}
+
 // Shared with `init --intake`. Writes the intake verbatim under a small
 // status header; the agent flips Status to converted at the end of the
 // playbook, which is how `next` knows the bootstrap is done.
@@ -110,7 +124,9 @@ export function printBootstrapPlaybook(projectRoot) {
   console.log(`1. Read ${c.cyan(".doctrina/intake.md")} (raw intent) and ${c.cyan(".doctrina/product.md")}.`);
   console.log("");
   console.log("2. Fill every product.md section from the intake: Vision, Problem,");
-  console.log("   Target users, Scope (in/out), Non-goals, Success criteria.");
+  console.log("   Target users, Scope (in/out), Non-goals, Success criteria, and the");
+  console.log("   Delivery order — name the ONE end-to-end walking skeleton to build");
+  console.log("   and verify before fanning out (depth before breadth).");
   console.log("   One fact, one home — product.md holds vision, never requirements.");
   console.log("");
   console.log("3. Derive the capability list: kebab-case, one per area of behaviour");
@@ -119,22 +135,29 @@ export function printBootstrapPlaybook(projectRoot) {
   console.log("   then replace the template placeholders in");
   console.log("   .doctrina/specs/<capability>/spec.md with EARS requirements derived");
   console.log("   from the intake (Ubiquitous / Event-driven / State-driven /");
-  console.log("   Unwanted-behavior / Optional). Remove section stubs you do not use,");
-  console.log("   and write concrete Acceptance criteria.");
+  console.log("   Unwanted-behavior / Optional). Keep the two axes honest — leave");
+  console.log("   Implementation: planned for what is not built yet; keep aspiration");
+  console.log("   under ## Maturity → Future, not in EARS; write concrete Acceptance");
+  console.log("   criteria, each [unverified] until a cited test proves it.");
+  console.log("");
+  console.log("4. If the project spans services/front-ends, own the seams between");
+  console.log("   them (port map, env, API/WS/event shapes) as a contract:");
+  console.log(`       ${c.cyan("doctrina contract new <name>")} → fill it → ${c.cyan("doctrina contract check")}`);
   console.log("");
-  console.log("4. Record any architectural decision the intake forces:");
+  console.log("5. Record any architectural decision the intake forces (cite Evidence):");
   console.log(`       ${c.cyan("doctrina decision new \"<title>\"")} → edit → ${c.cyan("doctrina decision accept <num>")}`);
   console.log("");
-  console.log("5. Quality gates — fix everything they report before moving on:");
+  console.log("6. Quality gates — fix everything they report before moving on:");
   console.log(`       ${c.cyan("doctrina clarify --all")}`);
   console.log(`       ${c.cyan("doctrina validate")}`);
+  console.log(`       ${c.cyan("doctrina coverage")}   (and ${c.cyan("doctrina verify --init")} to declare the build gate)`);
   console.log("   If something in the intake is genuinely ambiguous, ask the user");
   console.log("   before assuming.");
   console.log("");
-  console.log("6. Mark the intake consumed: in .doctrina/intake.md flip");
+  console.log("7. Mark the intake consumed: in .doctrina/intake.md flip");
   console.log("   \"- **Status:** pending\" to \"- **Status:** converted\".");
   console.log("");
-  console.log(`7. ${c.cyan("doctrina next")} — follow the recommendation. Implementation then`);
+  console.log(`8. ${c.cyan("doctrina next")} — follow the recommendation. Implementation then`);
   console.log(`   flows through ${c.cyan("doctrina work \"<brief prompt>\"")}, one change at a time.`);
   if (!hasSpecs) {
     console.log("");
@@ -149,7 +172,8 @@ Store the full project description verbatim at .doctrina/intake.md and
 print the bootstrap playbook — the ordered instruction sequence the host
 AI agent executes to convert the intake into product.md content and
 capability specs (see ADR 0005). The CLI itself does no natural-language
-interpretation.
+interpretation. A thin/under-specified description is flagged so the agent
+clarifies with the user before converting (advisory, never blocking).
 
 Forms:
   doctrina intake <file>              Ingest a description file

package/src/commands/search.js

@@ -6,7 +6,14 @@ import { c } from "../lib/colors.js";
 
 // Category-aware full-text search across the artifact tree. Answers
 // "where is X specified / decided / proposed?" without knowing the
-// layout. Plain substring matching, every term must hit (AND).
+// layout. Plain substring matching, every term must hit (AND) on a line.
+//
+// Results are ranked, not dumped in file order: each hit is scored (a match
+// in a heading or metadata header, or an adjacent full-phrase match, outranks
+// a bare body line), files are scored by their hits plus a filename bonus, and
+// files within a category print best-first. This mirrors the framework's own
+// "ranked selection over dumping" thesis — at scale the agent reads the most
+// relevant hit first instead of scanning an unordered list.
 
 const MAX_MATCHES_PER_FILE = 5;
 
@@ -16,6 +23,7 @@ export async function run(positional, flags) {
     console.error(c.red("error:") + " search requires at least one term");
     return 2;
   }
+  const phrase = terms.join(" ");
   const includeArchive = flagBool(flags, "archive", false);
   const projectRoot = process.cwd();
   if (!exists(path.join(projectRoot, ".doctrina"))) {
@@ -48,16 +56,22 @@ export async function run(positional, flags) {
       const lines = read(f).split("\n");
       const hits = [];
       for (let i = 0; i < lines.length; i++) {
-        const low = lines[i].toLowerCase();
+        const raw = lines[i];
+        const low = raw.toLowerCase();
         if (terms.every((t) => low.includes(t))) {
-          hits.push({ line: i + 1, text: lines[i].trim() });
-          if (hits.length === MAX_MATCHES_PER_FILE) break;
+          hits.push({ line: i + 1, text: raw.trim(), score: lineScore(raw, low, phrase) });
         }
       }
-      if (hits.length > 0) findings.push({ rel, hits });
+      if (hits.length === 0) continue;
+      // Keep the highest-scoring lines (best-first), not merely the first few.
+      hits.sort((a, b) => b.score - a.score || a.line - b.line);
+      const fileScore = hits.reduce((s, h) => s + h.score, 0) + filenameBonus(rel, terms);
+      findings.push({ rel, hits: hits.slice(0, MAX_MATCHES_PER_FILE), score: fileScore });
     }
 
     if (findings.length === 0) continue;
+    // Most relevant file first; stable tie-break by path.
+    findings.sort((a, b) => b.score - a.score || a.rel.localeCompare(b.rel));
     console.log(c.bold(cat.name));
     for (const file of findings) {
       filesWithMatches += 1;
@@ -81,13 +95,34 @@ function truncate(s, n) {
   return s.length > n ? s.slice(0, n - 1) + "…" : s;
 }
 
+// Relevance of a single matching line. A heading or metadata-header line
+// names the topic; an adjacent full-phrase match means the terms occur
+// together, not scattered. Both outrank a bare body line.
+function lineScore(raw, low, phrase) {
+  let s = 1;
+  if (/^\s*#{1,6}\s/.test(raw)) s += 2;
+  if (/\*\*[^*]+:\*\*/.test(raw)) s += 1;
+  if (phrase && low.includes(phrase)) s += 2;
+  return s;
+}
+
+// A file whose name carries the query is almost always the right one;
+// reward a full filename match more than a partial one.
+function filenameBonus(rel, terms) {
+  const base = rel.toLowerCase();
+  if (terms.every((t) => base.includes(t))) return 3;
+  return terms.some((t) => base.includes(t)) ? 1 : 0;
+}
+
 export const help = `
 Usage: doctrina search <term> [<term> ...] [--archive]
 
 Case-insensitive substring search across the artifact tree, grouped
 by category (specs, decisions, changes, skills, product, AGENTS.md).
-Every term must match on the same line. The change archive is
-excluded unless --archive is passed.
+Every term must match on the same line. Within each category, files are
+ranked best-first (heading / metadata / full-phrase / filename matches
+score higher), and the highest-scoring lines per file are shown. The
+change archive is excluded unless --archive is passed.
 
 Exits 0 when matches are found, 1 otherwise. Read-only.
 `;

package/src/commands/spec.js

@@ -51,13 +51,20 @@ export async function run(positional, flags) {
   console.log(c.green("created") + ` ${relPath(projectRoot, targetPath)}${bug ? " (bug-spec shape)" : ""}`);
 
   const index = idx.load(projectRoot);
-  idx.addSpec(index, {
+  // Two axes: a fresh capability scaffold is a draft document for a
+  // planned capability. Promote `status` to active once it reflects
+  // intent; advance `implementation` as code lands (see `doctrina
+  // coverage`). Bug specs are a different shape and stay off the
+  // implementation axis — only the capability template carries it.
+  const entry = {
     id: capability,
     path: `.doctrina/specs/${capability}/spec.md`,
-    status: "active",
+    status: bug ? "active" : "draft",
     version: "0.1.0",
     last_updated: date,
-  });
+  };
+  if (!bug) entry.implementation = "planned";
+  idx.addSpec(index, entry);
   idx.touch(index, date);
   idx.save(projectRoot, index);
   console.log(c.green("indexed") + ` spec "${capability}"`);
@@ -75,10 +82,14 @@ function specList() {
       const p = path.join(specsDir, cap, "spec.md");
       if (!isFile(p)) continue;
       const text = read(p);
+      // Show only the leading state word of Implementation, dropping any
+      // explanatory note after it ("planned — deferred" -> "planned").
+      const implRaw = specHeader(text, "Implementation");
       rows.push({
         id: cap,
         version: specHeader(text, "Version") ?? "—",
         status: specHeader(text, "Status") ?? "active",
+        impl: implRaw ? implRaw.trim().split(/[\s—-]+/)[0] : "—",
         lines: lineCount(p),
         updated: specHeader(text, "Last updated") ?? "—",
       });
@@ -88,10 +99,10 @@ function specList() {
     console.log(c.gray("no specs found in .doctrina/specs/"));
     return 0;
   }
-  console.log(c.bold("Specs:"));
+  console.log(c.bold("Specs:") + c.gray("  (status = document, impl = capability)"));
   console.log("");
   for (const r of rows) {
-    console.log(`  ${c.cyan(r.id.padEnd(20))} ${r.version.padEnd(8)} ${r.status.padEnd(10)} ${String(r.lines).padStart(4)} lines  ${r.updated}`);
+    console.log(`  ${c.cyan(r.id.padEnd(20))} ${r.version.padEnd(8)} ${r.status.padEnd(10)} ${r.impl.padEnd(12)} ${String(r.lines).padStart(4)} lines  ${r.updated}`);
   }
   console.log("");
   console.log(c.gray(`${rows.length} spec${rows.length === 1 ? "" : "s"}`));

package/src/commands/templates.js

@@ -89,7 +89,7 @@ function updateTemplates(flags) {
       if (idx.$schema_version === undefined) describe.push('index.json: add "$schema_version": "0.1.0"');
       if (idx.project === undefined) describe.push(`index.json: add "project": "${path.basename(projectRoot)}"`);
       if (idx.artifacts === undefined) describe.push('index.json: add empty "artifacts" object');
-      const categories = ["specs", "decisions", "changes", "changes_archive", "skills"];
+      const categories = ["specs", "decisions", "changes", "changes_archive", "skills", "contracts"];
       for (const cat of categories) {
         if (idx.artifacts && idx.artifacts[cat] === undefined) {
           describe.push(`index.json: add empty artifact category "${cat}"`);

package/src/commands/trace.js

@@ -0,0 +1,157 @@
+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 { specHeader } from "../lib/scan.js";
+import { flagBool } from "../lib/args.js";
+import { c } from "../lib/colors.js";
+
+// Intent-provenance report (ADR 0006). `coverage` proves a criterion has a
+// test; `trace` proves a capability traces to a stated intent. Together they
+// form the chain product-intent -> capability -> criterion -> test.
+//
+// Conventions (all opt-in; absent markers are "not yet traced", not errors):
+//   - product.md tags an intent anchor at the head of a bullet: "- [SC1] ...".
+//     Any "[A-Z]+\d+" tag is an anchor (Success criteria, In scope, ...).
+//   - a capability spec declares "**Realizes:** SC1, SC3".
+//
+// trace reports three provenance breaks: dropped intent (an anchor no spec
+// realizes), dangling realizes (a spec cites an unknown id), and untraceable
+// spec (an active spec with no Realizes: header). It is read-only; --strict
+// turns any break into a non-zero exit for CI.
+//
+// What it does NOT do (the honest ceiling, per ADR 0006): judge whether a
+// criterion faithfully encodes the intent. That semantic check is deferred to
+// a future LLM-assisted layer and is never claimed by this deterministic gate.
+
+const ANCHOR_RE = /[A-Z]+\d+/g;
+
+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 strict = flagBool(flags, "strict", false);
+
+  const anchors = collectAnchors(projectRoot); // [{ id }], in document order
+  const specs = collectSpecs(projectRoot); // [{ cap, status, realizes: [id] }]
+
+  const anchorIds = new Set(anchors.map((a) => a.id));
+  const anyRealizes = specs.some((s) => s.realizes !== null);
+
+  // The feature is unused: do not nag a project that never opted in.
+  if (anchors.length === 0 && !anyRealizes) {
+    console.log(
+      c.gray(
+        "no intent-provenance markers found — tag product.md bullets with `[SC1]` " +
+          "and add `**Realizes:** SC1` to the specs that deliver them",
+      ),
+    );
+    return 0;
+  }
+
+  // anchor id -> [capability]
+  const realizedBy = new Map();
+  const dangling = []; // { cap, id }
+  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.push({ cap: s.cap, id });
+      }
+    }
+  }
+  // Untraceable: an active capability tied to no stated intent.
+  const untraceable = specs
+    .filter((s) => s.realizes === null && s.status === "active")
+    .map((s) => s.cap);
+
+  console.log(c.bold("Trace") + c.gray(" — product intent → capability provenance:"));
+  console.log("");
+
+  let realized = 0;
+  for (const a of anchors) {
+    const caps = realizedBy.get(a.id);
+    if (caps && caps.length > 0) {
+      realized += 1;
+      console.log(`  ${c.cyan(a.id.padEnd(6))} ${c.green("✓")} realized by: ${caps.sort().join(", ")}`);
+    } else {
+      console.log(`  ${c.cyan(a.id.padEnd(6))} ${c.red("✗")} dropped — no spec realizes this intent`);
+    }
+  }
+
+  if (dangling.length > 0 || untraceable.length > 0) console.log("");
+  for (const d of dangling) {
+    console.log(`  ${c.yellow("!")} dangling: spec "${d.cap}" realizes ${d.id} (no such anchor in product.md)`);
+  }
+  if (untraceable.length > 0) {
+    console.log(`  ${c.yellow("!")} untraceable specs (no Realizes:): ${untraceable.sort().join(", ")}`);
+  }
+
+  const dropped = anchors.length - realized;
+  console.log("");
+  const summary =
+    `${realized} of ${anchors.length} intent anchor${anchors.length === 1 ? "" : "s"} realized` +
+    `; ${dropped} dropped, ${dangling.length} dangling, ${untraceable.length} untraceable`;
+  const clean = dropped === 0 && dangling.length === 0 && untraceable.length === 0;
+  if (clean) {
+    console.log(c.green("ok") + " " + summary);
+    return 0;
+  }
+  console.log((strict ? c.red("fail") : c.yellow("gap")) + " " + summary);
+  // A report by default (exit 0); a gate under --strict (exit 1 for CI).
+  return strict ? 1 : 0;
+}
+
+// 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) {
+  const productPath = path.join(projectRoot, ".doctrina", "product.md");
+  if (!isFile(productPath)) return [];
+  const out = [];
+  const seen = new Set();
+  for (const line of read(productPath).split(/\r?\n/)) {
+    const m = line.match(/^\s*[-*]\s+\[([A-Z]+\d+)\]\s+/);
+    if (m && !seen.has(m[1])) {
+      seen.add(m[1]);
+      out.push({ id: m[1] });
+    }
+  }
+  return out;
+}
+
+function collectSpecs(projectRoot) {
+  const specsDir = path.join(projectRoot, ".doctrina", "specs");
+  if (!isDir(specsDir)) return [];
+  const out = [];
+  for (const cap of readdirSync(specsDir).sort()) {
+    const specPath = path.join(specsDir, cap, "spec.md");
+    if (!isFile(specPath)) continue;
+    const text = read(specPath);
+    const realizesRaw = specHeader(text, "Realizes");
+    const realizes = realizesRaw === null ? null : (realizesRaw.match(ANCHOR_RE) ?? []);
+    const status = (specHeader(text, "Status") ?? "active").trim().toLowerCase();
+    out.push({ cap, status, realizes });
+  }
+  return out;
+}
+
+export const help = `
+Usage: doctrina trace [--strict]
+
+Report intent provenance: how product.md intent maps to capability specs
+(ADR 0006). Tag product bullets with an anchor — \`- [SC1] ...\` — and add
+\`**Realizes:** SC1\` to the specs that deliver them.
+
+trace reports three provenance breaks:
+  dropped intent     an anchor that no spec realizes
+  dangling realizes  a spec cites an id absent from product.md
+  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).
+`;