doctrina-cli 0.2.2 → 0.3.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.1.0 — first working release. Zero runtime dependencies
+**Status:** v0.3.0 — current release. Zero runtime dependencies
 (Node.js standard library only).
 
 ## Install

package/package.json

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

package/src/commands/change.js

@@ -193,7 +193,7 @@ function changeApply(args, _flags) {
   return errors > 0 ? 1 : 0;
 }
 
-function changeArchive(args, _flags) {
+function changeArchive(args, flags) {
   const id = args[0];
   if (!id) {
     console.error(c.red("error:") + " change archive requires <id>");
@@ -208,6 +208,28 @@ function changeArchive(args, _flags) {
     return 1;
   }
 
+  // Verification gate. "Done" is a claim until it is checked. Archiving is
+  // the act of declaring a change finished, so it must refuse while any
+  // task (including closing steps) or any declared verification item is
+  // still unchecked. This is the difference between "boxes marked" and
+  // "verification passed" the framework was faulted for collapsing.
+  // --force is the escape hatch: it archives anyway and records the gap.
+  const force = flagBool(flags, "force", false);
+  const blockers = collectArchiveBlockers(changeDir);
+  if (blockers.length > 0) {
+    if (!force) {
+      console.error(c.red("error:") + ` refusing to archive "${id}" — verification incomplete:`);
+      for (const b of blockers) console.error(`  - ${b}`);
+      console.error(
+        c.gray("hint: ") +
+          "finish and check the items, or pass --force to archive anyway (records the gap)",
+      );
+      return 1;
+    }
+    console.log(c.yellow("warn:") + ` archiving "${id}" with verification incomplete (--force):`);
+    for (const b of blockers) console.log(c.yellow("  - ") + b);
+  }
+
   const date = today();
   const archiveName = `${date}-${id}`;
   const archiveDir = path.join(projectRoot, ".doctrina", "changes", "archive", archiveName);
@@ -364,6 +386,45 @@ function extractDeltaBody(text) {
   return text.slice(idxSep + 5).replace(/^\n+/, "");
 }
 
+// Reasons a change is not finished enough to archive. Counts unchecked
+// GitHub-style checkboxes (`- [ ]`) in tasks.md (every task, including the
+// closing steps) and in the proposal's "## Verification" section. Returns
+// a list of human-readable blocker strings; empty means clear to archive.
+function collectArchiveBlockers(changeDir) {
+  const blockers = [];
+  const countUnchecked = (s) => (s.match(/^\s*-\s*\[ \]/gm) ?? []).length;
+
+  const tasksPath = path.join(changeDir, "tasks.md");
+  if (exists(tasksPath)) {
+    const n = countUnchecked(read(tasksPath));
+    if (n > 0) blockers.push(`${n} unchecked task${n === 1 ? "" : "s"} in tasks.md (closing steps count)`);
+  }
+
+  const proposalPath = path.join(changeDir, "proposal.md");
+  if (exists(proposalPath)) {
+    const n = countUnchecked(extractSection(read(proposalPath), "Verification"));
+    if (n > 0) blockers.push(`${n} unmet verification item${n === 1 ? "" : "s"} in proposal.md (## Verification)`);
+  }
+  return blockers;
+}
+
+// Return the body of a "## <name>" section (lines after the heading up to
+// the next "## " heading). Empty string when the section is absent.
+function extractSection(text, name) {
+  const lines = text.split(/\r?\n/);
+  const head = new RegExp(`^##\\s+${name}\\b`, "i");
+  let inSection = false;
+  const out = [];
+  for (const line of lines) {
+    if (/^##\s+/.test(line)) {
+      inSection = head.test(line);
+      continue;
+    }
+    if (inSection) out.push(line);
+  }
+  return out.join("\n");
+}
+
 function ensureDoctrinaProject(projectRoot) {
   if (!exists(path.join(projectRoot, ".doctrina"))) {
     throw new Error("not a Doctrina project (no .doctrina/ in cwd). Run `doctrina init` first.");

package/src/commands/contract.js

@@ -0,0 +1,254 @@
+import path from "node:path";
+import process from "node:process";
+import { readdirSync } from "node:fs";
+import { exists, isDir, isFile, read, relPath, write } from "../lib/fs-ops.js";
+import { locateTemplatesDir, substitute } from "../lib/templates.js";
+import { specHeader } from "../lib/scan.js";
+import * as idx from "../lib/index-json.js";
+import { today } from "../lib/dates.js";
+import { flagBool } from "../lib/args.js";
+import { c } from "../lib/colors.js";
+import { suggest } from "../lib/suggest.js";
+
+// Contracts are the first-class home for the integration/runtime surface
+// no single capability owns: the port map, the env/dependency contract,
+// and the API/WS/event interface shapes. The criticism this answers: each
+// capability was built against its own spec in isolation, and the seams
+// between them fell in the gap with nobody accountable. `contract check`
+// turns the parts that are mechanically verifiable (port collisions, env
+// drift vs .env.example, referenced specs that must exist) into a gate.
+
+const SUBCOMMANDS = ["new", "list", "check"];
+
+export async function run(positional, flags) {
+  const sub = positional[0];
+  switch (sub) {
+    case "new":
+      return contractNew(positional.slice(1), flags);
+    case "list":
+      return contractList();
+    case "check":
+      return contractCheck(positional.slice(1), flags);
+    default:
+      console.error(c.red("error:") + ` unknown contract subcommand "${sub ?? ""}"`);
+      const guess = suggest(sub, SUBCOMMANDS);
+      console.error(c.gray("hint: ") + (guess
+        ? `did you mean \`doctrina contract ${guess}\`?`
+        : `available: ${SUBCOMMANDS.join(", ")}`));
+      return 2;
+  }
+}
+
+function contractNew(args, flags) {
+  const name = args[0];
+  if (!name || !/^[a-z][a-z0-9-]*$/.test(name)) {
+    console.error(c.red("error:") + " contract name must be lowercase letters, digits, or hyphens (e.g. \"system\", \"api\").");
+    return 2;
+  }
+  const force = flagBool(flags, "force", false);
+  const projectRoot = process.cwd();
+  ensureDoctrinaProject(projectRoot);
+
+  const targetPath = path.join(projectRoot, ".doctrina", "contracts", `${name}.md`);
+  if (exists(targetPath) && !force) {
+    console.error(c.red("error:") + ` ${relPath(projectRoot, targetPath)} already exists (pass --force to overwrite)`);
+    return 1;
+  }
+
+  const templatesDir = locateTemplatesDir();
+  const date = today();
+  const body = substitute(read(path.join(templatesDir, "contract.md.template")), { CONTRACT_NAME: name, DATE: date });
+  write(targetPath, body, { force });
+  console.log(c.green("created") + ` ${relPath(projectRoot, targetPath)}`);
+
+  const index = idx.load(projectRoot);
+  idx.addContract(index, {
+    id: name,
+    path: `.doctrina/contracts/${name}.md`,
+    status: "active",
+    last_updated: date,
+  });
+  idx.touch(index, date);
+  idx.save(projectRoot, index);
+  console.log(c.green("indexed") + ` contract "${name}"`);
+  console.log("");
+  console.log("Fill in the Ports / Environment / Interfaces tables, then run " + c.cyan("doctrina contract check") + ".");
+  return 0;
+}
+
+function contractList() {
+  const projectRoot = process.cwd();
+  ensureDoctrinaProject(projectRoot);
+  const dir = path.join(projectRoot, ".doctrina", "contracts");
+  const rows = [];
+  if (isDir(dir)) {
+    for (const f of readdirSync(dir).sort()) {
+      if (!f.endsWith(".md")) continue;
+      const text = read(path.join(dir, f));
+      rows.push({ id: f.replace(/\.md$/, ""), status: specHeader(text, "Status") ?? "active", updated: specHeader(text, "Last updated") ?? "—" });
+    }
+  }
+  if (rows.length === 0) {
+    console.log(c.gray("no contracts found in .doctrina/contracts/ (create one with `doctrina contract new <name>`)"));
+    return 0;
+  }
+  console.log(c.bold("Contracts:"));
+  console.log("");
+  for (const r of rows) console.log(`  ${c.cyan(r.id.padEnd(20))} ${r.status.padEnd(10)} ${r.updated}`);
+  console.log("");
+  console.log(c.gray(`${rows.length} contract${rows.length === 1 ? "" : "s"}`));
+  return 0;
+}
+
+function contractCheck(args, _flags) {
+  const projectRoot = process.cwd();
+  ensureDoctrinaProject(projectRoot);
+  const dir = path.join(projectRoot, ".doctrina", "contracts");
+
+  let names;
+  if (args[0]) {
+    names = [args[0].replace(/\.md$/, "")];
+  } else if (isDir(dir)) {
+    names = readdirSync(dir).filter((f) => f.endsWith(".md")).map((f) => f.replace(/\.md$/, "")).sort();
+  } else {
+    names = [];
+  }
+  if (names.length === 0) {
+    console.log(c.gray("no contracts to check in .doctrina/contracts/"));
+    return 0;
+  }
+
+  // The env contract is checked against .env.example when one exists.
+  const envExamplePath = path.join(projectRoot, ".env.example");
+  const envExample = isFile(envExamplePath) ? read(envExamplePath) : null;
+
+  let errors = 0;
+  let warnings = 0;
+  for (const name of names) {
+    const file = path.join(dir, `${name}.md`);
+    if (!isFile(file)) {
+      console.log(c.red("error: ") + `contract "${name}" not found at ${relPath(projectRoot, file)}`);
+      errors += 1;
+      continue;
+    }
+    const text = read(file);
+    console.log(c.bold(name) + c.gray(` (${relPath(projectRoot, file)})`));
+
+    // 1. Port collisions — two services must not claim the same port.
+    const ports = parseTable(sectionOf(text, "Ports"));
+    if (ports) {
+      const portCol = colIndex(ports.headers, "port");
+      const svcCol = colIndex(ports.headers, "service");
+      const seen = new Map();
+      for (const row of ports.rows) {
+        const port = (row[portCol] ?? "").trim();
+        if (!/^\d+$/.test(port)) continue;
+        const svc = (row[svcCol] ?? "?").trim();
+        if (seen.has(port)) {
+          console.log(c.red("  ✗ ") + `port ${port} is claimed by both "${seen.get(port)}" and "${svc}"`);
+          errors += 1;
+        } else {
+          seen.set(port, svc);
+        }
+      }
+    }
+
+    // 2. Environment drift — every declared variable must exist in
+    //    .env.example (when present), so code, example, and infra agree.
+    const env = parseTable(sectionOf(text, "Environment"));
+    if (env && envExample !== null) {
+      const varCol = colIndex(env.headers, "variable");
+      for (const row of env.rows) {
+        const name2 = (row[varCol] ?? "").trim();
+        if (!/^[A-Z][A-Z0-9_]*$/.test(name2)) continue;
+        const declared = new RegExp(`^\\s*(export\\s+)?${name2}\\s*=`, "m").test(envExample);
+        if (!declared) {
+          console.log(c.yellow("  ! ") + `env var ${name2} is in the contract but absent from .env.example`);
+          warnings += 1;
+        }
+      }
+    }
+
+    // 3. Referenced capability specs must exist.
+    for (const refCap of referencedCapabilities(sectionOf(text, "References"))) {
+      const specPath = path.join(projectRoot, ".doctrina", "specs", refCap, "spec.md");
+      if (!isFile(specPath)) {
+        console.log(c.red("  ✗ ") + `references spec "${refCap}" but ${relPath(projectRoot, specPath)} does not exist`);
+        errors += 1;
+      }
+    }
+  }
+
+  console.log("");
+  if (errors === 0 && warnings === 0) {
+    console.log(c.green("ok") + ` ${names.length} contract${names.length === 1 ? "" : "s"} consistent`);
+    return 0;
+  }
+  const summary = `${errors} error${errors === 1 ? "" : "s"}, ${warnings} warning${warnings === 1 ? "" : "s"}`;
+  console.log((errors === 0 ? c.green("ok") : c.red("fail")) + " " + summary);
+  return errors === 0 ? 0 : 1;
+}
+
+// Return the body of a "## <name>" section, up to the next "## " heading.
+function sectionOf(text, name) {
+  const lines = text.split(/\r?\n/);
+  const head = new RegExp(`^##\\s+${name}\\b`, "i");
+  let inSection = false;
+  const out = [];
+  for (const line of lines) {
+    if (/^##\s+/.test(line)) {
+      inSection = head.test(line);
+      continue;
+    }
+    if (inSection) out.push(line);
+  }
+  return out.join("\n");
+}
+
+// Parse a GitHub-flavoured Markdown table into { headers, rows }.
+function parseTable(text) {
+  const lines = text.split(/\r?\n/).filter((l) => /^\s*\|/.test(l));
+  if (lines.length < 2) return null;
+  const cells = (line) => line.trim().replace(/^\||\|$/g, "").split("|").map((cl) => cl.trim());
+  const headers = cells(lines[0]);
+  const rows = [];
+  for (let i = 1; i < lines.length; i++) {
+    const row = cells(lines[i]);
+    if (row.every((cl) => /^:?-+:?$/.test(cl) || cl === "")) continue; // separator row
+    rows.push(row);
+  }
+  return { headers, rows };
+}
+
+function colIndex(headers, name) {
+  const i = headers.findIndex((h) => h.toLowerCase() === name.toLowerCase());
+  return i < 0 ? 0 : i;
+}
+
+// Capability names referenced as `specs/<cap>` (placeholder <...> ignored).
+function referencedCapabilities(text) {
+  const out = new Set();
+  for (const m of text.matchAll(/specs\/([a-z][a-z0-9-]*)/g)) out.add(m[1]);
+  return [...out];
+}
+
+function ensureDoctrinaProject(projectRoot) {
+  if (!exists(path.join(projectRoot, ".doctrina"))) {
+    throw new Error("not a Doctrina project (no .doctrina/ in cwd). Run `doctrina init` first.");
+  }
+}
+
+export const help = `
+Usage: doctrina contract <subcommand> [args]
+
+Own the integration/runtime surface no single capability spec owns:
+the port map, the environment contract, and API/WS/event interfaces.
+
+Subcommands:
+  new <name>          Scaffold .doctrina/contracts/<name>.md and index it
+  list                One line per contract: id, status, last updated
+  check [<name>]      Verify the mechanically checkable parts: no two
+                      services share a port, every declared env var exists
+                      in .env.example, and every referenced spec exists.
+                      Exits 1 on errors (port collisions, missing specs).
+`;

package/src/commands/coverage.js

@@ -0,0 +1,179 @@
+import path from "node:path";
+import process from "node:process";
+import { readdirSync } from "node:fs";
+import { exists, isDir, isFile, read, relPath } from "../lib/fs-ops.js";
+import { flagBool } from "../lib/args.js";
+import { c } from "../lib/colors.js";
+
+// Traceability report: how many acceptance criteria cite an artifact or
+// test that actually exists on disk. Doctrina otherwise has no link
+// between what a spec promises and what proves it — this command makes
+// that link a first-class, measurable signal (the gap the framework was
+// criticised for: validating form, never truth).
+//
+// Convention: each numbered acceptance criterion may cite its evidence as
+// a backtick path span, e.g.
+//   1. Returns HTTP 429 above the quota — verified by `test/quota.test.ts`.
+// A criterion is "covered" when at least one cited path resolves to a
+// file. A cited path that does not resolve is "dangling" (broken
+// traceability) and reported separately. Criteria with no cited path are
+// "bare" — the spec promises something nothing is shown to satisfy.
+
+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 specsDir = path.join(projectRoot, ".doctrina", "specs");
+  const reports = [];
+  if (isDir(specsDir)) {
+    for (const cap of readdirSync(specsDir).sort()) {
+      const specPath = path.join(specsDir, cap, "spec.md");
+      if (!isFile(specPath)) continue;
+      const criteria = extractAcceptanceCriteria(read(specPath));
+      if (criteria.length === 0) continue;
+      const rows = criteria.map((crit, i) => classify(crit, i + 1, projectRoot, path.dirname(specPath)));
+      reports.push({ cap, specPath, rows });
+    }
+  }
+
+  if (reports.length === 0) {
+    console.log(c.gray("no acceptance criteria found under .doctrina/specs/"));
+    return 0;
+  }
+
+  let totalCriteria = 0;
+  let totalCovered = 0;
+  let totalDangling = 0;
+
+  console.log(c.bold("Coverage") + c.gray(" — acceptance criteria with linked evidence:"));
+  console.log("");
+
+  for (const rep of reports) {
+    const covered = rep.rows.filter((r) => r.kind === "covered").length;
+    const dangling = rep.rows.filter((r) => r.kind === "dangling").length;
+    totalCriteria += rep.rows.length;
+    totalCovered += covered;
+    totalDangling += dangling;
+
+    const danglingNote = dangling > 0 ? c.yellow(`  (${dangling} dangling)`) : "";
+    console.log(`  ${c.cyan(rep.cap.padEnd(20))} ${covered}/${rep.rows.length} criteria${danglingNote}`);
+    for (const r of rep.rows) {
+      if (r.kind === "covered") continue;
+      if (r.kind === "bare") {
+        console.log(`    ${c.red("✗")} #${r.n}  no evidence linked — cite the file/test that proves it in backticks`);
+      } else {
+        console.log(`    ${c.yellow("!")} #${r.n}  evidence not found on disk: ${r.missing.map((m) => `\`${m}\``).join(", ")}`);
+      }
+    }
+  }
+
+  const pct = totalCriteria === 0 ? 100 : Math.round((totalCovered / totalCriteria) * 100);
+  console.log("");
+  const summary = `${totalCovered} of ${totalCriteria} acceptance criteria across ${reports.length} spec${reports.length === 1 ? "" : "s"} have linked evidence (${pct}%)`;
+  const clean = totalCovered === totalCriteria && totalDangling === 0;
+  if (clean) {
+    console.log(c.green("ok") + " " + summary);
+    return 0;
+  }
+  const danglingSummary = totalDangling > 0 ? `, ${totalDangling} dangling` : "";
+  console.log((strict ? c.red("fail") : c.yellow("gap")) + " " + summary + danglingSummary);
+  // A report by default (exit 0); a gate under --strict (exit 1 for CI).
+  return strict ? 1 : 0;
+}
+
+// Pull the numbered items out of the "## Acceptance criteria" section.
+// Each item may span multiple lines (continuation prose); accumulate until
+// the next number or the next "## " heading. Returns an array of strings.
+function extractAcceptanceCriteria(text) {
+  const lines = text.split(/\r?\n/);
+  const out = [];
+  let inSection = false;
+  let buf = null;
+  const flush = () => {
+    if (buf !== null) out.push(buf.trim());
+    buf = null;
+  };
+  for (const line of lines) {
+    if (/^##\s+/.test(line)) {
+      // Entering or leaving a section.
+      if (inSection) {
+        flush();
+        inSection = false;
+      }
+      if (/^##\s+Acceptance criteria\b/i.test(line)) inSection = true;
+      continue;
+    }
+    if (!inSection) continue;
+    if (/^\s*\d+\.\s+/.test(line)) {
+      flush();
+      buf = line.replace(/^\s*\d+\.\s+/, "");
+    } else if (buf !== null) {
+      // Continuation line of the current criterion.
+      if (line.trim() === "") buf += " ";
+      else buf += " " + line.trim();
+    }
+  }
+  flush();
+  // Drop empty placeholder items (a lone "1." with no text).
+  return out.filter((s) => s.length > 0);
+}
+
+// Decide whether a single criterion is covered, dangling, or bare.
+function classify(criterion, n, projectRoot, specDir) {
+  const cited = extractBacktickPaths(criterion);
+  if (cited.length === 0) return { kind: "bare", n };
+  const missing = [];
+  let resolved = 0;
+  for (const token of cited) {
+    const candidates = [
+      path.resolve(projectRoot, token),
+      path.resolve(specDir, token),
+    ];
+    if (candidates.some(exists)) resolved += 1;
+    else missing.push(token);
+  }
+  if (resolved > 0) return { kind: "covered", n };
+  return { kind: "dangling", n, missing };
+}
+
+// Backtick spans that look like repository file paths. Mirrors the
+// validate stale-link heuristic: a token is a path if it has a slash or a
+// file extension and is not a URL/placeholder.
+function extractBacktickPaths(text) {
+  const out = new Set();
+  for (const m of text.matchAll(/`([^`]+)`/g)) {
+    const token = m[1].trim();
+    if (looksLikePath(token)) out.add(token);
+  }
+  return [...out];
+}
+
+function looksLikePath(s) {
+  if (!s) return false;
+  if (/^(https?:|mailto:|ftp:|#|@)/i.test(s)) return false;
+  if (/[\s<>*?{}]/.test(s)) return false;
+  const hasSlash = s.includes("/");
+  const hasExt = /\.[a-z0-9]{1,8}$/i.test(s);
+  if (!hasSlash && !hasExt) return false;
+  if (s.startsWith("-")) return false;
+  return true;
+}
+
+export const help = `
+Usage: doctrina coverage [--strict]
+
+Report how many acceptance criteria across .doctrina/specs/ cite an
+artifact or test that exists on disk. Each numbered criterion may cite
+its evidence as a backtick path span, e.g. \`test/quota.test.ts\`.
+
+A criterion is covered when at least one cited path resolves to a file,
+dangling when a cited path is missing on disk, and bare when nothing is
+cited. Read-only.
+
+Flags:
+  --strict   Exit 1 when any criterion is bare or dangling (CI gate).
+             Without it the command always exits 0 (a report).
+`;

package/src/commands/intake.js

@@ -110,7 +110,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 +121,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. Record any architectural decision the intake forces:");
+  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("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("");

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

@@ -6,6 +6,7 @@ import * as idx from "../lib/index-json.js";
 import { c } from "../lib/colors.js";
 import { parseFrontmatter } from "./skill.js";
 import { checkEars, isEarsSpec } from "../lib/ears.js";
+import { specHeader, listHeader } from "../lib/scan.js";
 
 export async function run(_positional, _flags) {
   const projectRoot = process.cwd();
@@ -57,6 +58,7 @@ export async function run(_positional, _flags) {
       for (const d of index.artifacts.decisions ?? []) allArtifactPaths.push(d.path);
       for (const ch of index.artifacts.changes ?? []) allArtifactPaths.push(ch.path);
       for (const ch of index.artifacts.changes_archive ?? []) allArtifactPaths.push(ch.path);
+      for (const ct of index.artifacts.contracts ?? []) allArtifactPaths.push(ct.path);
       for (const rel of allArtifactPaths) {
         const full = path.join(projectRoot, rel);
         if (!exists(full)) errors.push(`index.json references missing artifact: ${rel}`);
@@ -99,6 +101,37 @@ export async function run(_positional, _flags) {
             `(expected a Markdown list item exactly like "- **Status:** accepted")`,
         );
       }
+
+      // 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.
+      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") {
+            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`,
+            );
+          }
+        } 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)`,
+              );
+            }
+          }
+        }
+      }
     }
   }
 
@@ -145,6 +178,30 @@ export async function run(_positional, _flags) {
             warnings.push(`${relPath(projectRoot, specPath)}:${f.line} ${f.message}`);
           }
         }
+
+        // 8c. Capability-state honesty (two-axis status). An "active"
+        //     document that records no built capability is an inventory
+        //     claim — the gap the framework is meant to make visible.
+        //     Warn when Status is active and Implementation is "planned"
+        //     with no explanatory note after the state word. A note
+        //     ("planned — deferred, see ADR 0007") is the deliberate-gap
+        //     escape hatch. Specs with no Implementation header are off
+        //     the axis and never warn.
+        const implRaw = specHeader(text, "Implementation");
+        if (implRaw) {
+          const docStatus = (specHeader(text, "Status") ?? "active").toLowerCase();
+          const implTokens = implRaw.trim().split(/\s+/);
+          const implWord = (implTokens[0] ?? "").replace(/[—-]+$/, "").toLowerCase();
+          const hasNote = implTokens.length > 1;
+          if (docStatus === "active" && implWord === "planned" && !hasNote) {
+            warnings.push(
+              `${relPath(projectRoot, specPath)}: Status is "active" but Implementation is ` +
+                `"planned" with no note — an active spec with no built capability is an ` +
+                `inventory claim (advance Implementation, set Status: draft, or add a note ` +
+                `after the value: "planned — <why deferred>")`,
+            );
+          }
+        }
       }
     }
   }
