doctrina-cli 0.3.0 → 0.4.0

package/README.md

@@ -3,7 +3,7 @@
 > CLI for the Doctrina framework. The package is published as
 > `doctrina-cli`; the executable it installs is `doctrina`.
 
-**Status:** v0.3.0 — current release. Zero runtime dependencies
+**Status:** v0.4.0 — current release. Zero runtime dependencies
 (Node.js standard library only).
 
 ## Install
@@ -20,14 +20,19 @@ Requires Node.js 20.12 or later.
 
 ```
 doctrina init                              scaffold AGENTS.md + .doctrina/ in cwd
+doctrina intake [<file>]                   store the full description + bootstrap playbook (clarification gate)
+doctrina work "<prompt>"                   brief prompt -> scaffolded change + work playbook (clarification gate)
 doctrina spec new <capability>             create a capability spec
 doctrina spec list                         list specs with version, status, size
 doctrina change new <id> "<title>"         open a change proposal
 doctrina change apply <id>                 apply spec deltas (ADDED/REMOVED auto)
 doctrina change archive <id>               archive an applied change
 doctrina change diff <id>                  preview spec deltas (line diff for MODIFIED)
+doctrina contract new <name>               own the integration surface (ports, env, interfaces)
+doctrina contract check                    verify port collisions, env drift, referenced specs
 doctrina decision new "<title>"            create the next sequential ADR
 doctrina decision accept <num>             flip a proposed ADR to accepted
+doctrina decision land <num> [path...]     stamp an accepted ADR as implemented (non-mutating Landed:)
 doctrina decision supersede <num> "<t>"    supersede an existing ADR
 doctrina decision list                     list ADRs with status, date, title
 doctrina skill new <name>                  scaffold an on-demand procedural-memory skill
@@ -36,8 +41,11 @@ doctrina skill sync                        mirror skill frontmatter descriptions
 doctrina analyze <change-id>               inspect a change folder before applying
 doctrina clarify <path>                    smell-test a Markdown file for ambiguity (--all: tree)
 doctrina context [<capability>]            print the context pack in read order (--concat)
-doctrina search <term> [...]               search artifacts, grouped by category
+doctrina search <term> [...]               search artifacts, grouped by category (ranked)
 doctrina validate                          schema + artifact-existence checks
+doctrina coverage                          acceptance criteria with linked evidence (--strict gates)
+doctrina trace                             intent provenance: product intent -> specs (--strict gates)
+doctrina verify                            run project typecheck/test/build checks (the real gate)
 doctrina templates list                    enumerate shipped templates
 doctrina templates check                   compare project against recommended template shape
 doctrina templates update                  additive fixer for check findings (preview; --write applies)
@@ -109,9 +117,19 @@ For each spec delta found under `.doctrina/changes/<id>/specs/`:
 16. Each skill's frontmatter description matches `index.json` (drift warn; `skill sync` fixes).
 17. EARS grammar shape per section in specs declaring `## Requirements (EARS)` (warn).
 18. Nested `AGENTS.md` files obey the root size caps (warn > 150, error > 200).
+19. No two ADR files share the same `NNNN` number (merge-collision error).
+20. `index.json` records a `framework_version` matching the running CLI
+    (stamp-divergence warn; `index rebuild` migrates it).
+21. Accepted ADRs anchor to reality via `Evidence:` and/or `Landed:`; cited
+    paths must exist on disk (drift warn).
 
 Exit code: 0 if no errors (warnings allowed), 1 otherwise.
 
