doctrina-cli 0.9.0 → 0.11.0

package/src/commands/why.js

@@ -3,6 +3,8 @@ 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 { parseAcceptanceCriteria, isVerified } from "../lib/criteria.js";
+import * as idx from "../lib/index-json.js";
 import { c } from "../lib/colors.js";
 import { suggest } from "../lib/suggest.js";
 
@@ -24,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}"`);
@@ -66,16 +75,35 @@ export async function run(positional, _flags) {
   const purpose = sectionParagraph(text, "Purpose");
   if (purpose) console.log("    " + purpose.replace(/\s+/g, " ").trim());
 
-  // 3. The proof (acceptance criteria with cited evidence).
+  // 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
+  //    no longer mis-reported as "no evidence cited". The mark distinguishes
+  //    the three honest states, including the one that used to read as a false
+  //    green: a [verified] claim that cites nothing.
   console.log("");
   console.log(c.bold("  Proof"));
-  const criteria = acceptanceWithEvidence(text);
+  const criteria = parseAcceptanceCriteria(text);
   if (criteria.length === 0) {
     console.log(`    ${c.gray("no acceptance criteria declared")}`);
   } else {
     for (const cr of criteria) {
-      const proof = cr.proof.length ? c.gray(cr.proof.map((p) => `\`${p}\``).join(", ")) : c.yellow("no evidence cited");
-      console.log(`    ${cr.mark} #${cr.n}  ${proof}`);
+      const paths = cr.proofPaths.map((p) => `\`${p}\``).join(", ");
+      let mark, note;
+      if (isVerified(cr) && cr.proofPaths.length > 0) {
+        mark = c.green("✓");
+        note = c.gray(paths);
+      } else if (isVerified(cr)) {
+        mark = c.yellow("~");
+        note = c.yellow("marked verified but cites no proof");
+      } else if (cr.marker !== null) {
+        mark = c.yellow("○");
+        note = cr.proofPaths.length ? c.gray(paths) : c.gray(`[${cr.marker}]`);
+      } else {
+        mark = c.gray("·");
+        note = cr.proofPaths.length ? c.gray(paths) : c.yellow("no evidence cited");
+      }
+      console.log(`    ${mark} #${cr.n}  ${note}`);
     }
   }
 
@@ -89,9 +117,96 @@ export async function run(positional, _flags) {
     for (const a of adrs) console.log(`    ${c.cyan("ADR " + a.id)}  ${a.title}`);
   }
 
+  // 5. History — the archived changes that built this capability. The default
+  //    context pack excludes changes/archive/ by design, so "what shaped this
+  //    spec?" otherwise loses the change trail. The index ledger already
+  //    records each archived change's affected capabilities (specs_affected);
+  //    surface them here so the provenance chain reaches back to the work that
+  //    delivered the spec, not only the intent and decisions in front of it.
+  console.log("");
+  console.log(c.bold("  History"));
+  const history = archivedChangesFor(projectRoot, cap);
+  if (history.length === 0) {
+    console.log(`    ${c.gray("no archived change recorded against this capability")}`);
+  } else {
+    for (const ch of history) {
+      console.log(`    ${c.cyan(ch.applied ?? "—")}  ${ch.title} ${c.gray(`(${ch.op})`)}`);
+    }
+  }
+
   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.
+function archivedChangesFor(projectRoot, cap) {
+  let index;
+  try {
+    index = idx.load(projectRoot);
+  } catch {
+    return [];
+  }
+  const out = [];
+  for (const ch of index.artifacts?.changes_archive ?? []) {
+    const hit = (ch.specs_affected ?? []).find((s) => s.capability === cap);
+    if (hit) out.push({ applied: ch.applied, title: ch.title, op: hit.operation ?? "MODIFIED" });
+  }
+  return out.sort((a, b) => String(a.applied ?? "").localeCompare(String(b.applied ?? "")));
+}
+
 // Map of anchor id -> the product.md bullet text that declares it.
 function productAnchors(projectRoot) {
   const out = new Map();
@@ -126,30 +241,6 @@ function sectionParagraph(text, name) {
   return buf.join(" ");
 }
 
-// Numbered acceptance criteria with their [mark] and any backtick proof paths.
-function acceptanceWithEvidence(text) {
-  const lines = text.split(/\r?\n/);
-  let inSection = false;
-  const out = [];
-  for (const line of lines) {
-    if (/^##\s+/.test(line)) {
-      inSection = /^##\s+Acceptance criteria\b/i.test(line);
-      continue;
-    }
-    if (!inSection) continue;
-    const m = line.match(/^\s*(\d+)\.\s+(.*)$/);
-    if (!m) continue;
-    const body = m[2];
-    const markMatch = body.match(/^\[([^\]]+)\]/);
-    const mark = markMatch
-      ? (/^verified/i.test(markMatch[1]) ? c.green("✓") : c.yellow("○"))
-      : c.gray("·");
-    const proof = [...body.matchAll(/`([^`]+)`/g)].map((x) => x[1]).filter((s) => s.includes("/") || /\.[a-z0-9]{1,8}$/i.test(s));
-    out.push({ n: m[1], mark, proof });
-  }
-  return out;
-}
-
 // Accepted ADRs whose body names the capability (word-ish boundary).
 function decisionsMentioning(projectRoot, cap) {
   const adrDir = path.join(projectRoot, ".doctrina", "decisions");
@@ -170,13 +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), and the accepted ADRs that name it. 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";
@@ -31,57 +32,27 @@ import * as close from "./commands/close.js";
 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,
+  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)
-  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)
@@ -90,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

@@ -0,0 +1,115 @@
+// Single canonical list of top-level `doctrina` commands.
+//
+// This is the one place the command surface is named. `src/index.js` builds
+// its dispatch table for these names (an execution-based test asserts every
+// name here resolves to a real handler, so the two never drift), and
+// `doctrina validate` compares it against the commands AGENTS.md documents —
+// the hub the agent reads first — so a stale command catalog or a reference
+// to a command that no longer exists becomes a loud signal instead of silent
+// rot (the "AGENTS.md is the source of truth but nothing keeps it fresh" gap).
+//
+// Keep this sorted by the workflow order used in `--help`, not alphabetically.
+export const COMMAND_NAMES = [
+  // bootstrap / day-to-day
+  "init", "intake", "work",
+  // authoring
+  "spec", "change", "contract", "decision", "skill",
+  // read / orient
+  "prime", "context", "show", "search", "status", "next", "why", "handoff", "constitution",
+  // gates
+  "analyze", "clarify", "validate", "coverage", "trace", "review", "verify", "close", "doctor",
+  // maintenance
+  "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
+// "the doctrina framework", which is not a command reference. Both the bare
+// `doctrina <cmd>` and the `npx doctrina-cli <cmd>` forms are recognised.
+export function referencedCommands(markdown) {
+  const out = new Set();
+  const chunks = [];
+  // Pull fenced blocks first and strip them out, so the inline-span scan below
+  // cannot mis-pair backticks across a fence boundary (a fence's own backticks
+  // would otherwise shift which inline spans pair up).
+  const rest = markdown.replace(/```[\s\S]*?```/g, (block) => {
+    chunks.push(block);
+    return "\n";
+  });
+  for (const m of rest.matchAll(/`[^`]+`/g)) chunks.push(m[0]);
+  const hay = chunks.join("\n");
+  for (const m of hay.matchAll(/(?:npx\s+doctrina-cli|doctrina)\s+([a-z][a-z-]+)/g)) {
+    out.add(m[1]);
+  }
+  return out;
+}

package/src/lib/criteria.js

@@ -0,0 +1,76 @@
+// Shared parser for the "## Acceptance criteria" section of a spec.
+//
+// A criterion is a numbered item that MAY span several lines (continuation
+// prose), and its evidence is cited as a backtick path span on ANY of those
+// lines. A single-line parser silently misses proof sitting on a continuation
+// line — the bug that made `doctrina why` print "no evidence cited" for a
+// criterion `doctrina coverage` counted as covered. Both commands (and the
+// validate honest-gate) read criteria through this one parser so they can
+// never disagree about what a criterion cites.
+//
+// Returns one row per criterion: { n, marker, body, proofPaths } where marker
+// is the lowercased `[tag]` (e.g. "verified", "unverified") or null, and
+// proofPaths is the de-duplicated list of file-path-looking backtick tokens.
+
+export function parseAcceptanceCriteria(text) {
+  const lines = text.split(/\r?\n/);
+  let inSection = false;
+  const rows = [];
+  let cur = null;
+  const flush = () => {
+    if (cur) {
+      cur.proofPaths = backtickPaths(cur.body);
+      rows.push(cur);
+    }
+    cur = null;
+  };
+  for (const line of lines) {
+    if (/^##\s+/.test(line)) {
+      if (inSection) {
+        flush();
+        inSection = false;
+      }
+      if (/^##\s+Acceptance criteria\b/i.test(line)) inSection = true;
+      continue;
+    }
+    if (!inSection) continue;
+    const m = line.match(/^\s*(\d+)\.\s+(.*)$/);
+    if (m) {
+      flush();
+      const body = m[2];
+      const markMatch = body.match(/^\[([^\]]+)\]/);
+      cur = { n: Number(m[1]), marker: markMatch ? markMatch[1].toLowerCase() : null, body };
+    } else if (cur) {
+      cur.body += (line.trim() === "" ? " " : " " + line.trim());
+    }
+  }
+  flush();
+  return rows.filter((r) => r.body.trim().length > 0);
+}
+
+// True when a criterion asserts it has been verified (the `[verified...]` tag).
+export function isVerified(row) {
+  return row.marker !== null && /^verified/.test(row.marker);
+}
+
+function backtickPaths(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];
+}
+
+// Mirrors the coverage heuristic so the two commands agree: a token is a path
+// if it has a slash or a file extension and is not a URL/placeholder.
+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;
+}

