doctrina-cli 0.2.1 → 0.3.0

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}`);
@@ -67,7 +69,7 @@ export async function run(_positional, _flags) {
       for (const s of index.artifacts.specs ?? []) {
         const full = path.join(projectRoot, s.path);
         if (!isFile(full)) continue;
-        const m = read(full).match(/^\*\*Version:\*\*\s+(\S+)/m);
+        const m = read(full).match(/^(?:-\s+)?\*\*Version:\*\*\s+(\S+)/m);
         if (m && s.version && m[1] !== s.version) {
           warnings.push(`${s.path} declares version ${m[1]} but index.json records ${s.version} (sync the index)`);
         }
@@ -80,9 +82,55 @@ export async function run(_positional, _flags) {
   if (isDir(adrDir)) {
     for (const f of walk(adrDir)) {
       if (!f.endsWith(".md")) continue;
+      const base = path.basename(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
+      // "ADR-001-foo.md" is silently invisible to all of them.
+      if (base !== "README.md" && !/^\d{4}-.+\.md$/.test(base)) {
+        errors.push(
+          `${relPath(projectRoot, f)} has a non-canonical ADR filename ` +
+            `(expected four digits + slug, e.g. "0001-jwt-algorithm.md"; ` +
+            `the decision and index commands silently ignore other shapes)`,
+        );
+      }
       const text = read(f);
       if (!/^-\s+\*\*Status:\*\*\s+\S+/m.test(text)) {
-        errors.push(`${relPath(projectRoot, f)} missing or malformed Status: header`);
+        errors.push(
+          `${relPath(projectRoot, f)} missing or malformed Status: header ` +
+            `(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)`,
+              );
+            }
+          }
+        }
       }
     }
   }
@@ -105,7 +153,10 @@ export async function run(_positional, _flags) {
       if (entry === "archive" || entry.startsWith(".")) continue;
       const proposal = path.join(changesDir, entry, "proposal.md");
       if (!isFile(proposal)) {
-        errors.push(`open change "${entry}" missing proposal.md`);
+        errors.push(
+          `open change "${entry}" missing proposal.md ` +
+            `(every dir under .doctrina/changes/ needs a proposal.md — that exact filename)`,
+        );
       }
     }
   }
@@ -127,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>")`,
+            );
+          }
+        }
       }
     }
   }
@@ -184,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
@@ -272,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

@@ -5,15 +5,23 @@ import { today } from "./dates.js";
 import { parseFrontmatter } from "../commands/skill.js";
 import { parseOperation, parseCapabilityFromDelta } from "../commands/change.js";
 
-// Parse a spec-style header line: **Name:** value
+// Parse a metadata header line, tolerating BOTH conventions:
+//   **Name:** value        (spec style)
+//   - **Name:** value      (ADR / proposal / intake style)
+// The leading "- " is optional so a one-character convention slip (an
+// agent hand-authoring an ADR with the bare spec form, or vice versa)
+// still parses instead of silently falling back to a default value.
+const HEADER_PREFIX = "(?:-\\s+)?";
+
+// Parse a spec-style header line: **Name:** value (dash optional).
 export function specHeader(text, name) {
-  const m = text.match(new RegExp(`^\\*\\*${name}:\\*\\*\\s+(.+)$`, "m"));
+  const m = text.match(new RegExp(`^${HEADER_PREFIX}\\*\\*${name}:\\*\\*\\s+(.+)$`, "m"));
   return m ? m[1].trim() : null;
 }
 
-// Parse an ADR/proposal-style header line: - **Name:** value
+// Parse an ADR/proposal-style header line: - **Name:** value (dash optional).
 export function listHeader(text, name) {
-  const m = text.match(new RegExp(`^-\\s+\\*\\*${name}:\\*\\*\\s+(.+)$`, "m"));
+  const m = text.match(new RegExp(`^${HEADER_PREFIX}\\*\\*${name}:\\*\\*\\s+(.+)$`, "m"));
   return m ? m[1].trim() : null;
 }
 
@@ -47,6 +55,7 @@ export function deriveIndex(projectRoot, current) {
       changes: [],
       changes_archive: [],
       skills: [],
+      contracts: [],
     },
   };
 
@@ -57,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.
@@ -135,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)) {
@@ -175,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/AGENTS.md.template

@@ -56,6 +56,34 @@ native multi-agent development. The full framework artifacts live under
 - Archived changes in `.doctrina/changes/archive/` are out of the default
   read path; consult only when explicitly debugging history.
 
+## Artifact invariants (verbatim — `doctrina validate` enforces these)
+
+Scaffold artifacts with the CLI (`doctrina decision new`, `doctrina work`),
+which writes from the canonical templates. Do NOT hand-author these files
+from memory. If you must write one by hand, match these exactly:
+
+- **Metadata headers come in two forms — do not mix them up:**
+  - ADRs, change proposals, and the intake use **list items**:
+    `- **Status:** accepted`, `- **Date:** 2026-06-13`.
+  - Specs use **bare bold** (no leading `- `):
+    `**Status:** active`, `**Version:** 0.1.0`.
+  Match the template for the artifact you are writing.
+- **ADR filename** must be `NNNN-slug.md` — four digits, e.g.
+  `0001-jwt-algorithm.md`. `ADR-001-...md` or `1-...md` is invisible to
+  `doctrina decision accept`, the index, and the orphan check.
+- **Change folder** at `.doctrina/changes/<id>/` must contain a file named
+  exactly `proposal.md` (not `change.md`, not `README.md`). `tasks.md` and
+  `design.md` are optional siblings.
+- **Spec** lives at `.doctrina/specs/<capability>/spec.md` and its
+  `**Version:**` header must equal the `version` recorded for it in
+  `.doctrina/index.json`.
+- **Every artifact on disk** must be registered in `.doctrina/index.json`,
+  and every path in `index.json` must exist on disk. Update the index in
+  the same change that adds or moves a file.
+
+Always finish by running `doctrina validate` and resolving every `error:`
+before considering work done.
+
 ## How to read context efficiently
 
 1. Read this `AGENTS.md`.

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>`