doctrina-cli 0.10.0 → 0.11.0

package/src/commands/status.js

@@ -7,6 +7,7 @@ import { deriveIndex, indexesMatch, specHeader, listHeader } from "../lib/scan.j
 import { cliVersion } from "../lib/version.js";
 import { summarize as coverageSummary } from "./coverage.js";
 import { summarize as traceSummary } from "./trace.js";
+import { flagBool } from "../lib/args.js";
 import { c } from "../lib/colors.js";
 
 // One-glance project health (review 2026-06-27 passive-user feature #1): a
@@ -19,53 +20,47 @@ import { c } from "../lib/colors.js";
 
 const CONFIG_REL = ".doctrina/verify.json";
 
-export async function run(_positional, _flags) {
+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.");
   }
 
-  let index = null;
-  try {
-    index = idx.load(projectRoot);
-  } catch {
-    index = null;
+  const s = collectStatus(projectRoot);
+
+  if (flagBool(flags, "json", false)) {
+    console.log(JSON.stringify(s, null, 2));
+    return 0;
   }
 
-  const project = index?.project ?? path.basename(projectRoot);
-  const stamp = index?.framework_version ?? "—";
-  const cli = cliVersion();
-  console.log(c.bold("Doctrina status") + c.gray(` — ${project}  (framework ${stamp} / CLI ${cli})`));
+  console.log(c.bold("Doctrina status") + c.gray(` — ${s.project}  (framework ${s.stamp ?? "—"} / CLI ${s.cli})`));
   console.log("");
 
   // --- Gates ---
   console.log(c.bold("  Gates"));
-  // Index drift (the silent rot validate now errors on).
   let driftLine;
-  if (!index) {
+  if (s.indexState === "missing") {
     driftLine = c.red("missing/unreadable") + c.gray(" — run `doctrina index rebuild`");
-  } else if (indexesMatch(deriveIndex(projectRoot, index), index)) {
+  } else if (s.indexState === "in-sync") {
     driftLine = c.green("in sync");
   } else {
     driftLine = c.yellow("drifted") + c.gray(" — run `doctrina validate --fix`");
   }
   console.log(`    ${"index".padEnd(11)} ${driftLine}`);
 
-  // Framework stamp divergence.
-  const stampLine = stamp === cli
+  const stampLine = s.stamp === s.cli
     ? c.green("current")
-    : c.yellow(`${stamp} (CLI ${cli})`) + c.gray(" — `doctrina index rebuild`");
+    : c.yellow(`${s.stamp ?? "—"} (CLI ${s.cli})`) + c.gray(" — `doctrina index rebuild`");
   console.log(`    ${"stamp".padEnd(11)} ${stampLine}`);
 
-  // Coverage and trace ratios.
-  const cov = coverageSummary(projectRoot);
+  const cov = s.coverage;
   const covExtra = cov.totalDangling + cov.totalConditional > 0
     ? c.yellow(` ${cov.totalDangling} dangling, ${cov.totalConditional} conditional`)
     : "";
   const covColor = cov.pct === 100 ? c.green : cov.pct >= 50 ? c.yellow : c.red;
   console.log(`    ${"coverage".padEnd(11)} ${covColor(`${cov.pct}%`)} ${c.gray(`(${cov.totalCovered}/${cov.totalCriteria} criteria)`)}${covExtra}`);
 
-  const tr = traceSummary(projectRoot);
+  const tr = s.trace;
   const trExtra = tr.untraceable + tr.dropped + tr.dangling > 0
     ? c.yellow(` ${tr.dropped} dropped, ${tr.untraceable} untraceable`)
     : "";
@@ -73,40 +68,72 @@ export async function run(_positional, _flags) {
   const trText = tr.anchors === 0 ? "no anchors" : `${tr.realized}/${tr.anchors} anchors`;
   console.log(`    ${"trace".padEnd(11)} ${trColor(trText)}${trExtra}`);
 
-  // Verify config presence (running it is the slow, authoritative gate).
-  const verifyCfg = path.join(projectRoot, CONFIG_REL);
   let verifyLine = c.gray("not configured") + c.gray(" — `doctrina verify --init`");
-  if (isFile(verifyCfg)) {
-    try {
-      const cfg = JSON.parse(read(verifyCfg));
-      const n = Array.isArray(cfg?.checks) ? cfg.checks.length : 0;
-      verifyLine = c.cyan(`${n} check${n === 1 ? "" : "s"}`) + c.gray(" — run `doctrina verify`");
-    } catch {
-      verifyLine = c.red("invalid JSON");
-    }
+  if (s.verify.invalid) {
+    verifyLine = c.red("invalid JSON");
+  } else if (s.verify.configured) {
+    const n = s.verify.checks;
+    verifyLine = c.cyan(`${n} check${n === 1 ? "" : "s"}`) + c.gray(" — run `doctrina verify`");
   }
   console.log(`    ${"verify".padEnd(11)} ${verifyLine}`);
 
   // --- Work ---
   console.log("");
   console.log(c.bold("  Work"));
-  const specs = countSpecs(projectRoot);
-  const implBreak = Object.entries(specs.impl).map(([k, v]) => `${v} ${k}`).join(", ");
-  console.log(`    ${"specs".padEnd(11)} ${specs.total}${implBreak ? c.gray(`  (${implBreak})`) : ""}`);
-  console.log(`    ${"changes".padEnd(11)} ${specs.openChanges} open`);
-  const adr = countDecisions(projectRoot);
+  const implBreak = Object.entries(s.specs.impl).map(([k, v]) => `${v} ${k}`).join(", ");
+  console.log(`    ${"specs".padEnd(11)} ${s.specs.total}${implBreak ? c.gray(`  (${implBreak})`) : ""}`);
+  console.log(`    ${"changes".padEnd(11)} ${s.specs.openChanges} open`);
   const adrNotes = [];
-  if (adr.proposed > 0) adrNotes.push(c.yellow(`${adr.proposed} proposed`));
-  if (adr.bare > 0) adrNotes.push(c.yellow(`${adr.bare} unproven`));
-  console.log(`    ${"decisions".padEnd(11)} ${adr.total}${adrNotes.length ? c.gray("  (") + adrNotes.join(c.gray(", ")) + c.gray(")") : ""}`);
-  const skills = countSkills(projectRoot);
-  console.log(`    ${"skills".padEnd(11)} ${skills}`);
+  if (s.decisions.proposed > 0) adrNotes.push(c.yellow(`${s.decisions.proposed} proposed`));
+  if (s.decisions.bare > 0) adrNotes.push(c.yellow(`${s.decisions.bare} unproven`));
+  console.log(`    ${"decisions".padEnd(11)} ${s.decisions.total}${adrNotes.length ? c.gray("  (") + adrNotes.join(c.gray(", ")) + c.gray(")") : ""}`);
+  console.log(`    ${"skills".padEnd(11)} ${s.skills}`);
 
   console.log("");
   console.log(c.gray("  Full gates: `doctrina validate` · `doctrina verify`.  Next step: `doctrina next`."));
   return 0;
 }
 
+// Pure, render-free status snapshot — the data behind the dashboard, shared
+// with `prime`, `handoff`, `doctor`, and the `--json` output so every consumer
+// reads the same numbers.
+export function collectStatus(projectRoot) {
+  let index = null;
+  try {
+    index = idx.load(projectRoot);
+  } catch {
+    index = null;
+  }
+  let indexState = "missing";
+  if (index) {
+    indexState = indexesMatch(deriveIndex(projectRoot, index), index) ? "in-sync" : "drifted";
+  }
+
+  const verifyCfg = path.join(projectRoot, CONFIG_REL);
+  let verify = { configured: false, checks: 0, invalid: false };
+  if (isFile(verifyCfg)) {
+    try {
+      const cfg = JSON.parse(read(verifyCfg));
+      verify = { configured: true, checks: Array.isArray(cfg?.checks) ? cfg.checks.length : 0, invalid: false };
+    } catch {
+      verify = { configured: true, checks: 0, invalid: true };
+    }
+  }
+
+  return {
+    project: index?.project ?? path.basename(projectRoot),
+    stamp: index?.framework_version ?? null,
+    cli: cliVersion(),
+    indexState,
+    coverage: coverageSummary(projectRoot),
+    trace: traceSummary(projectRoot),
+    verify,
+    specs: countSpecs(projectRoot),
+    decisions: countDecisions(projectRoot),
+    skills: countSkills(projectRoot),
+  };
+}
+
 function countSpecs(projectRoot) {
   const specsDir = path.join(projectRoot, ".doctrina", "specs");
   const impl = {};
@@ -165,13 +192,16 @@ function countSkills(projectRoot) {
 }
 
 export const help = `
-Usage: doctrina status
+Usage: doctrina status [--json]
 
 Print a one-glance health dashboard for the .doctrina/ project: the gate
 signals (index drift, framework stamp, coverage %, trace anchors, whether
 verify is configured) and the artifact counts (specs by implementation
 state, open changes, decisions, skills). Read-only; always exits 0.
 
+Flags:
+  --json   Emit the snapshot as JSON (stable shape for agents and CI).
+
 It is a fast summary, not the authoritative gate: run \`doctrina validate\`
 and \`doctrina verify\` for the full structural and build checks, and
 \`doctrina next\` for the recommended next action.

package/src/commands/trace.js

@@ -32,6 +32,7 @@ export async function run(_positional, flags) {
     throw new Error("not a Doctrina project (no .doctrina/ in cwd). Run `doctrina init` first.");
   }
   const strict = flagBool(flags, "strict", false);
+  const json = flagBool(flags, "json", false);
 
   const anchors = collectAnchors(projectRoot); // [{ id }], in document order
   const specs = collectSpecs(projectRoot); // [{ cap, status, realizes: [id] }]
@@ -41,6 +42,10 @@ export async function run(_positional, flags) {
 
   // The feature is unused: do not nag a project that never opted in.
   if (anchors.length === 0 && !anyRealizes) {
+    if (json) {
+      console.log(JSON.stringify({ anchors: [], dangling: [], untraceable: [], summary: summarize(projectRoot) }, null, 2));
+      return 0;
+    }
     console.log(
       c.gray(
         "no intent-provenance markers found — tag product.md bullets with `[SC1]` " +
@@ -69,6 +74,13 @@ export async function run(_positional, flags) {
     .filter((s) => s.realizes === null && s.status === "active")
     .map((s) => s.cap);
 
+  if (json) {
+    const rows = anchors.map((a) => ({ id: a.id, realizedBy: (realizedBy.get(a.id) ?? []).sort() }));
+    const clean = rows.every((r) => r.realizedBy.length > 0) && dangling.length === 0 && untraceable.length === 0;
+    console.log(JSON.stringify({ anchors: rows, dangling, untraceable, summary: summarize(projectRoot) }, null, 2));
+    return clean ? 0 : strict ? 1 : 0;
+  }
+
   console.log(c.bold("Trace") + c.gray(" — product intent → capability provenance:"));
   console.log("");
 
@@ -183,6 +195,7 @@ trace reports three provenance breaks:
   untraceable spec   an active spec with no Realizes: header
 
 Read-only. Exits 0 as a report; with --strict, exits 1 when any break
-exists (CI gate). It checks that the link exists and is complete — not
-that a criterion is faithful to the intent (that stays a human/LLM call).
+exists (CI gate). --json emits anchors/dangling/untraceable + summary
+as JSON. It checks that the link exists and is complete — not that a
+criterion is faithful to the intent (that stays a human/LLM call).
 `;

package/src/commands/validate.js

@@ -499,7 +499,35 @@ export async function run(_positional, flags) {
     }
   }
 
+  // 16. Bilingual docs parity. Projects that keep an EN-source docs tree
+  //     with a PT mirror (docs/en + docs/pt) get filename-parity checking:
+  //     a file added in one language and missing in the other is invisible
+  //     to every other gate, and the mirror silently falls behind. Only the
+  //     deterministic half (file sets) is checked — content staleness stays
+  //     a human judgement. Projects without both trees never see this.
+  const docsEn = path.join(projectRoot, "docs", "en");
+  const docsPt = path.join(projectRoot, "docs", "pt");
+  if (isDir(docsEn) && isDir(docsPt)) {
+    const mdSet = (dir) => new Set(readdirSync(dir).filter((f) => f.endsWith(".md")));
+    const enSet = mdSet(docsEn);
+    const ptSet = mdSet(docsPt);
+    for (const f of [...enSet].sort()) {
+      if (!ptSet.has(f)) {
+        warnings.push(`docs/en/${f} has no docs/pt/${f} counterpart (EN is the source; the PT mirror fell behind)`);
+      }
+    }
+    for (const f of [...ptSet].sort()) {
+      if (!enSet.has(f)) {
+        warnings.push(`docs/pt/${f} has no docs/en/${f} counterpart (PT translates an EN source, never leads it)`);
+      }
+    }
+  }
+
   // Output
+  if (flagBool(flags, "json", false)) {
+    console.log(JSON.stringify({ ok: errors.length === 0, errors, warnings }, null, 2));
+    return errors.length === 0 ? 0 : 1;
+  }
   for (const w of warnings) console.log(c.yellow("warn:  ") + w);
   for (const e of errors) console.log(c.red("error: ") + e);
 
@@ -613,9 +641,13 @@ function isLikelyPath(s) {
 }
 
 export const help = `
-Usage: doctrina validate
+Usage: doctrina validate [--fix] [--json]
 
 Run schema, artifact-existence, and structural checks against the
 .doctrina/ tree in the current working directory. Exits 0 if no errors
 (warnings allowed), 1 otherwise.
+
+Flags:
+  --fix    Rebuild index.json from the tree before checking (heals drift).
+  --json   Emit { ok, errors, warnings } as JSON (stable shape for agents/CI).
 `;

package/src/commands/why.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}"`);
@@ -130,6 +137,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 +261,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/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,26 @@ 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";
 
 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,
 };
 
 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)
@@ -92,7 +61,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", "strict", "list", "init", "fix", "once", "clean"],
+    boolean: ["help", "h", "version", "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")) {

package/src/lib/commands.js

@@ -15,13 +15,82 @@ export const COMMAND_NAMES = [
   // authoring
   "spec", "change", "contract", "decision", "skill",
   // 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",
 ];
 
+// 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)"],
+  ["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)"],
+];
+
+// 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/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,