@@ -202,6 +259,44 @@ export async function run(_positional, _flags) {
         }
       }
     }
+    const indexedContractIds = new Set((index.artifacts.contracts ?? []).map((ct) => ct.id));
+    const contractsDir = path.join(projectRoot, ".doctrina", "contracts");
+    if (isDir(contractsDir)) {
+      for (const f of walk(contractsDir)) {
+        if (!f.endsWith(".md")) continue;
+        const id = path.basename(f, ".md");
+        if (!indexedContractIds.has(id)) {
+          warnings.push(`orphan contract ${relPath(projectRoot, f)} (id "${id}" not in index.json)`);
+        }
+      }
+    }
+  }
+
+  // 11. Archive ledger ↔ index cross-check. The history of archived
+  //     changes is recorded twice — once human-facing in
+  //     changes/archive/LEDGER.md, once machine-facing in
+  //     index.json.changes_archive. Two sources of truth that silently
+  //     disagree are worse than one: an incomplete ledger makes the
+  //     history look shorter than it is. When the ledger exists, every
+  //     archived change must appear in both, or validation fails.
+  const ledgerPath = path.join(changesDir, "archive", "LEDGER.md");
+  if (index?.artifacts && isFile(ledgerPath)) {
+    const ledgerIds = new Set();
+    for (const line of read(ledgerPath).split(/\r?\n/)) {
+      const m = line.match(/^-\s+\d{4}-\d{2}-\d{2}\s+[—-]\s+(\S+)\s+[—-]\s+/);
+      if (m) ledgerIds.add(m[1]);
+    }
+    const archiveIds = new Set((index.artifacts.changes_archive ?? []).map((ch) => ch.id));
+    for (const id of archiveIds) {
+      if (!ledgerIds.has(id)) {
+        errors.push(`archived change "${id}" is in index.json but missing from changes/archive/LEDGER.md (ledger and index disagree)`);
+      }
+    }
+    for (const id of ledgerIds) {
+      if (!archiveIds.has(id)) {
+        errors.push(`changes/archive/LEDGER.md lists "${id}" but index.json.changes_archive does not (ledger and index disagree)`);
+      }
+    }
   }
 
   // 12-14. Skills validation