+Two related read-only reports gate separately: `doctrina coverage`
+(each acceptance criterion cites a real test) and `doctrina trace`
+(each product intent has a capability, each capability traces to an
+intent). Both exit 1 under `--strict` for CI.
+
 ## Tests
 
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "doctrina-cli",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Doctrina CLI — spec-driven, AGENTS.md-native framework for multi-agent AI development.",
   "license": "MIT",
   "keywords": [

package/src/commands/change.js

@@ -144,6 +144,7 @@ function changeApply(args, _flags) {
   // Flip proposal status from "proposed" to "applied" when fully successful.
   // Zero-delta changes are trivially successful (no work to fail), so they
   // also flip — otherwise metadata-only changes are stuck at "proposed".
+  let flippedToApplied = false;
   if (errors === 0 && manual === 0) {
     const proposalPath = path.join(changeDir, "proposal.md");
     if (exists(proposalPath)) {
@@ -155,30 +156,41 @@ function changeApply(args, _flags) {
       if (updated !== txt) {
         write(proposalPath, updated, { force: true });
         console.log(c.green("status") + " proposal.md → applied");
+        flippedToApplied = true;
       }
     }
   }
 
-  // Update index for ADDED/REMOVED that affected specs
-  if (writes > 0) {
+  // Update the index when specs changed (ADDED/REMOVED) and/or the proposal
+  // flipped to applied. The change entry's status must mirror the proposal —
+  // the same value `index rebuild` derives from the file — or the index
+  // drifts from the tree in the apply→archive window (caught by
+  // `index rebuild --check`, e.g. in the pre-commit hook).
+  if (writes > 0 || flippedToApplied) {
     const index = idx.load(projectRoot);
-    for (const deltaPath of deltaFiles) {
-      const text = read(deltaPath);
-      const op = parseOperation(text);
-      const capability = parseCapabilityFromDelta(text, deltaPath);
-      if (!capability) continue;
-      if (op === "ADDED") {
-        idx.addSpec(index, {
-          id: capability,
-          path: `.doctrina/specs/${capability}/spec.md`,
-          status: "active",
-          version: "0.1.0",
-          last_updated: date,
-        });
-      } else if (op === "REMOVED") {
-        idx.removeSpec(index, capability);
+    if (writes > 0) {
+      for (const deltaPath of deltaFiles) {
+        const text = read(deltaPath);
+        const op = parseOperation(text);
+        const capability = parseCapabilityFromDelta(text, deltaPath);
+        if (!capability) continue;
+        if (op === "ADDED") {
+          idx.addSpec(index, {
+            id: capability,
+            path: `.doctrina/specs/${capability}/spec.md`,
+            status: "active",
+            version: "0.1.0",
+            last_updated: date,
+          });
+        } else if (op === "REMOVED") {
+          idx.removeSpec(index, capability);
+        }
       }
     }
+    if (flippedToApplied) {
+      const entry = index.artifacts.changes.find((ch) => ch.id === id);
+      if (entry) entry.status = "applied";
+    }
     idx.touch(index, date);
     idx.save(projectRoot, index);
   }

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.
@@ -158,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/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).
+`;

package/src/commands/validate.js

@@ -3,6 +3,8 @@ import process from "node:process";
 import { readdirSync } from "node:fs";
 import { exists, isDir, isFile, lineCount, read, relPath, walk } from "../lib/fs-ops.js";
 import * as idx from "../lib/index-json.js";
+import { SCHEMA_VERSION } from "../lib/index-json.js";
+import { cliVersion } from "../lib/version.js";
 import { c } from "../lib/colors.js";
 import { parseFrontmatter } from "./skill.js";
 import { checkEars, isEarsSpec } from "../lib/ears.js";
@@ -45,8 +47,20 @@ export async function run(_positional, _flags) {
   }
 
   if (index) {
-    if (index.$schema_version !== "0.1.0") {
-      warnings.push(`index.json $schema_version is "${index.$schema_version}" (expected "0.1.0")`);
+    if (index.$schema_version !== SCHEMA_VERSION) {
+      warnings.push(`index.json $schema_version is "${index.$schema_version}" (expected "${SCHEMA_VERSION}")`);
+    }
+    // framework_version stamp divergence (3.6). The index records which CLI
+    // manages it; a stamp behind (or absent vs.) the running CLI means the
+    // tree may predate the current schema. `index rebuild` migrates it.
+    const runningVersion = cliVersion();
+    if (!index.framework_version) {
+      warnings.push(`index.json has no framework_version (run \`doctrina index rebuild\` to stamp it)`);
+    } else if (index.framework_version !== runningVersion) {
+      warnings.push(
+        `index.json framework_version is "${index.framework_version}" but the running CLI is ` +
+          `${runningVersion} (run \`doctrina index rebuild\` to stamp/migrate)`,
+      );
     }
     if (!index.artifacts) {
       errors.push("index.json missing artifacts object");
@@ -79,10 +93,20 @@ export async function run(_positional, _flags) {
 
   // 5. ADRs have parseable Status: header
   const adrDir = path.join(projectRoot, ".doctrina", "decisions");
+  // Track which files claim each NNNN so a merge-time collision (two branches
+  // both allocating the same number) becomes a loud error rather than one ADR
+  // silently shadowing the other (C2).
+  const adrByNumber = new Map();
   if (isDir(adrDir)) {
     for (const f of walk(adrDir)) {
       if (!f.endsWith(".md")) continue;
       const base = path.basename(f);
+      const numMatch = base.match(/^(\d{4})-/);
+      const num = numMatch ? numMatch[1] : null;
+      if (num) {
+        if (!adrByNumber.has(num)) adrByNumber.set(num, []);
+        adrByNumber.get(num).push(relPath(projectRoot, f));
+      }
       // ADR filenames must be NNNN-slug.md (four digits). The entire ADR
       // toolchain — decision new/accept/supersede, index derivation, and
       // the orphan check below — keys off this shape; a file like
@@ -105,33 +129,50 @@ export async function run(_positional, _flags) {
       // 5b. ADR evidence drift. A decision is only true if reality reflects
       //     it; an accepted ADR that points at nothing — or at a file that
       //     no longer exists — is the classic "ADR decrees X, the code
-      //     never did X". Only ADRs that adopt the **Evidence:** header are
-      //     checked, so legacy/process ADRs that opt out stay quiet.
+      //     never did X". Two header fields anchor a decision to reality:
+      //     **Evidence:** (cited at any point) and **Landed:** (the
+      //     non-mutating "this is now implemented and verified here" stamp,
+      //     written by `doctrina decision land`; 3.4). Both are checked for
+      //     dangling citations; an accepted ADR is only flagged bare when
+      //     BOTH are empty. ADRs that adopt neither header opt out entirely.
       const evidence = listHeader(text, "Evidence");
-      if (evidence !== null) {
-        const adrStatus = (listHeader(text, "Status") ?? "").toLowerCase();
-        const trimmed = evidence.trim();
-        const bare = trimmed === "—" || trimmed === "-" || trimmed === "";
-        if (bare) {
-          if (adrStatus === "accepted") {
+      const landed = listHeader(text, "Landed");
+      const isBare = (v) => {
+        const t = (v ?? "").trim();
+        return t === "" || t === "—" || t === "-";
+      };
+      for (const [field, value] of [["Evidence", evidence], ["Landed", landed]]) {
+        if (value === null || isBare(value)) continue;
+        for (const token of extractBacktickPaths(value)) {
+          const candidates = [path.resolve(path.dirname(f), token), path.resolve(projectRoot, token)];
+          if (!candidates.some(exists)) {
             warnings.push(
-              `${relPath(projectRoot, f)}: accepted ADR cites no implementation evidence ` +
-                `(link the file(s) that prove it, or note "n/a — <why>"); a decision with ` +
-                `nothing behind it may be drift waiting to be superseded`,
+              `${relPath(projectRoot, f)}: ${field} cites \`${token}\` which is missing on disk — ` +
+                `the decision may have drifted from the code (update it or supersede the ADR)`,
             );
           }
-        } else {
-          for (const token of extractBacktickPaths(evidence)) {
-            const candidates = [path.resolve(path.dirname(f), token), path.resolve(projectRoot, token)];
-            if (!candidates.some(exists)) {
-              warnings.push(
-                `${relPath(projectRoot, f)}: Evidence cites \`${token}\` which is missing on disk — ` +
-                  `the decision may have drifted from the code (update the evidence or supersede the ADR)`,
-              );
-            }
-          }
         }
       }
+      const adrStatus = (listHeader(text, "Status") ?? "").toLowerCase();
+      if (adrStatus === "accepted" && evidence !== null && isBare(evidence) && isBare(landed)) {
+        warnings.push(
+          `${relPath(projectRoot, f)}: accepted ADR cites no implementation evidence ` +
+            `(link the file(s) that prove it, run \`doctrina decision land ${num ?? "NNNN"}\` once ` +
+            `it ships, or note "n/a — <why>"); a decision with nothing behind it may be drift ` +
+            `waiting to be superseded`,
+        );
+      }
+    }
+
+    // 5c. Duplicate ADR numbers (C2).
+    for (const [num, files] of adrByNumber) {
+      if (files.length > 1) {
+        errors.push(
+          `ADR number ${num} is claimed by ${files.length} files (${files.join(", ")}) — ` +
+            `two branches likely allocated it concurrently; renumber all but one ` +
+            `(the index keys decisions by number, so duplicates silently shadow each other)`,
+        );
+      }
     }
   }
 

package/src/commands/work.js

@@ -4,6 +4,7 @@ import { readdirSync } from "node:fs";
 import { exists, isDir, isFile, read, relPath, write } from "../lib/fs-ops.js";
 import { flagString } from "../lib/args.js";
 import { c } from "../lib/colors.js";
+import { assessBrief } from "../lib/clarity.js";
 import { changeNew } from "./change.js";
 
 // `work` is the second half of the no-ceremony path (ADR 0005): a brief
@@ -58,9 +59,10 @@ export async function run(positional, flags) {
 
   const matches = pinned ? [] : rankCapabilities(projectRoot, prompt);
   const capability = pinned ?? matches[0]?.id ?? null;
+  const clarity = assessBrief(prompt, { kind: "prompt" });
 
   console.log("");
-  printPlaybook(projectRoot, { id, prompt, pinned, matches, capability });
+  printPlaybook(projectRoot, { id, prompt, pinned, matches, capability, clarity });
   return 0;
 }
 
@@ -150,12 +152,21 @@ export function rankCapabilities(projectRoot, prompt) {
   return ranked.sort((a, b) => b.score - a.score || a.id.localeCompare(b.id)).slice(0, 3);
 }
 
-function printPlaybook(projectRoot, { id, prompt, pinned, matches, capability }) {
+function printPlaybook(projectRoot, { id, prompt, pinned, matches, capability, clarity }) {
   const capToken = capability ?? "<capability>";
   console.log(c.bold(`Work playbook — change ${id}`) + c.gray(" — agent-executed (ADR 0005)."));
   console.log("");
   console.log(`Prompt: "${prompt}"`);
 
+  // Clarification gate (review Topic A): a thin prompt is the moment to ask
+  // the user, not to invent a spec. Advisory — the change is still scaffolded
+  // (it is a draft), but the agent is told to resolve the gaps first.
+  if (clarity?.thin) {
+    console.log("");
+    console.log(c.yellow("⚠ thin prompt — clarify with the user before writing spec deltas:"));
+    for (const r of clarity.reasons) console.log(`    - ${r}`);
+  }
+
   if (pinned) {
     const hasSpec = isFile(path.join(projectRoot, ".doctrina", "specs", pinned, "spec.md"));
     console.log(`Capability (pinned): ${c.cyan(pinned)}` +
@@ -214,7 +225,8 @@ Turn a brief prompt into a scaffolded change plus the work playbook the
 host AI agent executes (see ADR 0005). The CLI derives a sequential
 change id (NNNN-<slug>) from the prompt, opens the change folder,
 records the prompt under the proposal's "## Why", ranks existing specs
-by term overlap as a capability hint, and prints the ordered steps:
+by term overlap as a capability hint, flags a thin/under-specified prompt
+so you clarify before writing deltas (advisory), and prints the steps:
 context → spec delta → tasks → implement → analyze → apply → verify
 (verify + coverage) → archive → validate. No natural-language
 interpretation happens in the CLI.

package/src/index.js

@@ -1,11 +1,9 @@
 #!/usr/bin/env node
 import process from "node:process";
-import path from "node:path";
-import { fileURLToPath } from "node:url";
-import { readFileSync } from "node:fs";
 import { parseArgs } from "./lib/args.js";
 import { c } from "./lib/colors.js";
 import { suggest } from "./lib/suggest.js";
+import { cliVersion } from "./lib/version.js";
 
 import * as init from "./commands/init.js";
 import * as spec from "./commands/spec.js";
@@ -27,11 +25,12 @@ import * as work from "./commands/work.js";
 import * as coverage from "./commands/coverage.js";
 import * as verify from "./commands/verify.js";
 import * as contract from "./commands/contract.js";
+import * as trace from "./commands/trace.js";
 
 const COMMANDS = {
   init, spec, change, decision, validate, hooks, analyze, clarify,
   templates, skill, index: indexCmd, next, metrics, context, search,
-  intake, work, coverage, verify, contract,
+  intake, work, coverage, verify, contract, trace,
 };
 
 const TOP_HELP = `
@@ -51,6 +50,7 @@ Commands:
   contract check       Verify port collisions, env drift, referenced specs
   decision new         Create the next sequentially numbered ADR
   decision accept      Flip a proposed ADR to accepted
+  decision land        Record that an accepted ADR is now implemented (non-mutating)
   decision supersede   Create a new ADR that supersedes an existing one
   decision list        List ADRs with status, date, and title
   skill new            Scaffold an on-demand procedural memory skill
@@ -62,6 +62,7 @@ Commands:
   search               Search the artifact tree, grouped by category
   validate             Run schema and structural checks
   coverage             Report acceptance criteria with linked evidence (--strict gates)
+  trace                Report intent provenance: product intent → specs (--strict gates)
   verify               Run project-declared typecheck/test/build checks (the real gate)
   templates list       List the templates shipped by the installed CLI
   templates check      Compare the project against the recommended template shape
@@ -81,7 +82,7 @@ async function main(argv) {
   });
 
   if (flags.get("version") || flags.get("v")) {
-    console.log(readVersion());
+    console.log(cliVersion());
     return 0;
   }
 
@@ -119,14 +120,4 @@ async function main(argv) {
   }
 }
 
-function readVersion() {
-  const here = path.dirname(fileURLToPath(import.meta.url));
-  const pkgPath = path.resolve(here, "..", "package.json");
-  try {
-    return JSON.parse(readFileSync(pkgPath, "utf8")).version ?? "0.0.0";
-  } catch {
-    return "0.0.0";
-  }
-}
-
 main(process.argv.slice(2)).then((code) => process.exit(code ?? 0));

package/src/lib/clarity.js

@@ -0,0 +1,49 @@
+// Deterministic under-specification detector for free-text briefs and
+// intakes — the clarification gate (review Topic A). It does NOT judge
+// meaning (that stays the agent's job, ADR 0005); it flags input that is
+// structurally too thin to spec from, so `intake` and `work` prompt the
+// agent to clarify with the user before speculating a spec or change out of
+// too little. Advisory only: it surfaces the gap, it does not block.
+
+const WEASEL = /\b(might|could|perhaps|maybe|probably|somehow|approximately|roughly|etc)\b/gi;
+const VAGUE = /\b(some|several|various|appropriate|robust|scalable|nice|good|better|fast|simple|stuff|things?)\b/gi;
+
+// Generic verbs/nouns that carry no capability information on their own. A
+// brief made only of these ("add the feature", "do the thing") names nothing
+// concrete to build.
+const FILLER = new Set([
+  "the", "and", "for", "with", "this", "that", "something", "anything",
+  "make", "add", "create", "build", "implement", "feature", "thing",
+  "things", "stuff", "task", "work", "please", "just", "some", "any",
+]);
+
+// Assess a brief/intake. `kind` tunes the thresholds: a one-line work prompt
+// is held to a lower bar than a full project intake.
+export function assessBrief(text, { kind = "prompt" } = {}) {
+  const clean = String(text ?? "").replace(/\s+/g, " ").trim();
+  const tokens = clean ? clean.split(" ") : [];
+  const words = tokens.length;
+  const vague = (clean.match(VAGUE) ?? []).length + (clean.match(WEASEL) ?? []).length;
+  const meaningful = tokens
+    .map((t) => t.toLowerCase().replace(/[^a-z0-9]/g, ""))
+    .filter((t) => t.length >= 3 && !FILLER.has(t));
+
+  const minWords = kind === "intake" ? 20 : 3;
+  const maxVague = kind === "intake" ? 4 : 2;
+
+  const reasons = [];
+  if (words < minWords) {
+    reasons.push(
+      `only ${words} word${words === 1 ? "" : "s"} — say what the behaviour is, ` +
+        `what the inputs are, and how you'll know it's done`,
+    );
+  }
+  if (words > 0 && meaningful.length === 0) {
+    reasons.push("no concrete terms once filler words are removed — name the actual capability or behaviour");
+  }
+  if (vague >= maxVague) {
+    reasons.push(`${vague} vague/weasel term${vague === 1 ? "" : "s"} — replace with definite, checkable wording`);
+  }
+
+  return { thin: reasons.length > 0, words, reasons };
+}

package/src/lib/index-json.js

@@ -1,7 +1,8 @@
 import path from "node:path";
 import { read, write, exists } from "./fs-ops.js";
+import { cliVersion } from "./version.js";
 
-const SCHEMA_VERSION = "0.1.0";
+export const SCHEMA_VERSION = "0.1.0";
 
 export function indexPath(projectRoot) {
   return path.join(projectRoot, ".doctrina", "index.json");
@@ -21,6 +22,11 @@ export function load(projectRoot) {
 }
 
 export function save(projectRoot, index) {
+  // Stamp the managing framework version on every write (3.6): the index
+  // records which CLI last wrote it, so a stale stamp (an index written by an
+  // older CLI) is detectable by `doctrina validate` and migrated by
+  // `doctrina index rebuild`.
+  index.framework_version = cliVersion();
   const p = indexPath(projectRoot);
   const text = JSON.stringify(index, null, 2) + "\n";
   write(p, text, { force: true });
@@ -30,7 +36,7 @@ export function blank(projectName, date) {
   return {
     $schema_version: SCHEMA_VERSION,
     project: projectName,
-    framework_version: "0.0.0",
+    framework_version: cliVersion(),
     last_updated: date,
     artifacts: {
       product: {

package/src/lib/scan.js

@@ -81,6 +81,12 @@ export function deriveIndex(projectRoot, current) {
     const implRaw = specHeader(text, "Implementation");
     const impl = implRaw ? implRaw.trim() : prev?.implementation;
     if (impl) entry.implementation = impl;
+    // Realizes: the product intent anchors this capability delivers (ADR
+    // 0006). Stored as an id list so the provenance link is queryable, not
+    // just prose. Header wins over the previous index, like Implementation.
+    const realizesRaw = specHeader(text, "Realizes");
+    const realizes = realizesRaw ? (realizesRaw.match(/[A-Z]+\d+/g) ?? []) : prev?.realizes;
+    if (realizes && realizes.length) entry.realizes = realizes;
     out.artifacts.specs.push(entry);
   }
 
@@ -104,6 +110,8 @@ export function deriveIndex(projectRoot, current) {
     if (supersedes && supersedes !== "—") entry.supersedes = supersedes;
     const supersededBy = listHeader(text, "Superseded by");
     if (supersededBy && supersededBy !== "—") entry.superseded_by = supersededBy;
+    const landed = listHeader(text, "Landed");
+    if (landed && landed !== "—") entry.landed = landed;
     out.artifacts.decisions.push(entry);
   }
 

package/src/lib/version.js

@@ -0,0 +1,21 @@
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { readFileSync } from "node:fs";
+
+// Single source for "which CLI version is running." Read from the package
+// manifest so it tracks the published version with no extra wiring. Used to
+// stamp index.json (so an artifact tree records the framework that manages
+// it — `doctrina validate` warns and `index rebuild` migrates when the stamp
+// falls behind the running CLI) and to print `doctrina --version`.
+
+const here = path.dirname(fileURLToPath(import.meta.url));
+
+export function cliVersion() {
+  // src/lib/version.js -> packages/doctrina-cli/package.json
+  const pkgPath = path.resolve(here, "..", "..", "package.json");
+  try {
+    return JSON.parse(readFileSync(pkgPath, "utf8")).version ?? "0.0.0";
+  } catch {
+    return "0.0.0";
+  }
+}

package/templates/decision.md.template

@@ -6,6 +6,7 @@
 - **Supersedes:** —
 - **Superseded by:** —
 - **Evidence:** —
+- **Landed:** —
 
 <!--
 Evidence anchors the decision to reality. Once accepted, cite the file(s)
@@ -14,6 +15,13 @@ that prove this decision is actually implemented, in backticks, e.g.
 `doctrina validate` warns when cited evidence is missing on disk (the
 decision drifted from the code) or when an accepted ADR cites none. For a
 process decision with no code artifact, write "n/a — <why>".
+
+Landed is the non-mutating "this decision is now implemented and verified
+here" stamp. Many ADRs are accepted at design time with "Evidence: n/a — no
+implementation yet"; once the capability ships, run
+"doctrina decision land NNNN `path/to/proof.ts` ..." to record the date and
+proof without editing the immutable body. A filled Landed satisfies the
+accepted-ADR evidence check.
 -->
 
 ## Context

package/templates/doctrina/index.json.template

@@ -1,7 +1,7 @@
 {
   "$schema_version": "0.1.0",
   "project": "{{PROJECT_NAME}}",
-  "framework_version": "0.0.0",
+  "framework_version": "{{FRAMEWORK_VERSION}}",
   "last_updated": "{{DATE}}",
   "artifacts": {
     "product": {

package/templates/doctrina/product.md.template

@@ -28,7 +28,12 @@ Out of scope (deferred or rejected):
 
 ## Success criteria
 
-<!-- How you will know this project is working. Prefer measurable signals. -->
+<!--
+How you will know this project is working. Prefer measurable signals.
+Tag a bullet with a short stable id — "- [SC1] ..." — to make it an intent
+anchor that capability specs cite via "**Realizes:** SC1" (`doctrina trace`;
+ADR 0006). Untagged bullets are fine; anchors are opt-in.
+-->
 
 ## Delivery order (walking skeleton)
 

package/templates/spec.md.template

@@ -17,6 +17,10 @@ An "active" spec left at "planned" is an inventory claim with nothing
 behind it, and `doctrina validate` warns. To record a deliberate gap and
 silence the warning, add a note after the value, e.g.
 "**Implementation:** planned — backend deferred to Q3, see ADR 0007".
+
+Optional: trace this capability to product intent by adding a header
+"**Realizes:** SC1, SC3" that names the product.md anchors it delivers
+(`doctrina trace`; ADR 0006).
 -->
 
 ## Purpose