package/src/lib/index-json.js

@@ -39,6 +39,7 @@ export function blank(projectName, date) {
     framework_version: cliVersion(),
     last_updated: date,
     artifacts: {
+      entrypoint: { path: "AGENTS.md" },
       product: {
         path: ".doctrina/product.md",
         status: "active",

package/src/lib/scan.js

@@ -192,6 +192,13 @@ export function deriveIndex(projectRoot, current) {
     });
   }
 
+  // Entrypoint — the root AGENTS.md the agent reads first (the hub the
+  // AGENTS.md-drift gate in `validate` keeps honest). Registering it closes
+  // the machine-readable graph in both directions: a tool that enumerates
+  // index.json finds the hub itself, not only the artifacts the hub points at.
+  // Path-only, so the field never churns the index.
+  out.artifacts.entrypoint = { path: "AGENTS.md" };
+
   return out;
 }
 

package/templates/AGENTS.md.template

@@ -35,8 +35,9 @@ so prefer it over writing artifacts by hand. Full list: `doctrina --help`.
 
 - **Read / orient (any task, first & last):** `doctrina status` (health) ·
   `doctrina context [<cap>] --concat` (read pack) · `doctrina next` (what's
-  next) · `doctrina why <cap>` (provenance) · `doctrina spec list` ·
-  `doctrina decision list` · `doctrina search <query>`
+  next) · `doctrina why <cap>` (provenance) · `doctrina constitution`
+  (standing rules) · `doctrina spec list` · `doctrina decision list` ·
+  `doctrina search <query>`
 - **Start:** `doctrina work "<prompt>"` · `--from-diff` (backfill from
   existing code) · `--chore` (no-spec infra/docs/build)
 - **Scaffold (manual creation stays available):** `doctrina spec new <cap>`

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/adapters/claude/.claude/commands/doctrina-context.md.template

