doctrina-cli 0.10.0 → 0.12.0

package/src/commands/why.js

@@ -2,7 +2,7 @@ import path from "node:path";
 import process from "node:process";
 import { readdirSync } from "node:fs";
 import { exists, isDir, isFile, read } from "../lib/fs-ops.js";
-import { specHeader, listHeader } from "../lib/scan.js";
+import { specHeader, listHeader, parseDependsOn } from "../lib/scan.js";
 import { parseAcceptanceCriteria, isVerified } from "../lib/criteria.js";
 import * as idx from "../lib/index-json.js";
 import { c } from "../lib/colors.js";
@@ -26,10 +26,17 @@ export async function run(positional, _flags) {
   const known = isDir(specsDir) ? readdirSync(specsDir).filter((e) => isFile(path.join(specsDir, e, "spec.md"))) : [];
 
   if (!cap) {
-    console.error(c.red("error:") + " why requires a <capability>");
+    console.error(c.red("error:") + " why requires a <capability> (or an intent anchor like SC1)");
     if (known.length) console.error(c.gray("known: ") + known.sort().join(", "));
     return 2;
   }
+
+  // Reverse mode: `doctrina why SC1` walks the chain the other way — from a
+  // product intent anchor to the capabilities that realize it and the work
+  // that delivered them. Forward mode asks "why does this capability exist?";
+  // reverse mode asks "who delivers this promise?".
+  if (/^[A-Z]+\d+$/.test(cap)) return whyAnchor(projectRoot, cap, specsDir, known);
+
   const specPath = path.join(specsDir, cap, "spec.md");
   if (!isFile(specPath)) {
     console.error(c.red("error:") + ` no spec for capability "${cap}"`);
@@ -68,6 +75,16 @@ export async function run(positional, _flags) {
   const purpose = sectionParagraph(text, "Purpose");
   if (purpose) console.log("    " + purpose.replace(/\s+/g, " ").trim());
 
+  // Dependency graph, both directions (the machine-readable **Depends on:**
+  // header — specs used to cite each other only in prose, invisible here).
+  const deps = parseDependsOn(text);
+  const dependents = known
+    .filter((other) => other !== cap)
+    .filter((other) => parseDependsOn(read(path.join(specsDir, other, "spec.md"))).includes(cap))
+    .sort();
+  if (deps.length > 0) console.log(`    ${c.gray("depends on:")} ${deps.map((d) => c.cyan(d)).join(", ")}`);
+  if (dependents.length > 0) console.log(`    ${c.gray("depended on by:")} ${dependents.map((d) => c.cyan(d)).join(", ")}`);
+
   // 3. The proof (acceptance criteria with cited evidence). Read through the
   //    shared multi-line parser so the marks here agree with `doctrina
   //    coverage` — a criterion that cites its proof on a continuation line is
@@ -130,6 +147,58 @@ export async function run(positional, _flags) {
   return 0;
 }
 
+// Reverse provenance: one intent anchor → the capabilities that realize it,
+// each with its proof state, plus the archived changes that built them.
+function whyAnchor(projectRoot, id, specsDir, known) {
+  const anchors = productAnchors(projectRoot);
+  if (!anchors.has(id)) {
+    console.error(c.red("error:") + ` no anchor [${id}] in .doctrina/product.md`);
+    if (anchors.size) console.error(c.gray("known: ") + [...anchors.keys()].join(", "));
+    return 1;
+  }
+
+  console.log(c.bold(`Why ${id}`) + c.gray(" — reverse provenance (intent → capabilities → proof → history)"));
+  console.log("");
+  console.log(c.bold("  Intent"));
+  console.log(`    ${c.cyan(id)}  ${anchors.get(id)}`);
+
+  const realizing = [];
+  for (const capName of known.sort()) {
+    const text = read(path.join(specsDir, capName, "spec.md"));
+    const realizesRaw = specHeader(text, "Realizes");
+    const ids = realizesRaw ? (realizesRaw.match(/[A-Z]+\d+/g) ?? []) : [];
+    if (ids.includes(id)) realizing.push({ cap: capName, text });
+  }
+
+  console.log("");
+  console.log(c.bold("  Realized by"));
+  if (realizing.length === 0) {
+    console.log(`    ${c.red("nothing")} ${c.gray("— dropped intent: no spec declares Realizes: " + id + " (doctrina trace)")}`);
+    return 0;
+  }
+  for (const s of realizing) {
+    const status = specHeader(s.text, "Status") ?? "—";
+    const impl = specHeader(s.text, "Implementation") ?? "—";
+    const criteria = parseAcceptanceCriteria(s.text);
+    const proven = criteria.filter((cr) => cr.proofPaths.length > 0).length;
+    console.log(
+      `    ${c.cyan(s.cap.padEnd(14))} ${c.gray(`status: ${status} · implementation: ${impl} · proof: ${proven}/${criteria.length} criteria cite evidence`)}`,
+    );
+  }
+
+  console.log("");
+  console.log(c.bold("  History"));
+  let any = false;
+  for (const s of realizing) {
+    for (const ch of archivedChangesFor(projectRoot, s.cap)) {
+      console.log(`    ${c.cyan(ch.applied ?? "—")}  ${ch.title} ${c.gray(`(${s.cap}, ${ch.op})`)}`);
+      any = true;
+    }
+  }
+  if (!any) console.log(`    ${c.gray("no archived change recorded against the realizing capabilities")}`);
+  return 0;
+}
+
 // Archived changes whose recorded specs_affected include this capability,
 // oldest first. Read from the index ledger (the same data `index rebuild`
 // derives from each change's spec deltas); absent or unreadable index → none.
@@ -202,14 +271,18 @@ function decisionsMentioning(projectRoot, cap) {
 }
 
 export const help = `
-Usage: doctrina why <capability>
+Usage: doctrina why <capability | anchor>
+
+Explain provenance in either direction, read-only:
 
-Explain a capability's provenance by assembling the chain Doctrina already
-records into one read: the product intent it **Realizes:** ([SC1] anchors),
-the capability's purpose and status, the acceptance criteria that prove it
-(with cited evidence), the accepted ADRs that name it, and the archived
-changes that built it (from the index ledger). Read-only.
+  doctrina why billing   forward — the product intent the capability
+                         Realizes:, its purpose/status, the acceptance
+                         criteria that prove it, the accepted ADRs that
+                         name it, and the archived changes that built it.
+  doctrina why SC1       reverse — the intent anchor's product.md text,
+                         the capabilities that realize it (with proof
+                         state), and the archived changes behind them.
 
-Builds on the intent provenance (ADR 0006/0011) — answer "why was X built,
-and built this way?" without grepping the tree by hand.
+Builds on the intent provenance (ADR 0006/0011) — answer "why was X built"
+or "who delivers this promise?" without grepping the tree by hand.
 `;

package/src/commands/work.js

@@ -71,14 +71,18 @@ export async function run(positional, flags) {
   }
 
   const effPrompt = prompt || `backfill specs from ${files.length} changed file${files.length === 1 ? "" : "s"}`;
-  const slug = prompt ? slugify(prompt) : "backfill";
+  // --title separates the short display name from the full brief: the title
+  // drives the slug and the proposal H1; the whole prompt still lands, intact,
+  // under ## Why. Without it a long prompt used to become a 900-char H1.
+  const title = flagString(flags, "title") ?? effPrompt;
+  const slug = prompt || flags.has("title") ? slugify(title) : "backfill";
   const id = flagString(flags, "id") ?? `${nextChangeNumber(projectRoot)}-${slug}`;
   if (!/^[a-z0-9][a-z0-9-]*$/.test(id)) {
     console.error(c.red("error:") + ` invalid change id "${id}" (lowercase letters, digits, hyphens)`);
     return 2;
   }
 
-  const code = changeNew([id, effPrompt], flags);
+  const code = changeNew([id, title], flags);
   if (code !== 0) return code;
 
   // Record the prompt verbatim as the change's Why — the raw intent has
@@ -228,6 +232,9 @@ function resumeChange(projectRoot, resumeId) {
 }
 
 // ASCII-folded kebab-case of the prompt ("Faça o login" -> "faca-o-login").
+// Over-long slugs are cut at a WORD boundary, not mid-token — a 900-char
+// prompt used to produce folder names ending in a half word ("...-scoped-c"),
+// which then leaks into every path, ledger line, and archive name.
 export function slugify(text) {
   let slug = text
     .normalize("NFD")
@@ -235,7 +242,11 @@ export function slugify(text) {
     .toLowerCase()
     .replace(/[^a-z0-9]+/g, "-")
     .replace(/^-+|-+$/g, "");
-  if (slug.length > 48) slug = slug.slice(0, 48).replace(/-+$/g, "");
+  if (slug.length > 48) {
+    const cut = slug.slice(0, 49); // one past the cap: a "-" here means 48 ends a word
+    const boundary = cut.lastIndexOf("-");
+    slug = (boundary > 0 ? cut.slice(0, boundary) : cut.slice(0, 48)).replace(/-+$/g, "");
+  }
   return slug.length > 0 ? slug : "task";
 }
 
@@ -292,7 +303,7 @@ export function rankCapabilities(projectRoot, prompt) {
 // file scores its capability when the file sits under a path segment named for
 // it, or when the spec cites the file as evidence. A deterministic overlap
 // hint for the agent — never a decision (ADR 0005).
-export function rankCapabilitiesByDiff(projectRoot, files) {
+export function rankCapabilitiesByDiff(projectRoot, files, { limit = 3 } = {}) {
   const specsDir = path.join(projectRoot, ".doctrina", "specs");
   if (!files || files.length === 0 || !isDir(specsDir)) return [];
   const norm = files.map((f) => f.replace(/\\/g, "/"));
@@ -310,7 +321,10 @@ export function rankCapabilitiesByDiff(projectRoot, files) {
     }
     if (score > 0) ranked.push({ id: cap, score, path: `.doctrina/specs/${cap}/spec.md` });
   }
-  return ranked.sort((a, b) => b.score - a.score || a.id.localeCompare(b.id)).slice(0, 3);
+  // `limit` keeps the work-playbook hint short (top 3); review passes
+  // Infinity — truncating there is how it missed 5 of 8 touched capabilities
+  // in the 0.11.0 field session.
+  return ranked.sort((a, b) => b.score - a.score || a.id.localeCompare(b.id)).slice(0, limit);
 }
 
 // A chore is a spec-less change (review F9): the playbook drops the spec-delta
@@ -401,6 +415,16 @@ function printPlaybook(projectRoot, { id, prompt, pinned, matches, capability, c
   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(c.gray("   New capability? `spec new` then an ADDED delta with the FULL body — apply"));
+  console.log(c.gray("   replaces the untouched scaffold. Bookkeeping edits? MODIFIED with an ops"));
+  console.log(c.gray("   block, applied mechanically (all ops or none):"));
+  console.log(c.gray("       ```ops"));
+  console.log(c.gray("       set-header Implementation: verified — `src/x.js`"));
+  console.log(c.gray("       bump-version minor"));
+  console.log(c.gray("       set-criterion 1: verified"));
+  console.log(c.gray("       append-criterion [unverified] new signal — verified by `test/y.test.js`"));
+  console.log(c.gray("       ```"));
+  console.log(c.gray("   Only prose rewrites stay a by-hand merge."));
   if (fromDiff) {
     console.log(c.gray("   --from-diff: the code already exists — describe its CURRENT behaviour, and"));
     console.log(c.gray("   mark each criterion [unverified] until a test proves it (don't assume the"));
@@ -414,19 +438,22 @@ function printPlaybook(projectRoot, { id, prompt, pinned, matches, capability, c
   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 with an ops block applies mechanically; prose merges by hand).`);
-  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(`       ${c.cyan("doctrina trace")}      — the capability traces to product intent`);
-  console.log("   Then check the proposal's ## Verification boxes and every task,");
+  console.log(`6. ADR checkpoint — does this change decide something structural`);
+  console.log("   (an architecture, a boundary, a trade-off a future session must");
+  console.log(`   not relitigate)? If yes: ${c.cyan("doctrina decision new \"<title>\"")} now,`);
+  console.log("   before closing — the definition of done requires it recorded.");
+  console.log("");
+  console.log(`7. Close in one attested pass (preferred — runs every gate and stops`);
+  console.log("   at the first failure with the exact rerun command):");
+  console.log(`       ${c.cyan(`doctrina close ${id}`)}`);
+  console.log(c.gray("   (equivalent, step by step: ") +
+    c.gray(`analyze → change apply → verify → coverage → trace → change archive → validate)`));
+  console.log("   Before it: 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.`);
-  console.log(c.gray("    If this change taught a reusable lesson (a fix you'd hate to relearn,"));
-  console.log(c.gray("    a recurring convention), capture it: ") + c.cyan("doctrina skill new <slug>") + c.gray("."));
+  console.log(`8. ${c.cyan("doctrina next")} for the follow-up.`);
+  console.log(c.gray("   If this change taught a reusable lesson (a fix you'd hate to relearn,"));
+  console.log(c.gray("   a recurring convention), capture it: ") + c.cyan("doctrina skill new <slug>") + c.gray("."));
 }
 
 export const help = `
@@ -447,6 +474,8 @@ already open, work suggests resuming it instead of opening a junk change
 named after that word (review G1). Use --resume to do so directly.
 
 Options:
+  --title "<short>"    Short display title: drives the slug and the proposal
+                       H1; the full prompt still lands under ## Why
   --capability <cap>   Pin the capability instead of ranking matches
   --id <id>            Override the derived change id
   --resume <id>        Reprint the playbook for an open change; create nothing

package/src/index.js

@@ -4,6 +4,7 @@ import { parseArgs } from "./lib/args.js";
 import { c } from "./lib/colors.js";
 import { suggest } from "./lib/suggest.js";
 import { cliVersion } from "./lib/version.js";
+import { surfaceHelp } from "./lib/commands.js";
 
 import * as init from "./commands/init.js";
 import * as spec from "./commands/spec.js";
@@ -32,58 +33,29 @@ import * as review from "./commands/review.js";
 import * as watch from "./commands/watch.js";
 import * as why from "./commands/why.js";
 import * as constitution from "./commands/constitution.js";
+import * as prime from "./commands/prime.js";
+import * as handoff from "./commands/handoff.js";
+import * as show from "./commands/show.js";
+import * as doctor from "./commands/doctor.js";
+import * as report from "./commands/report.js";
+import * as completion from "./commands/completion.js";
+import * as intent from "./commands/intent.js";
+import * as upgrade from "./commands/upgrade.js";
 
 const COMMANDS = {
   init, spec, change, decision, validate, hooks, analyze, clarify,
   templates, skill, index: indexCmd, next, metrics, context, search,
   intake, work, coverage, verify, contract, trace,
   status, close, review, watch, why, constitution,
+  prime, handoff, show, doctor, report, completion,
+  intent, upgrade,
 };
 
 const TOP_HELP = `
 Usage: doctrina <command> [options]
 
 Commands:
-  init                 Scaffold AGENTS.md and .doctrina/ in the current directory
-  intake               Store the full project description; print the bootstrap playbook
-  work                 Brief prompt -> scaffolded change + guided work playbook
-  spec new             Create a new capability spec (--bug for bug-shape)
-  spec list            List specs with version, status, and size
-  change new           Open a change proposal
-  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 land        Record that an accepted ADR is now implemented (non-mutating)
-  decision supersede   Create a new ADR that supersedes an existing one
-  decision list        List ADRs with status, date, and title
-  skill new            Scaffold an on-demand procedural memory skill
-  skill list           List skills with their descriptions
-  skill sync           Mirror skill frontmatter descriptions into index.json
-  skill suggest        Surface fix-shaped lessons worth a skill (--write scaffolds)
-  analyze              Inspect a change folder before applying
-  clarify              Smell-test a Markdown file for ambiguity (--all for the tree)
-  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)
-  trace                Report intent provenance: product intent → specs (--strict gates)
-  review               Conformance review of your changes vs specs/ADRs/contracts
-  verify               Run project-declared typecheck/test/build checks (the real gate)
-  close                Run the whole close sequence for a change in one pass
-  status               One-glance project health dashboard
-  why                  Explain a capability's provenance (intent → proof → ADRs)
-  constitution         Print the standing rules: accepted ADRs + product non-goals
-  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
-  index rebuild        Regenerate index.json from the artifacts on disk
-  next                 Print the recommended next workflow actions
-  watch                Re-run validate --fix + next on every change (--once for one pass)
-  metrics              Local git-derived adoption metrics (no network)
+${surfaceHelp()}
 
 Global flags:
   --help, -h           Show this message (or per-command help if after a command)
@@ -91,11 +63,17 @@ Global flags:
 `;
 
 async function main(argv) {
+  // `--version` is only "print the CLI version" when NO command is given.
+  // With a command it is that command's flag to consume — the old global
+  // intercept made `doctrina spec set x --version 0.10.0` print the CLI
+  // version and exit, looking exactly like the spec's version had been set
+  // (0.11.0 field-review papercut). `-v` stays global either way.
+  const versionOnly = argv.every((t) => t === "--version" || t === "-v") && argv.length > 0;
   const { positional, flags } = parseArgs(argv, {
-    boolean: ["help", "h", "version", "v", "force", "non-interactive", "check", "save", "bug", "write", "all", "concat", "archive", "strict", "list", "init", "fix", "once", "clean"],
+    boolean: ["help", "h", "v", "force", "non-interactive", "check", "save", "bug", "write", "all", "concat", "archive", "strict", "list", "init", "fix", "once", "clean", "json"],
   });
 
-  if (flags.get("version") || flags.get("v")) {
+  if (versionOnly || flags.get("v") === true) {
     console.log(cliVersion());
     return 0;
   }

package/src/lib/commands.js

@@ -13,15 +13,87 @@ export const COMMAND_NAMES = [
   // bootstrap / day-to-day
   "init", "intake", "work",
   // authoring
-  "spec", "change", "contract", "decision", "skill",
+  "spec", "change", "contract", "decision", "skill", "intent",
   // read / orient
-  "context", "search", "status", "next", "why", "constitution",
+  "prime", "context", "show", "search", "status", "next", "why", "handoff", "constitution",
   // gates
-  "analyze", "clarify", "validate", "coverage", "trace", "review", "verify", "close",
+  "analyze", "clarify", "validate", "coverage", "trace", "review", "verify", "close", "doctor",
   // maintenance
-  "templates", "hooks", "index", "watch", "metrics",
+  "templates", "hooks", "index", "watch", "metrics", "report", "completion", "upgrade",
 ];
 
+// The full operation surface — every `doctrina <command> [<subcommand>]` a
+// user can invoke, each with the one-line summary `--help` prints. This is
+// the single source the top-level help is GENERATED from, so an operation
+// that exists in a dispatch switch but not here is now a loud test failure
+// instead of a hidden feature (`spec set` / `change abandon` shipped and
+// stayed invisible to `--help`, AGENTS.md, and the CLI reference — the exact
+// drift the AGENTS.md gate could not see because its catalog stops at the
+// top-level names). Tests assert: every op resolves to a real handler, the
+// top-level words equal COMMAND_NAMES, and the cli-reference docs cover
+// every op.
+export const OPERATIONS = [
+  ["init", "Scaffold AGENTS.md and .doctrina/ in the current directory"],
+  ["intake", "Store the full project description; print the bootstrap playbook"],
+  ["work", "Brief prompt -> scaffolded change + guided work playbook"],
+  ["spec new", "Create a new capability spec (--bug for bug-shape)"],
+  ["spec list", "List specs with version, status, and size"],
+  ["spec set", "Edit spec headers / a criterion mark and resync the index"],
+  ["change new", "Open a change proposal"],
+  ["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)"],
+  ["change abandon", "Discard an open change cleanly (recorded in the ledger)"],
+  ["contract new", "Own the integration surface (ports, env, interfaces)"],
+  ["contract list", "List contracts with status and last-updated date"],
+  ["contract check", "Verify port collisions, env drift, referenced specs"],
+  ["decision new", "Create the next sequentially numbered ADR"],
+  ["decision accept", "Flip a proposed ADR to accepted"],
+  ["decision land", "Record that an accepted ADR is now implemented (non-mutating)"],
+  ["decision supersede", "Create a new ADR that supersedes an existing one"],
+  ["decision list", "List ADRs with status, date, and title"],
+  ["skill new", "Scaffold an on-demand procedural memory skill"],
+  ["skill list", "List skills with their descriptions"],
+  ["skill sync", "Mirror skill frontmatter descriptions into index.json"],
+  ["skill suggest", "Surface fix-shaped lessons worth a skill (--write scaffolds)"],
+  ["intent add", "Append a new product intent anchor post-intake (- [SC5] ...)"],
+  ["intent list", "List product.md intent anchors in document order"],
+  ["analyze", "Inspect a change folder before applying"],
+  ["clarify", "Smell-test a Markdown file for ambiguity (--all for the tree)"],
+  ["prime", "Session primer: gates, rules, open work, next steps in one read"],
+  ["context", "Print the context pack for a task in read order"],
+  ["show", "Point-read a requirement/criterion/ADR (cli-R12, cli-C3, 0007)"],
+  ["search", "Search the artifact tree, grouped by category"],
+  ["validate", "Run schema and structural checks"],
+  ["coverage", "Report acceptance criteria with linked evidence (--strict gates)"],
+  ["trace", "Report intent provenance: product intent → specs (--strict gates)"],
+  ["review", "Conformance review of your changes vs specs/ADRs/contracts"],
+  ["verify", "Run project-declared typecheck/test/build checks (the real gate)"],
+  ["close", "Run the whole close sequence for a change in one pass"],
+  ["doctor", "Aggregate diagnostic with per-finding remediation (a driver)"],
+  ["status", "One-glance project health dashboard"],
+  ["why", "Explain provenance: a capability's chain, or an anchor's (SC1)"],
+  ["handoff", "Markdown handoff note: open work, task state, resume command"],
+  ["constitution", "Print the standing rules: accepted ADRs + product non-goals"],
+  ["templates list", "List the templates shipped by the installed CLI"],
+  ["templates check", "Compare the project against the recommended template shape"],
+  ["templates update", "Additive fixer for check findings (preview; --write applies)"],
+  ["hooks install", "Install the pre-commit hook"],
+  ["index rebuild", "Regenerate index.json from the artifacts on disk"],
+  ["next", "Print the recommended next workflow actions"],
+  ["watch", "Re-run validate --fix + next on every change (--once for one pass)"],
+  ["metrics", "Local git-derived adoption metrics (no network)"],
+  ["report", "Markdown digest for a period: changes, gates, git summary"],
+  ["completion", "Print bash/zsh/pwsh completions (generated from the catalog)"],
+  ["upgrade", "Bring an existing project up to the installed CLI (--write applies)"],
+];
+
+// The Commands block of `doctrina --help`, generated from OPERATIONS so the
+// printed surface can never omit an operation the catalog knows about.
+export function surfaceHelp() {
+  return OPERATIONS.map(([op, summary]) => `  ${op.padEnd(21)}${summary}`).join("\n");
+}
+
 // Extract the set of top-level `doctrina <command>` references that appear in
 // CODE context (fenced blocks or inline backtick spans) of a Markdown file —
 // AGENTS.md, typically. Restricting to code context avoids matching prose like

package/src/lib/scan.js

@@ -25,6 +25,15 @@ export function listHeader(text, name) {
   return m ? m[1].trim() : null;
 }
 
+// The machine-readable "**Depends on:** defects, decisions" spec header: the
+// sibling capabilities this spec builds on. Returns [] when absent, "n/a", or
+// empty. One parser so index, why, context, and review agree.
+export function parseDependsOn(text) {
+  const raw = specHeader(text, "Depends on");
+  if (!raw || /^n\/a\b/i.test(raw.trim()) || raw.trim() === "—") return [];
+  return raw.match(/[a-z][a-z0-9][a-z0-9-]*/g) ?? [];
+}
+
 function dirEntries(dir) {
   if (!isDir(dir)) return [];
   return readdirSync(dir).filter((e) => !e.startsWith(".")).sort();
@@ -87,6 +96,13 @@ export function deriveIndex(projectRoot, current) {
     const realizesRaw = specHeader(text, "Realizes");
     const realizes = realizesRaw ? (realizesRaw.match(/[A-Z]+\d+/g) ?? []) : prev?.realizes;
     if (realizes && realizes.length) entry.realizes = realizes;
+    // Depends on: sibling capabilities this spec builds on (0.11.0 field
+    // review — specs cited each other only in prose, unreadable by machine).
+    // Stored as a capability-id list so `why` can show the graph, `context`
+    // can pull dependencies into the read pack, and `review` can flag
+    // dependents of a touched capability.
+    const depends = specHeader(text, "Depends on") !== null ? parseDependsOn(text) : prev?.depends_on;
+    if (depends && depends.length) entry.depends_on = depends;
     out.artifacts.specs.push(entry);
   }
 

package/templates/AGENTS.md.template

@@ -42,17 +42,21 @@ so prefer it over writing artifacts by hand. Full list: `doctrina --help`.
   existing code) · `--chore` (no-spec infra/docs/build)
 - **Scaffold (manual creation stays available):** `doctrina spec new <cap>`
   (`--bug`) · `doctrina decision new "<title>"` · `doctrina change new <id>`
-  · `doctrina contract new <id>` · `doctrina skill new <slug>`
+  · `doctrina contract new <id>` · `doctrina skill new <slug>` · `doctrina
+  intent add "<text>"` (new product anchor post-intake)
 - **Advance / close:** `doctrina change apply|archive|diff <id>` · `doctrina
   decision accept|land|supersede <n>` · `doctrina spec set <cap> [...]` ·
-  `doctrina close <id>` (whole close in one pass)
+  `doctrina close <id>` (whole close in one pass, coverage scoped to the
+  change)
 - **Gates (ground truth, not guesses):** `doctrina validate` (`--fix`) ·
   `doctrina verify` · `doctrina review` (conformance vs specs/ADRs) ·
-  `doctrina coverage --strict` · `doctrina trace --strict` · `doctrina
-  contract check` · `doctrina clarify --all` · `doctrina analyze <id>`
+  `doctrina coverage --strict` (`--run` executes cited proof) ·
+  `doctrina trace --strict` · `doctrina contract check` ·
+  `doctrina clarify --all` · `doctrina analyze <id>`
 
 Continuous: `doctrina watch` re-syncs and re-orients on every save.
 Capture lessons: `doctrina skill suggest` surfaces skills worth writing.
+After a CLI update: `doctrina upgrade --write` brings this project up.
 
 ## Stack and tooling
 

package/templates/README.md

@@ -21,6 +21,9 @@ replace. No conditionals, loops, or includes.
 | `{{DECISION_NUMBER}}` | Zero-padded ADR number (e.g. `0007`) | next available |
 | `{{DECISION_TITLE}}` | ADR title | required, no default |
 | `{{DECISION_SLUG}}` | kebab-case slug derived from `{{DECISION_TITLE}}` | derived |
+| `{{SKILL_NAME}}` | Slug for a new on-demand skill | required, no default |
+| `{{CONTRACT_NAME}}` | Slug for a new integration contract | required, no default |
+| `{{FRAMEWORK_VERSION}}` | Version of the CLI that scaffolded/stamped the tree | running CLI version |
 | `{{AGENTS_MD_PATH}}` | Path to root `AGENTS.md` from the adapter location | per adapter |
 
 CLI authors and template authors share this vocabulary. Adding a token
@@ -49,13 +52,16 @@ change/
   design.md.template
   spec-delta.md.template
 decision.md.template                       one ADR (Nygard/MADR)
+contract.md.template                       one integration contract (ports/env/interfaces)
 hooks/
   pre-commit.sample                        installed by `doctrina hooks install`
   watch.sample                             on-save validation wrapper (manual wiring)
 adapters/
   claude/CLAUDE.md.template
+  claude/.claude/commands/doctrina-*.md.template   native slash commands (core loop)
   codex/README.md
   cursor/.cursor/rules/00-doctrina.mdc.template
+  cursor/.cursor/commands/doctrina-*.md.template   native slash commands (core loop)
   copilot/.github/copilot-instructions.md.template
   gemini/GEMINI.md.template
   aider/CONVENTIONS.md.template
@@ -76,7 +82,7 @@ adapters/
 | `cursor` | `.cursor/rules/00-doctrina.mdc` with `alwaysApply: true` | Cursor's `.mdc` rules live in a dedicated directory; the file is a thin pointer. |
 | `copilot` | `.github/copilot-instructions.md` | GitHub Copilot's repository-level custom instructions path. |
 | `gemini` | `GEMINI.md` at project root | Gemini CLI's native context file. |
-| `aider` | `CONVENTIONS.md` at project root | Aider reads CONVENTIONS.md as cached read-only context. |
+| `aider` | `CONVENTIONS.md` at project root | Read-only context once wired in (`aider --read CONVENTIONS.md`, or `read:` in `.aider.conf.yml`). |
 | `windsurf` | `.windsurfrules` at project root | Windsurf's rules file convention. |
 | `continue` | `.continue/rules/00-doctrina.md` | Continue.dev's rules directory. |
 | `amp` / `devin` / `factory` / `jules` | nothing | AGENTS.md-native (same posture as `codex`); the directory marks the support contract and gives future per-agent affordances a home. |

package/templates/adapters/aider/CONVENTIONS.md.template

@@ -1,8 +1,9 @@
 # CONVENTIONS.md — {{PROJECT_NAME}}
 
-Aider reads this file as read-only context (CONVENTIONS.md is
-loaded automatically and cached). This project routes all
-operational rules through the open AGENTS.md standard.
+Aider reads this file as read-only context once wired in: launch
+with `aider --read CONVENTIONS.md`, or add `read: CONVENTIONS.md`
+to `.aider.conf.yml` so it loads on every run. This project routes
+all operational rules through the open AGENTS.md standard.
 
 See `{{AGENTS_MD_PATH}}` for the canonical operational source of
 truth. The Doctrina framework artifacts (specs, decisions,

package/templates/spec.md.template

@@ -24,7 +24,15 @@ ADR 0006). Tag product.md success-criteria bullets with an anchor —
 "- [SC1] ..." — and list the ones this spec delivers above. An "active"
 spec with no Realizes: header warns under `doctrina validate`; if the
 capability genuinely maps to no product anchor (internal tooling), keep
-the header and write "n/a — <why>" to record that on purpose.
+the header and write "n/a — <why>" to record that on purpose. Need a NEW
+anchor for intent born after the intake? `doctrina intent add "<text>"`.
+
+Optional: declare the sibling capabilities this spec builds on with a
+machine-readable header — "**Depends on:** defects, decisions". It feeds
+`doctrina why` (the dependency graph), `doctrina context <cap>` (the
+dependencies join the read pack), and `doctrina review` (dependents of a
+touched capability are flagged). Citing them only in prose keeps every
+tool blind to the link.
 -->
 
 ## Purpose