doctrina-cli 0.2.1 → 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.1",
+  "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/skill.js

@@ -54,7 +54,10 @@ function skillNew(args, flags) {
   idx.addSkill(index, {
     id: name,
     path: `.doctrina/skills/${name}.md`,
-    description: "<edit me — one-sentence summary>",
+    // Seed the index from the scaffolded frontmatter so a fresh skill does
+    // not immediately trip validate's description-drift check. Matches how
+    // deriveIndex (index rebuild) reads the description.
+    description: parseFrontmatter(body, "description") ?? "<edit me — one-sentence summary>",
     last_updated: date,
   });
   idx.touch(index, date);

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}"`);