@@ -290,6 +385,17 @@ function extractPathReferences(text) {
   return [...out];
 }
 
+// Path-like tokens inside backtick spans — the convention for citing
+// evidence (ADR **Evidence:**, acceptance-criteria links).
+function extractBacktickPaths(text) {
+  const out = new Set();
+  for (const m of text.matchAll(/`([^`]+)`/g)) {
+    const token = m[1].trim();
+    if (isLikelyPath(token)) out.add(stripFragment(token));
+  }
+  return [...out];
+}
+
 function stripFragment(s) {
   // Remove an in-page anchor (#section) or query string from a path token.
   return s.split(/[#?]/)[0];

package/src/commands/verify.js

@@ -0,0 +1,153 @@
+import path from "node:path";
+import process from "node:process";
+import { spawnSync } from "node:child_process";
+import { exists, isFile, read, write, relPath } from "../lib/fs-ops.js";
+import { flagBool } from "../lib/args.js";
+import { c } from "../lib/colors.js";
+
+// The build/verify gate `validate` is not. `validate` checks the shape of
+// the artifact tree; it never runs the project, so a repo that does not
+// compile still "passes". `verify` closes that hole: it executes the
+// project-declared checks (typecheck / test / build) and fails when any
+// of them fails. Doctrina is language-agnostic and ships zero runtime
+// deps, so it cannot know your build — you declare it in
+// `.doctrina/verify.json`, and `verify` runs exactly that, in order.
+
+const CONFIG_REL = ".doctrina/verify.json";
+
+const STARTER = {
+  $comment:
+    "doctrina verify runs each check below, in order, through your shell. " +
+    "Replace the example with your real typecheck/test/build commands. A " +
+    "non-zero exit fails the gate. This file is the project's executable " +
+    "definition of 'the code actually works'.",
+  checks: [
+    { name: "example", run: "exit 1" },
+  ],
+};
+
+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 configPath = path.join(projectRoot, CONFIG_REL);
+
+  // --init scaffolds a starter config so the gate is one edit away.
+  if (flagBool(flags, "init", false)) {
+    const force = flagBool(flags, "force", false);
+    if (isFile(configPath) && !force) {
+      console.error(c.red("error:") + ` ${CONFIG_REL} already exists (pass --force to overwrite)`);
+      return 1;
+    }
+    write(configPath, JSON.stringify(STARTER, null, 2) + "\n", { force: true });
+    console.log(c.green("created") + ` ${CONFIG_REL}`);
+    console.log(c.gray("Edit the `checks` array with your real commands, then run `doctrina verify`."));
+    return 0;
+  }
+
+  if (!isFile(configPath)) {
+    // A verify gate with nothing configured would pass vacuously — exactly
+    // the false confidence this command exists to prevent. Fail loudly.
+    console.error(c.red("error:") + ` no ${CONFIG_REL} — nothing to verify`);
+    console.error(c.gray("hint: ") + "scaffold one with `doctrina verify --init`, then declare your typecheck/test/build commands");
+    return 1;
+  }
+
+  let config;
+  try {
+    config = JSON.parse(read(configPath));
+  } catch (err) {
+    console.error(c.red("error:") + ` ${CONFIG_REL} is not valid JSON: ${err.message}`);
+    return 1;
+  }
+  const checks = Array.isArray(config?.checks) ? config.checks : null;
+  if (!checks) {
+    console.error(c.red("error:") + ` ${CONFIG_REL} must contain a "checks" array of { name, run }`);
+    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`);
+      return 1;
+    }
+  }
+  if (checks.length === 0) {
+    console.error(c.red("error:") + ` ${CONFIG_REL} declares zero checks — a verify gate with no checks proves nothing`);
+    return 1;
+  }
+
+  // --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)}`);
+    });
+    return 0;
+  }
+
+  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("");
+    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,
+    // and platform builtins. stdio is inherited so the operator sees the
+    // real output — verify shows the truth, it does not summarise it away.
+    // An optional per-check `cwd` (relative to the project root) lets a
+    // monorepo target a sub-package, e.g. { run: "node --test", cwd:
+    // "packages/api" } — the multi-service shape the contract artifact
+    // also serves.
+    const res = spawnSync(ch.run, {
+      cwd: ch.cwd ? path.resolve(projectRoot, ch.cwd) : projectRoot,
+      shell: true,
+      stdio: "inherit",
+    });
+    const ok = !res.error && res.status === 0;
+    if (res.error) {
+      console.log(c.red(`✗ ${name}`) + c.gray(` — could not run: ${res.error.message}`));
+    } else {
+      console.log(ok ? c.green(`✓ ${name}`) : c.red(`✗ ${name} (exit ${res.status})`));
+    }
+    results.push({ name, ok });
+    // Fail fast is tempting, but running every check surfaces all breakage
+    // in one pass — more useful for an agent fixing the gap.
+  }
+
+  const passed = results.filter((r) => r.ok).length;
+  console.log("");
+  if (passed === results.length) {
+    console.log(c.green("ok") + ` ${passed}/${results.length} checks passed`);
+    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}`);
+  return 1;
+}
+
+export const help = `
+Usage: doctrina verify [--list] [--init] [--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):
+  {
+    "checks": [
+      { "name": "typecheck", "run": "tsc --noEmit", "cwd": "packages/api" },
+      { "name": "test",      "run": "npm test" },
+      { "name": "build",     "run": "npm run build" }
+    ]
+  }
+
+Flags:
+  --init     Scaffold a starter ${CONFIG_REL} (refuses to overwrite without --force)
+  --list     Print the configured checks without running them
+  --force    With --init, overwrite an existing config
+`;

package/src/commands/work.js

@@ -9,9 +9,10 @@ import { changeNew } from "./change.js";
 // `work` is the second half of the no-ceremony path (ADR 0005): a brief
 // prompt ("add login") becomes a fully scaffolded change plus a playbook
 // the host agent executes — context, spec deltas, tasks, implementation,
-// then the analyze → apply → archive → validate close. The CLI's own
-// language processing stops at slugging and term counting; everything
-// semantic is the agent's job.
+// then the analyze → apply → verify → archive → validate close (verify =
+// `doctrina verify` + `doctrina coverage`, since archive now refuses
+// unproven verification). The CLI's own language processing stops at
+// slugging and term counting; everything semantic is the agent's job.
 
 export async function run(positional, flags) {
   const prompt = positional.join(" ").trim();
@@ -183,18 +184,27 @@ function printPlaybook(projectRoot, { id, prompt, pinned, matches, capability })
   console.log(c.gray("       **Operation:** ADDED | MODIFIED | REMOVED"));
   console.log(c.gray("       **Target spec on apply:** `.doctrina/specs/<capability>/spec.md`"));
   console.log(c.gray("       ---"));
-  console.log(c.gray("       <EARS requirements: full spec body for ADDED, fragment for MODIFIED>"));
+  console.log(c.gray("       <EARS body. Keep the two axes honest (Status vs Implementation),"));
+  console.log(c.gray("        keep aspiration under ## Maturity → Future, and cite the proof per"));
+  console.log(c.gray("        criterion: \"1. [unverified] <signal> — verified by `path/to/test`\">"));
   console.log("");
   console.log(`4. Replace the placeholder tasks in .doctrina/changes/${id}/tasks.md`);
   console.log("   with small, checkable implementation tasks (a few hours each, max).");
   console.log("");
-  console.log("5. Implement task by task, checking each box as it lands. If the");
-  console.log("   prompt is genuinely ambiguous, ask the user before assuming.");
+  console.log("5. Implement task by task, checking each box as it lands. Advance the");
+  console.log("   spec's Implementation: planned → partial → implemented as code lands.");
+  console.log("   If the prompt is genuinely ambiguous, ask the user before assuming.");
   console.log("");
   console.log(`6. ${c.cyan(`doctrina analyze ${id}`)} — fix every ✗ before applying.`);
   console.log(`7. ${c.cyan(`doctrina change apply ${id}`)}   (MODIFIED deltas are merged by hand).`);
-  console.log(`8. ${c.cyan(`doctrina change archive ${id}`)}`);
-  console.log(`9. ${c.cyan("doctrina validate")}, then ${c.cyan("doctrina next")} for the follow-up.`);
+  console.log("8. Prove it before declaring done (archive refuses unchecked boxes):");
+  console.log(`       ${c.cyan("doctrina verify")}     — the project's typecheck/test/build gate`);
+  console.log(`       ${c.cyan("doctrina coverage")}   — each acceptance criterion cites a real test`);
+  console.log("   Then check the proposal's ## Verification boxes and every task,");
+  console.log("   closing steps included, and bump Implementation to verified.");
+  console.log("");
+  console.log(`9. ${c.cyan(`doctrina change archive ${id}`)}`);
+  console.log(`10. ${c.cyan("doctrina validate")}, then ${c.cyan("doctrina next")} for the follow-up.`);
 }
 
 export const help = `
@@ -205,8 +215,9 @@ 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:
-context → spec delta → tasks → implement → analyze → apply → archive →
-validate. No natural-language interpretation happens in the CLI.
+context → spec delta → tasks → implement → analyze → apply → verify
+(verify + coverage) → archive → validate. No natural-language
+interpretation happens in the CLI.
 
 Options:
   --capability <cap>   Pin the capability instead of ranking matches

package/src/index.js

@@ -24,11 +24,14 @@ import * as context from "./commands/context.js";
 import * as search from "./commands/search.js";
 import * as intake from "./commands/intake.js";
 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";
 
 const COMMANDS = {
   init, spec, change, decision, validate, hooks, analyze, clarify,
   templates, skill, index: indexCmd, next, metrics, context, search,
-  intake, work,
+  intake, work, coverage, verify, contract,
 };
 
 const TOP_HELP = `
