doctrina-cli 0.8.0 → 0.10.0

package/README.md

@@ -3,7 +3,7 @@
 > CLI for the Doctrina framework. The package is published as
 > `doctrina-cli`; the executable it installs is `doctrina`.
 
-**Status:** v0.6.0 — current release. Zero runtime dependencies
+**Status:** v0.10.0 — current release. Zero runtime dependencies
 (Node.js standard library only).
 
 ## Install

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "doctrina-cli",
-  "version": "0.8.0",
+  "version": "0.10.0",
   "description": "Doctrina CLI — spec-driven, AGENTS.md-native framework for multi-agent AI development.",
   "license": "MIT",
   "keywords": [

package/src/commands/constitution.js

@@ -0,0 +1,136 @@
+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 { listHeader } from "../lib/scan.js";
+import { c } from "../lib/colors.js";
+
+// The project's standing rules in one read — Spec Kit parity for its
+// `constitution.md`, but ASSEMBLED, not a new home for facts. Doctrina's
+// constitution is its accepted ADRs (the immutable decisions that govern how
+// the codebase evolves) plus the product's declared non-goals. Both already
+// own those facts elsewhere; this is a read-only digest that gathers them so a
+// human or agent (especially one migrating from Spec Kit, which expects a
+// single constitution) can see "the rules" without reading the whole tree.
+//
+// To change a principle, supersede its ADR; to change a non-goal, edit
+// product.md. The command never writes — it has nothing of its own to own.
+
+export async function run(_positional, _flags) {
+  const projectRoot = process.cwd();
+  if (!exists(path.join(projectRoot, ".doctrina"))) {
+    throw new Error("not a Doctrina project (no .doctrina/ in cwd). Run `doctrina init` first.");
+  }
+
+  const project = projectName(projectRoot);
+  console.log(
+    c.bold("Doctrina constitution") +
+      c.gray(` — ${project}  (standing rules: accepted decisions + non-goals)`),
+  );
+
+  // Principles — the accepted ADRs, by number. Every accepted decision is a
+  // binding rule; superseded/withdrawn/proposed ADRs are not yet (or no longer)
+  // in force and stay out.
+  console.log("");
+  console.log(c.bold("  Principles") + c.gray("  (immutable — supersede an ADR to change one)"));
+  const adrs = acceptedDecisions(projectRoot);
+  if (adrs.length === 0) {
+    console.log(`    ${c.gray("no accepted ADRs yet — record decisions with `doctrina decision new`")}`);
+  } else {
+    for (const a of adrs) console.log(`    ${c.cyan("ADR " + a.id)}  ${a.title}`);
+  }
+
+  // Non-goals — the explicit "what this project will not be", from product.md.
+  console.log("");
+  console.log(c.bold("  Non-goals") + c.gray("  (.doctrina/product.md)"));
+  const nonGoals = productSection(projectRoot, "Non-goals");
+  if (nonGoals.length === 0) {
+    console.log(`    ${c.gray("none declared — add a `## Non-goals` section to product.md")}`);
+  } else {
+    for (const g of nonGoals) console.log(`    ${c.gray("•")} ${g}`);
+  }
+
+  console.log("");
+  console.log(
+    c.gray(
+      `  ${adrs.length} accepted decision${adrs.length === 1 ? "" : "s"} · ` +
+        `${nonGoals.length} non-goal${nonGoals.length === 1 ? "" : "s"} · read-only`,
+    ),
+  );
+  return 0;
+}
+
+function projectName(projectRoot) {
+  try {
+    return JSON.parse(read(path.join(projectRoot, ".doctrina", "index.json"))).project
+      ?? path.basename(projectRoot);
+  } catch {
+    return path.basename(projectRoot);
+  }
+}
+
+// Accepted ADRs (NNNN-slug.md with Status: accepted), oldest first, with the
+// title read from the `# ADR NNNN — <title>` heading.
+function acceptedDecisions(projectRoot) {
+  const dir = path.join(projectRoot, ".doctrina", "decisions");
+  const out = [];
+  if (!isDir(dir)) return out;
+  for (const f of readdirSync(dir).sort()) {
+    const m = f.match(/^(\d{4})-.*\.md$/);
+    if (!m) continue;
+    const text = read(path.join(dir, f));
+    if ((listHeader(text, "Status") ?? "").toLowerCase() !== "accepted") continue;
+    const titleMatch = text.match(/^#\s+ADR\s+\d{4}\s*[—-]\s*(.+)$/m);
+    out.push({ id: m[1], title: titleMatch ? titleMatch[1].trim() : f });
+  }
+  return out;
+}
+
+// Bullets under a named `## <section>` of product.md, each accumulated across
+// its continuation lines so a wrapped bullet reads as one rule.
+function productSection(projectRoot, name) {
+  const p = path.join(projectRoot, ".doctrina", "product.md");
+  if (!isFile(p)) return [];
+  const lines = read(p).split(/\r?\n/);
+  let inSection = false;
+  const out = [];
+  let cur = null;
+  const flush = () => {
+    if (cur) out.push(cur.replace(/\s+/g, " ").trim());
+    cur = null;
+  };
+  for (const line of lines) {
+    if (/^##\s+/.test(line)) {
+      if (inSection) {
+        flush();
+        break;
+      }
+      if (new RegExp(`^##\\s+${name}\\b`, "i").test(line)) inSection = true;
+      continue;
+    }
+    if (!inSection) continue;
+    const m = line.match(/^\s*[-*]\s+(.+)$/);
+    if (m) {
+      flush();
+      cur = m[1];
+    } else if (cur && line.trim() !== "") {
+      cur += " " + line.trim();
+    } else if (line.trim() === "") {
+      flush();
+    }
+  }
+  flush();
+  return out;
+}
+
+export const help = `
+Usage: doctrina constitution
+
+Print the project's standing rules in one read: the accepted ADRs (the
+immutable decisions that govern how the codebase evolves) and the product's
+declared non-goals. Read-only — it assembles facts the ADRs and product.md
+already own; it never writes.
+
+This is the Spec Kit \`constitution.md\` analogue: a single place to see the
+non-negotiables. To change one, supersede the ADR or edit product.md.
+`;

package/src/commands/context.js

@@ -36,8 +36,14 @@ export async function run(positional, flags) {
   pushFile("AGENTS.md", "root rules");
   pushFile(".doctrina/product.md", "product truth");
 
-  // 3. The capability spec under work.
+  // 3. The capability spec(s) — the current truth. With a named capability,
+  //    just that one. Without one, EVERY active spec: the default orientation
+  //    read previously jumped from product.md straight to the ADRs, leaving
+  //    the single source of truth out of the pack entirely (a review/debug/
+  //    question read got history but not current truth). Specs come before
+  //    open changes and ADRs, matching the documented read order.
   let specMissing = false;
+  const specsRoot = path.join(projectRoot, ".doctrina", "specs");
   if (capability) {
     const specRel = `.doctrina/specs/${capability}/spec.md`;
     if (isFile(path.join(projectRoot, specRel))) {
@@ -45,6 +51,11 @@ export async function run(positional, flags) {
     } else {
       specMissing = true;
     }
+  } else if (isDir(specsRoot)) {
+    for (const cap of readdirSync(specsRoot).sort()) {
+      const specRel = `.doctrina/specs/${cap}/spec.md`;
+      if (isFile(path.join(projectRoot, specRel))) pushFile(specRel, `spec: ${cap}`);
+    }
   }
 
   // 4. Open changes (their proposal, tasks, and deltas).
@@ -117,9 +128,10 @@ export const help = `
 Usage: doctrina context [<capability>] [--concat]
 
 Print the exact context pack for a task, in the documented read
-order: AGENTS.md, product.md, the capability spec (when given), open
-changes, accepted ADRs. Skills are listed name + description only —
-they are on-demand by design. The change archive is excluded.
+order: AGENTS.md, product.md, the capability spec (when given —
+otherwise every active spec, so the current truth is never absent),
+open changes, accepted ADRs. Skills are listed name + description only
+— they are on-demand by design. The change archive is excluded.
 
 Flags:
   --concat   Print the file contents (with separators) instead of the

package/src/commands/skill.js

@@ -1,11 +1,12 @@
 import path from "node:path";
 import process from "node:process";
 import { readdirSync } from "node:fs";
+import { spawnSync } from "node:child_process";
 import { exists, isDir, isFile, mkdirp, read, relPath, walk, write } from "../lib/fs-ops.js";
 import { locateTemplatesDir, substitute } from "../lib/templates.js";
 import * as idx from "../lib/index-json.js";
 import { today } from "../lib/dates.js";
-import { flagBool } from "../lib/args.js";
+import { flagBool, flagString } from "../lib/args.js";
 import { c } from "../lib/colors.js";
 import { suggest } from "../lib/suggest.js";
 
@@ -30,57 +31,91 @@ export async function run(positional, flags) {
 // Surface (and optionally scaffold) skills worth capturing (review 2026-06-27
 // passive-user feature #6). A skill exists so a hard-won lesson is not relearned
 // by the next agent/session; the framework otherwise never pulls you toward
-// writing one. `skill suggest` scans the archived changes for fix-shaped work —
-// the textbook case for a skill — and lists candidates whose lesson is not yet
-// captured. With --write it scaffolds a stub per candidate, pre-seeded from the
-// change so the human/agent only fills the body. Deterministic pattern match on
-// the archived folder name — a hint, never a decision (ADR 0005).
+// writing one. `skill suggest` scans for fix-shaped work — the textbook case for
+// a skill — from two deterministic sources and lists candidates whose lesson is
+// not yet captured: archived change proposals, and the git commit history
+// (ADR 0013). The archive only fills if a team runs the `doctrina change`
+// lifecycle, so without the git source `suggest` is inert in most repos. With
+// --write it scaffolds a stub per candidate, pre-seeded from the source so the
+// human/agent only fills the body. Both sources are a pattern match — a hint,
+// never a decision (ADR 0005); skills are still authored, never generated.
 const FIX_SHAPED = /(?:^|-)(fix|bug|hotfix|patch|parse|parsing|tolerate|workaround|race|deadlock|flaky|retry|escape|sanitize|sanitise)(?:-|$)/;
 
+// The same idea applied to a commit subject. Narrower than FIX_SHAPED on
+// purpose: a deliberate folder slug tolerates more noise than a free-form
+// subject line. Matches conventional fix-type prefixes (fix:, fix(scope):,
+// bug:, hotfix:, patch:, and the free-form "Fix the…") plus the strongly
+// fix-flavoured debugging keywords — never feat:/refactor:/docs:/chore:.
+const FIX_SHAPED_SUBJECT =
+  /^(?:fix|bug|hotfix|patch)\b|\b(?:tolerate|workaround|deadlock|flaky|race condition|retry|sanitiz|sanitis)/i;
+
+// How far back the git source looks when --since is not given, and how many
+// candidates we print before collapsing the rest into a "+N more" line.
+const GIT_LOG_LIMIT = 200;
+const MAX_SHOWN = 20;
+
 function skillSuggest(args, flags) {
   const projectRoot = process.cwd();
   ensureDoctrinaProject(projectRoot);
   const doWrite = flagBool(flags, "write", false);
+  const since = flagString(flags, "since");
 
-  const archiveDir = path.join(projectRoot, ".doctrina", "changes", "archive");
   const skillsDir = path.join(projectRoot, ".doctrina", "skills");
   const existing = new Set(
     isDir(skillsDir) ? walk(skillsDir).filter((f) => f.endsWith(".md")).map((f) => path.basename(f, ".md")) : [],
   );
 
+  // Two deterministic sources, deduped by slug. `seen` guards against a lesson
+  // appearing twice (e.g. a fix committed and later archived as a change).
   const candidates = [];
+  const seen = new Set();
+
+  // Source 1 — archived change proposals with a fix-shaped folder name.
+  const archiveDir = path.join(projectRoot, ".doctrina", "changes", "archive");
   if (isDir(archiveDir)) {
     for (const name of readdirSync(archiveDir).sort()) {
       if (!isDir(path.join(archiveDir, name))) continue;
       const id = name.replace(/^\d{4}-\d{2}-\d{2}-/, "");
       if (!FIX_SHAPED.test(id)) continue;
       const slug = skillSlug(id);
-      if (existing.has(slug)) continue; // lesson already captured
+      if (existing.has(slug) || seen.has(slug)) continue; // captured or already queued
       const proposal = path.join(archiveDir, name, "proposal.md");
       const why = isFile(proposal) ? firstWhyLine(read(proposal)) : "";
-      candidates.push({ id, slug, why, archive: name });
+      seen.add(slug);
+      candidates.push({ id, slug, why, source: "change", from: name });
     }
   }
 
+  // Source 2 — fix-shaped commits in the git history (ADR 0013). Archive wins a
+  // slug collision: a `## Why` paragraph is a richer seed than a subject line.
+  for (const cand of gitFixCommits(projectRoot, { since, limit: GIT_LOG_LIMIT })) {
+    if (existing.has(cand.slug) || seen.has(cand.slug)) continue;
+    seen.add(cand.slug);
+    candidates.push(cand);
+  }
+
   if (candidates.length === 0) {
-    console.log(c.gray("no uncaptured fix-shaped lessons found in .doctrina/changes/archive/"));
-    console.log(c.gray("(skills are written by humans; this only surfaces candidates — `doctrina skill new <slug>` to author one)"));
+    console.log(c.gray("no uncaptured fix-shaped lessons found in .doctrina/changes/archive/ or the git history"));
+    console.log(c.gray("(scans archived changes and fix-shaped commits — pass --since <ref> to widen the git window;"));
+    console.log(c.gray(" skills are written by humans, so this only surfaces candidates — `doctrina skill new <slug>` to author one)"));
     return 0;
   }
 
   if (!doWrite) {
     console.log(c.bold("Skill candidates") + c.gray(" — fix-shaped lessons not yet captured:"));
     console.log("");
-    for (const cand of candidates) {
-      console.log(`  ${c.cyan(cand.slug.padEnd(28))} ${c.gray("from " + cand.archive)}`);
+    for (const cand of candidates.slice(0, MAX_SHOWN)) {
+      console.log(`  ${c.cyan(cand.slug.padEnd(28))} ${c.gray(provenance(cand))}`);
       if (cand.why) console.log(`    ${c.gray(cand.why.slice(0, 90))}`);
     }
+    const hidden = candidates.length - MAX_SHOWN;
+    if (hidden > 0) console.log(c.gray(`  … +${hidden} more`));
     console.log("");
     console.log(c.gray(`${candidates.length} candidate${candidates.length === 1 ? "" : "s"}. Scaffold them: `) + c.cyan("doctrina skill suggest --write"));
     return 0;
   }
 
-  // --write: scaffold a stub per candidate, pre-seeded from the change.
+  // --write: scaffold a stub per candidate, pre-seeded from its source.
   const templatesDir = locateTemplatesDir();
   const tplPath = path.join(templatesDir, "skill.md.template");
   const tpl = read(tplPath);
@@ -97,7 +132,7 @@ function skillSuggest(args, flags) {
     let body = substitute(tpl, { SKILL_NAME: cand.slug });
     if (cand.why) {
       // Drop the originating lesson into the body so authoring is "fill", not "start".
-      body += `\n<!-- Candidate from change "${cand.id}". The lesson to capture:\n${cand.why}\n-->\n`;
+      body += `\n<!-- ${seedLabel(cand)}. The lesson to capture:\n${cand.why}\n-->\n`;
     }
     write(target, body, { force: false });
     idx.addSkill(index, {
@@ -118,6 +153,63 @@ function skillSuggest(args, flags) {
   return 0;
 }
 
+// One-line origin shown next to a candidate slug.
+function provenance(cand) {
+  return cand.source === "commit" ? `from commit ${cand.ref}` : `from ${cand.from}`;
+}
+
+// The label seeded into a scaffolded skill body so the author knows where the
+// lesson came from.
+function seedLabel(cand) {
+  return cand.source === "commit"
+    ? `Candidate from commit ${cand.ref}`
+    : `Candidate from change "${cand.id}"`;
+}
+
+// Source 2 for `skill suggest`: fix-shaped commits in the git history (ADR
+// 0013). Deterministic — a regex on the subject, never a read of the diff
+// (ADR 0005 semantic-fidelity ceiling). Returns [] silently when this is not a
+// git repo, git is absent, or the --since ref is unknown, so the command
+// degrades to archive-only rather than erroring.
+function gitFixCommits(projectRoot, { since, limit }) {
+  // US (0x1f) between fields, RS (0x1e) between records — robust against any
+  // newline or punctuation inside a subject or body.
+  const format = "%H%x1f%s%x1f%b%x1e";
+  const args = ["log", "--no-merges", `--format=${format}`];
+  if (since) args.push(`${since}..HEAD`);
+  else args.push("-n", String(limit));
+
+  const r = spawnSync("git", args, { cwd: projectRoot, encoding: "utf8" });
+  if (r.error || r.status !== 0 || !r.stdout) return [];
+
+  const out = [];
+  const seen = new Set();
+  for (const record of r.stdout.split("\x1e")) {
+    const [sha, subject = "", body = ""] = record.replace(/^\r?\n/, "").split("\x1f");
+    if (!sha || !sha.trim()) continue;
+    if (!FIX_SHAPED_SUBJECT.test(subject)) continue;
+    const slug = commitSlug(subject);
+    if (!slug || seen.has(slug)) continue; // first commit wins a duplicate lesson
+    seen.add(slug);
+    const firstBodyLine = body.split(/\r?\n/).map((l) => l.trim()).find(Boolean) ?? "";
+    out.push({
+      id: slug,
+      slug,
+      source: "commit",
+      ref: sha.trim().slice(0, 9),
+      why: subject.trim() + (firstBodyLine ? ` — ${firstBodyLine}` : ""),
+    });
+  }
+  return out;
+}
+
+// Derive a skill slug from a commit subject: drop a conventional-commit
+// "type(scope): " prefix, then reuse skillSlug for the lowercase/hyphenate/cap.
+function commitSlug(subject) {
+  const stripped = subject.replace(/^[a-z]+(?:\([^)]*\))?!?\s*:\s*/i, "");
+  return skillSlug(stripped.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, ""));
+}
+
 function skillSlug(id) {
   // Reuse the change id as the skill slug, trimmed to a sane length.
   const slug = id.replace(/[^a-z0-9-]+/g, "-").replace(/^-+|-+$/g, "");
@@ -282,10 +374,13 @@ Subcommands:
   sync          Copy each skill's frontmatter description into
                 .doctrina/index.json so the index never drifts
                 from the frontmatter (single source of truth).
-  suggest [--write]
-                Surface fix-shaped lessons in the change archive whose
-                skill is not yet captured. --write scaffolds a stub per
-                candidate (pre-seeded from the change) to fill in.
+  suggest [--write] [--since <ref>]
+                Surface fix-shaped lessons not yet captured as skills,
+                from two sources: archived change proposals and the git
+                commit history (ADR 0013). --write scaffolds a stub per
+                candidate (pre-seeded from its source) to fill in.
+                --since <ref> scans commits in <ref>..HEAD instead of the
+                last 200 (e.g. --since v0.7.0).
 
 Skills are written by humans, not generated. See docs/en/skills.md
 for the design rationale and the distinction from specs / AGENTS.md /

package/src/commands/validate.js

@@ -11,6 +11,13 @@ import { c } from "../lib/colors.js";
 import { parseFrontmatter } from "./skill.js";
 import { checkEars, isEarsSpec } from "../lib/ears.js";
 import { specHeader, listHeader, deriveIndex, indexesMatch, stableStringify } from "../lib/scan.js";
+import { COMMAND_NAMES, referencedCommands } from "../lib/commands.js";
+import { parseAcceptanceCriteria, isVerified } from "../lib/criteria.js";
+
+// AGENTS.md is treated as a maintained doctrina-command catalog only once it
+// documents at least this many real commands; below it, the file defers to
+// `doctrina --help` and is never nagged about omissions.
+const CATALOG_THRESHOLD = 8;
 
 export async function run(_positional, flags) {
   const projectRoot = process.cwd();
@@ -25,6 +32,46 @@ export async function run(_positional, flags) {
     const lines = lineCount(agentsMd);
     if (lines > 200) errors.push(`AGENTS.md is ${lines} lines (>200, hard limit)`);
     else if (lines > 150) warnings.push(`AGENTS.md is ${lines} lines (>150 soft limit)`);
+
+    // 1c. AGENTS.md command-surface drift. AGENTS.md is the hub the agent reads
+    //     first, so the doctrina commands it documents must match the real CLI.
+    //     Two drifts are flagged: a reference to a command that does not exist
+    //     (a typo or a removed command — the agent will try to run it and fail),
+    //     and a maintained catalog that has fallen behind the CLI (commands the
+    //     agent never discovers because the hub never names them). validate only
+    //     checked AGENTS.md *size* before, so the hub could rot while staying
+    //     green; this closes that gap.
+    const agentsText = read(agentsMd);
+    const referenced = referencedCommands(agentsText);
+    const known = new Set(COMMAND_NAMES);
+    // Reverse drift is always flagged — a dangling command reference misleads
+    // the agent regardless of how the file is structured.
+    for (const cmd of [...referenced].sort()) {
+      if (!known.has(cmd)) {
+        warnings.push(
+          `AGENTS.md references \`doctrina ${cmd}\` which is not a CLI command ` +
+            `(typo or removed command — agents reading the hub will try to run it)`,
+        );
+      }
+    }
+    // Forward drift (omitted commands) is flagged only when the file presents
+    // itself as an exhaustive catalog: it documents many commands AND does not
+    // defer to `doctrina --help`. A file that defers is declaring its list
+    // illustrative (the shipped template does this), so its omissions are
+    // intentional and stay silent.
+    const documented = [...referenced].filter((cmd) => known.has(cmd));
+    const defersToHelp = /doctrina(?:-cli)?\s+--help/.test(agentsText);
+    if (documented.length >= CATALOG_THRESHOLD && !defersToHelp) {
+      const missing = COMMAND_NAMES.filter((cmd) => !referenced.has(cmd));
+      if (missing.length > 0) {
+        warnings.push(
+          `AGENTS.md documents the doctrina command surface but omits ` +
+            `${missing.length} command${missing.length === 1 ? "" : "s"} ` +
+            `(${missing.join(", ")}) — agents reading the hub will not discover ` +
+            `them (add them, or defer to \`doctrina --help\` for the full list)`,
+        );
+      }
+    }
   }
 
   // 1b. Nested AGENTS.md files ("nearest wins" hierarchy) obey the same
@@ -306,6 +353,23 @@ export async function run(_positional, flags) {
             }
           }
         }
+
+        // 8f. Self-certified acceptance criteria (honest gates, ADR 0008). A
+        //     criterion that asserts [verified] but cites no proof path is a
+        //     claim with nothing behind it — the dishonest-green case. `coverage`
+        //     reports every bare criterion; this names the specific combo
+        //     (claims verified, proves nothing) in the always-run gate. It reads
+        //     through the shared multi-line parser, so a proof cited on a
+        //     continuation line still counts (no false positive).
+        for (const crit of parseAcceptanceCriteria(text)) {
+          if (isVerified(crit) && crit.proofPaths.length === 0) {
+            warnings.push(
+              `${relPath(projectRoot, specPath)}: acceptance criterion #${crit.n} is marked ` +
+                `[verified] but cites no proof path — self-certified (cite the file/test in ` +
+                `backticks, or drop the marker; \`doctrina coverage\`)`,
+            );
+          }
+        }
       }
     }
   }

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";
 
@@ -66,16 +68,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 +110,44 @@ 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;
 }
 
+// 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 +182,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");
@@ -175,7 +207,8 @@ Usage: doctrina why <capability>
 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.
+(with cited evidence), the accepted ADRs that name it, and the archived
+changes that built it (from the index ledger). Read-only.
 
 Builds on the intent provenance (ADR 0006/0011) — answer "why was X built,
 and built this way?" without grepping the tree by hand.

package/src/index.js

@@ -31,12 +31,13 @@ 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";
 
 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,
 };
 
 const TOP_HELP = `
@@ -75,6 +76,7 @@ Commands:
   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

package/src/lib/commands.js

@@ -0,0 +1,46 @@
+// 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
+  "context", "search", "status", "next", "why", "constitution",
+  // gates
+  "analyze", "clarify", "validate", "coverage", "trace", "review", "verify", "close",
+  // maintenance
+  "templates", "hooks", "index", "watch", "metrics",
+];
+
+// 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/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.

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

@@ -0,0 +1,17 @@
+---
+description: Turn a request into a Doctrina change and drive it through the gates
+argument-hint: <prompt describing the change>
+---
+
+Drive the Doctrina spec-driven workflow for **{{PROJECT_NAME}}**.
+
+1. `doctrina work "$ARGUMENTS"` — scaffolds the change and prints the playbook.
+   (No prompt, but you already edited code? Use `doctrina work --from-diff`.)
+2. Execute the printed playbook in order: read the pack with
+   `doctrina context <capability> --concat`, write the spec delta, fill
+   `tasks.md`, implement, then `doctrina analyze <id>` → `doctrina change apply <id>`.
+3. Close it: `doctrina close <id>` (verify → coverage → archive → validate) and
+   resolve every `error:` before reporting the work done.
+
+Reach for the CLI instead of hand-authoring artifacts. Ask the human only on
+genuine ambiguity.

package/templates/adapters/cursor/.cursor/commands/doctrina-context.md.template

@@ -0,0 +1,10 @@
+# /doctrina-context — read pack for {{PROJECT_NAME}}
+
+Assemble the context before doing any work.
+
+Run `doctrina context <capability> --concat` and read top to bottom:
+AGENTS.md → product.md → the capability spec(s) → open changes → accepted ADRs.
+With no capability it includes every active spec. The change archive is
+excluded 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/cursor/.cursor/commands/doctrina-next.md.template

@@ -0,0 +1,10 @@
+# /doctrina-next — next step for {{PROJECT_NAME}}
+
+Decide the next step 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.

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

@@ -0,0 +1,10 @@
+# /doctrina-status — health of {{PROJECT_NAME}}
+
+Report the project's health and gate status.
+
+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/cursor/.cursor/commands/doctrina-why.md.template

@@ -0,0 +1,9 @@
+# /doctrina-why — provenance for {{PROJECT_NAME}}
+
+Explain why a capability exists and is shaped as it is.
+
+Run `doctrina why <capability>` 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.

package/templates/adapters/cursor/.cursor/commands/doctrina-work.md.template

@@ -0,0 +1,12 @@
+# /doctrina-work — drive a change for {{PROJECT_NAME}}
+
+Turn the request into a Doctrina change and drive it through the gates.
+
+1. Run `doctrina work "<the request>"` (or `doctrina work --from-diff` if you
+   already edited code) and follow the printed playbook.
+2. `doctrina context <capability> --concat` → write the spec delta → fill
+   `tasks.md` → implement → `doctrina analyze <id>` → `doctrina change apply <id>`.
+3. `doctrina close <id>` (verify → coverage → archive → validate); resolve
+   every `error:` before reporting the work done.
+
+Prefer the CLI over hand-authoring artifacts. Ask only on genuine ambiguity.

package/templates/doctrina/index.json.template

@@ -4,6 +4,9 @@
   "framework_version": "{{FRAMEWORK_VERSION}}",
   "last_updated": "{{DATE}}",
   "artifacts": {
+    "entrypoint": {
+      "path": "AGENTS.md"
+    },
     "product": {
       "path": ".doctrina/product.md",
       "status": "active",