@@ -0,0 +1,13 @@
+---
+description: Load the Doctrina read pack for a task, in read order
+argument-hint: [capability]
+---
+
+Assemble the context for **{{PROJECT_NAME}}** before doing any work.
+
+Run `doctrina context $ARGUMENTS --concat` and read the output top to bottom:
+AGENTS.md → product.md → the capability spec(s) → open changes → accepted ADRs.
+With no capability it includes every active spec. It excludes the change
+archive by design — run `doctrina why <capability>` when you need history.
+
+Do this for ANY task (review, debug, a question), not only new work.

package/templates/adapters/claude/.claude/commands/doctrina-next.md.template

@@ -0,0 +1,13 @@
+---
+description: Show and act on the next recommended Doctrina workflow step
+---
+
+Decide the next step for **{{PROJECT_NAME}}** from the framework's own signals.
+
+1. Run `doctrina next` and `doctrina status` to see open work and gate health.
+2. Do the single highest-priority action it names (resume a change, apply a
+   delta, archive, accept an ADR, fix index drift, …).
+3. Re-run `doctrina next` to confirm the item cleared.
+
+Use the read-only commands first; never guess what is pending — let the CLI
+report it.

package/templates/adapters/claude/.claude/commands/doctrina-status.md.template

@@ -0,0 +1,12 @@
+---
+description: One-glance Doctrina project health and gate status
+---
+
+Report the health of **{{PROJECT_NAME}}**.
+
+Run `doctrina status` for the dashboard (index drift, framework stamp,
+coverage %, trace anchors, verify config, artifact counts). For the
+authoritative gates run `doctrina validate` and `doctrina verify`, and
+`doctrina next` for the recommended action.
+
+Summarise what is green, what is not, and the single next step.

package/templates/adapters/claude/.claude/commands/doctrina-why.md.template

@@ -0,0 +1,12 @@
+---
+description: Explain a capability's provenance (intent → proof → ADRs → history)
+argument-hint: <capability>
+---
+
+Explain why a capability of **{{PROJECT_NAME}}** exists and is shaped as it is.
+
+Run `doctrina why $ARGUMENTS` and relay the provenance chain it prints: the
+product intent it Realizes, its purpose and status, the acceptance criteria
+that prove it (with cited evidence), the accepted ADRs that decided it, and
+the archived changes that built it. Read-only — answer from the artifacts,
+don't grep the tree by hand.