@@ -44,6 +47,8 @@ Commands:
   change apply         Apply spec deltas (ADDED/REMOVED auto, MODIFIED manual)
   change archive       Archive an applied change
   change diff          Preview spec deltas (line diff for MODIFIED)
+  contract new         Own the integration surface (ports, env, interfaces)
+  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 supersede   Create a new ADR that supersedes an existing one
@@ -56,6 +61,8 @@ Commands:
   context              Print the context pack for a task in read order
   search               Search the artifact tree, grouped by category
   validate             Run schema and structural checks
+  coverage             Report acceptance criteria with linked evidence (--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
   hooks install        Install the pre-commit hook
@@ -70,7 +77,7 @@ Global flags:
 
 async function main(argv) {
   const { positional, flags } = parseArgs(argv, {
-    boolean: ["help", "h", "version", "v", "force", "non-interactive", "check", "save", "bug", "write", "all", "concat", "archive"],
+    boolean: ["help", "h", "version", "v", "force", "non-interactive", "check", "save", "bug", "write", "all", "concat", "archive", "strict", "list", "init"],
   });
 
   if (flags.get("version") || flags.get("v")) {

package/src/lib/index-json.js

@@ -44,6 +44,7 @@ export function blank(projectName, date) {
       changes: [],
       changes_archive: [],
       skills: [],
+      contracts: [],
     },
   };
 }
@@ -56,6 +57,14 @@ export function addSkill(index, entry) {
   return index;
 }
 
+export function addContract(index, entry) {
+  if (!index.artifacts.contracts) index.artifacts.contracts = [];
+  if (!index.artifacts.contracts.some((s) => s.id === entry.id)) {
+    index.artifacts.contracts.push(entry);
+  }
+  return index;
+}
+
 export function removeSkill(index, id) {
   if (!index.artifacts.skills) return index;
   index.artifacts.skills = index.artifacts.skills.filter((s) => s.id !== id);

package/src/lib/scan.js

@@ -55,6 +55,7 @@ export function deriveIndex(projectRoot, current) {
       changes: [],
       changes_archive: [],
       skills: [],
+      contracts: [],
     },
   };
 
@@ -65,13 +66,22 @@ export function deriveIndex(projectRoot, current) {
     if (!isFile(p)) continue;
     const text = read(p);
     const prev = (cur.specs ?? []).find((s) => s.id === cap);
-    out.artifacts.specs.push({
+    const entry = {
       id: cap,
       path: `.doctrina/specs/${cap}/spec.md`,
       status: specHeader(text, "Status") ?? prev?.status ?? "active",
       version: specHeader(text, "Version") ?? prev?.version ?? "0.1.0",
       last_updated: specHeader(text, "Last updated") ?? prev?.last_updated ?? date,
-    });
+    };
+    // Implementation is the capability axis (planned -> partial ->
+    // implemented -> verified), independent of the document Status. Only
+    // record it when the spec declares it or the index already tracked it,
+    // so specs that never opted in (e.g. bug specs) stay off the axis.
+    // The stored value keeps any explanatory note after the state word.
+    const implRaw = specHeader(text, "Implementation");
+    const impl = implRaw ? implRaw.trim() : prev?.implementation;
+    if (impl) entry.implementation = impl;
+    out.artifacts.specs.push(entry);
   }
 
   // Decisions — NNNN-slug.md files; Status/Date headers win.
@@ -143,6 +153,22 @@ export function deriveIndex(projectRoot, current) {
     });
   }
 
+  // Contracts — the integration/runtime surface (ports, env, interfaces)
+  // that no single capability owns. Headers inside each contract win.
+  const contractsDir = path.join(dot, "contracts");
+  for (const f of walk(contractsDir)) {
+    if (!f.endsWith(".md")) continue;
+    const id = path.basename(f, ".md");
+    const text = read(f);
+    const prev = (cur.contracts ?? []).find((s) => s.id === id);
+    out.artifacts.contracts.push({
+      id,
+      path: `.doctrina/contracts/${id}.md`,
+      status: specHeader(text, "Status") ?? prev?.status ?? "active",
+      last_updated: specHeader(text, "Last updated") ?? prev?.last_updated ?? date,
+    });
+  }
+
   // Skills — frontmatter description wins.
   const skillsDir = path.join(dot, "skills");
   for (const f of walk(skillsDir)) {
@@ -183,7 +209,7 @@ export function indexesMatch(a, b) {
     const clone = { ...x };
     delete clone.last_updated;
     const arts = { ...(clone.artifacts ?? {}) };
-    for (const cat of ["specs", "decisions", "changes", "changes_archive", "skills"]) {
+    for (const cat of ["specs", "decisions", "changes", "changes_archive", "skills", "contracts"]) {
       arts[cat] = arts[cat] ?? [];
     }
     clone.artifacts = arts;

package/templates/change/proposal.md.template

@@ -19,7 +19,16 @@
 
 ## Verification
 
-<!-- How you will know the change is correctly applied. -->
+<!--
+How you will know the change is correctly applied. Use checkboxes: every
+box here is a claim that must be PROVEN before the change is done.
+`doctrina change archive` refuses to archive while any box below is
+unchecked (pass --force to archive anyway and record the gap). Distinguish
+"task marked done" from "verification passed" — link the evidence.
+-->
+
+- [ ] Automated checks pass (`doctrina verify`, or the project's typecheck/test/build).
+- [ ] The affected spec's acceptance criteria are met and cite their evidence (`doctrina coverage`).
 
 ## Open questions
 

package/templates/contract.md.template

@@ -0,0 +1,58 @@
+# Contract — {{CONTRACT_NAME}}
+
+**Contract:** {{CONTRACT_NAME}}
+**Status:** active
+**Last updated:** {{DATE}}
+
+## Purpose
+
+<!--
+The integration/runtime surface this contract OWNS. No single capability
+spec owns the seams between services and front-ends — this artifact does.
+If a login response shape, a WebSocket path, or a Kafka topic falls in the
+gap between two specs, it belongs here.
+-->
+
+## Ports
+
+<!--
+The single source of truth for who listens where. `doctrina contract check`
+fails when two rows claim the same port (the "front points at the wrong
+port" class of bug). Front-ends and clients read their targets from here.
+-->
+
+| Service | Port | Protocol |
+|---------|------|----------|
+| gateway | 8080 | http     |
+
+## Environment
+
+<!--
+Variables the running system requires, named IDENTICALLY across code,
+`.env.example`, and infra (compose/helm). `doctrina contract check` warns
+when a variable here is missing from `.env.example` — the DATABASE_URL /
+KAFKA_BROKER drift class.
+-->
+
+| Variable     | Required | Example                                   |
+|--------------|----------|-------------------------------------------|
+| DATABASE_URL | yes      | postgres://user:pass@localhost:5432/app   |
+
+## Interfaces
+
+<!--
+API / WebSocket / event-stream contracts: endpoints, message shapes, event
+schemas, and the exact response shape each consumer can rely on (e.g. login
+returns `{ token, user }`, not a bare `TokenPair`).
+-->
+
+-
+
+## References
+
+<!--
+The capability specs that must conform to this contract. List each as
+`specs/<capability>`; `doctrina contract check` verifies each spec exists.
+-->
+
+- `specs/<capability>`

package/templates/decision.md.template

@@ -5,6 +5,16 @@
 - **Deciders:**
 - **Supersedes:** —
 - **Superseded by:** —
+- **Evidence:** —
+
+<!--
+Evidence anchors the decision to reality. Once accepted, cite the file(s)
+that prove this decision is actually implemented, in backticks, e.g.
+"- **Evidence:** `proto/order.proto`, `services/gateway/grpc.ts`".
+`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>".
+-->
 
 ## Context
 

package/templates/doctrina/product.md.template

@@ -29,3 +29,15 @@ Out of scope (deferred or rejected):
 ## Success criteria
 
 <!-- How you will know this project is working. Prefer measurable signals. -->
+
+## Delivery order (walking skeleton)
+
+<!--
+Depth before breadth. Name the ONE end-to-end path that must work and be
+verified before any capability fans out — the walking skeleton (e.g.
+auth -> ingest -> ws -> ui). A spec'd capability with no working slice
+through it is breadth bought on credit: build and `doctrina verify` the
+skeleton first, then spec the next capability.
+-->
+
+1.

package/templates/spec.md.template

@@ -1,10 +1,24 @@
 # Spec — {{CAPABILITY}}
 
 **Capability:** {{CAPABILITY}}
-**Status:** active
+**Status:** draft
+**Implementation:** planned
 **Last updated:** {{DATE}}
 **Version:** 0.1.0
 
+<!--
+Two independent axes — keep them honest:
+  Status         — the document:   draft -> active -> deprecated
+  Implementation — the capability: planned -> partial -> implemented -> verified
+Flip Status to "active" only once this spec reflects intended truth.
+Advance Implementation as code lands; "verified" means a test proves it
+(cite the test per acceptance criterion — see `doctrina coverage`).
+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".
+-->
+
 ## Purpose
 
 <!-- One paragraph: what this capability does and why it exists. -->
@@ -43,9 +57,33 @@ Easy Approach to Requirements Syntax. Use one of the five forms per item:
 
 ## Acceptance criteria
 
-<!-- Concrete, observable signals that the capability is correctly implemented. -->
+<!--
+Concrete, observable signals that the capability is correctly implemented.
+Each criterion is also a claim that must be proven: mark it [verified] or
+[unverified] and cite the artifact/test in backticks. `doctrina coverage`
+reports which criteria have no linked evidence — an [unverified] criterion
+with no test is explicit debt, not a fact.
+-->
+
+1. [unverified] <observable signal> — verified by `path/to/test`.
 
-1.
+## Maturity
+
+<!--
+The line between an MVP and a product wishlist. List under MVP only what
+this capability COMMITS to now. Anything aspirational goes under Future and
+is explicitly NOT accepted scope — do not write Future items in EARS as if
+they were already built (no WebGPU/multi-cloud/"50k entities at 30fps"
+smuggled in as committed requirements).
+-->
+
+**MVP (committed):**
+
+-
+
+**Future (aspirational, not committed):**
+
+-
 
 ## Out of scope for this spec