doctrina-cli 0.10.0 → 0.11.0

package/src/commands/handoff.js

@@ -0,0 +1,94 @@
+import path from "node:path";
+import process from "node:process";
+import { exists } from "../lib/fs-ops.js";
+import { collectStatus } from "./status.js";
+import { computeActions } from "./next.js";
+import { openChanges } from "./prime.js";
+import { today } from "../lib/dates.js";
+import { c } from "../lib/colors.js";
+
+// Session handoff note: everything the NEXT session (a fresh agent, a
+// teammate, tomorrow's you) needs to resume without re-reading the tree —
+// where the open work stands task-by-task, which gates are red, and the
+// exact command to continue with. Doctrina's thesis is that context must
+// survive across sessions; this command is that thesis for the in-flight
+// change. It is a VIEW derived from the tree at call time, deliberately not
+// a stored file: a saved note goes stale the moment work continues, the
+// tree never does (no new home for facts).
+
+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 s = collectStatus(projectRoot);
+  const open = openChanges(projectRoot);
+  const actions = computeActions(projectRoot);
+
+  console.log(`# Doctrina handoff — ${s.project} (${today()})`);
+  console.log("");
+
+  // Gate digest — the red ones are what the resuming session fixes first.
+  console.log("## Where things stand");
+  console.log("");
+  console.log(`- index: ${s.indexState} · framework stamp: ${s.stamp ?? "—"} (CLI ${s.cli})`);
+  console.log(`- coverage: ${s.coverage.pct}% (${s.coverage.totalCovered}/${s.coverage.totalCriteria} criteria` +
+    (s.coverage.totalDangling ? `, ${s.coverage.totalDangling} dangling` : "") +
+    (s.coverage.totalConditional ? `, ${s.coverage.totalConditional} conditional` : "") + ")");
+  const tr = s.trace.anchors === 0 ? "no anchors declared" : `${s.trace.realized}/${s.trace.anchors} anchors realized`;
+  console.log(`- trace: ${tr}` + (s.trace.untraceable ? ` (${s.trace.untraceable} untraceable)` : ""));
+  console.log(`- verify: ${s.verify.configured ? `${s.verify.checks} checks declared — run \`doctrina verify\`` : "not configured"}`);
+
+  // The in-flight work, task by task.
+  console.log("");
+  if (open.length === 0) {
+    console.log("## Open work");
+    console.log("");
+    console.log("- none — the tree is at rest; start with `doctrina work \"<prompt>\"`");
+  } else {
+    for (const ch of open) {
+      console.log(`## Open change \`${ch.id}\`${ch.title ? ` — ${ch.title}` : ""}`);
+      console.log("");
+      console.log(`- proposal status: ${ch.status}`);
+      if (ch.tasksTotal > 0) {
+        console.log(`- tasks: ${ch.tasksDone}/${ch.tasksTotal} checked`);
+        for (const t of ch.unchecked.slice(0, 8)) console.log(`  - [ ] ${t}`);
+        if (ch.unchecked.length > 8) console.log(`  - … ${ch.unchecked.length - 8} more in tasks.md`);
+      } else {
+        console.log("- tasks: no tasks.md checklist found");
+      }
+      console.log(`- resume with: \`doctrina work --resume ${ch.id}\` · close with: \`doctrina close ${ch.id}\``);
+      console.log("");
+    }
+  }
+
+  // What to do, in priority order.
+  console.log("## Next actions");
+  console.log("");
+  if (actions.length === 0) {
+    console.log("1. nothing pending — `doctrina next` will confirm; pick up new work");
+  } else {
+    actions.forEach((a, i) => console.log(`${i + 1}. ${a}`));
+  }
+
+  console.log("");
+  console.log("*Generated read-only from the tree — regenerate anytime with `doctrina handoff`.*");
+  if (process.stdout.isTTY) {
+    console.log("");
+    console.log(c.gray("tip: pipe it — `doctrina handoff > note.md` — or paste it as the first message of the next session"));
+  }
+  return 0;
+}
+
+export const help = `
+Usage: doctrina handoff
+
+Print a session handoff note in Markdown: gate digest, each open change
+with its task-by-task progress and the exact resume command, and the
+prioritised next actions. Made to be pasted as the first message of the
+next agent session (or piped to a file).
+
+Deliberately a derived view, not a stored file — the tree is the truth
+and never goes stale; regenerate on demand. Read-only; always exits 0.
+`;

package/src/commands/init.js

@@ -56,7 +56,18 @@ export async function run(_positional, flags) {
     description = await ask("One-sentence project description:");
   }
 
-  const agentSelector = flagString(flags, "agent");
+  let agentSelector = flagString(flags, "agent");
+  // Interactive wizard step: when no --agent was given and we are on a real
+  // terminal, offer the adapter install instead of silently skipping it —
+  // first-run users rarely know the flag exists. Never fires in pipes/CI
+  // (no TTY) or under --non-interactive, so scripted init is unchanged.
+  if (agentSelector === undefined && !nonInteractive && process.stdin.isTTY && process.stdout.isTTY) {
+    const answer = await ask(
+      `Install an agent adapter? (${SUPPORTED_AGENTS.join("/")}/all/none)`,
+      { defaultValue: "none" },
+    );
+    if (answer && answer !== "none") agentSelector = answer;
+  }
   const fromPath = flagString(flags, "from");
   const agentsMdPath = path.join(projectRoot, "AGENTS.md");
   const doctrinaDir = path.join(projectRoot, ".doctrina");

package/src/commands/next.js

@@ -4,15 +4,43 @@ import { readdirSync } from "node:fs";
 import { exists, isDir, isFile, read, relPath, walk } from "../lib/fs-ops.js";
 import * as idx from "../lib/index-json.js";
 import { deriveIndex, indexesMatch, listHeader } from "../lib/scan.js";
+import { flagBool } from "../lib/args.js";
 import { c } from "../lib/colors.js";
 
-export async function run(_positional, _flags) {
+export async function run(_positional, flags) {
   const projectRoot = process.cwd();
+  const json = flagBool(flags, "json", false);
   if (!exists(path.join(projectRoot, ".doctrina"))) {
-    console.log("1. doctrina init — this directory is not a Doctrina project yet");
+    const first = "doctrina init — this directory is not a Doctrina project yet";
+    console.log(json ? JSON.stringify({ actions: [first] }, null, 2) : `1. ${first}`);
     return 0;
   }
 
+  const actions = computeActions(projectRoot);
+
+  if (json) {
+    console.log(JSON.stringify({ actions }, null, 2));
+    return 0;
+  }
+
+  if (actions.length === 0) {
+    console.log(c.green("ok") + " no open work.");
+    console.log("");
+    console.log("Start something:");
+    console.log(`  doctrina change new <id> "<title>"   open a change proposal`);
+    console.log(`  doctrina spec new <capability>       spec a new capability`);
+    return 0;
+  }
+
+  console.log(c.bold("Next actions") + c.gray(" (in priority order):"));
+  console.log("");
+  actions.forEach((a, i) => console.log(`${i + 1}. ${a}`));
+  return 0;
+}
+
+// The priority-ordered action list, render-free — shared with `prime`,
+// `handoff`, and the --json output.
+export function computeActions(projectRoot) {
   const actions = [];
 
   // A pending intake is the very first thing to resolve: until it is
@@ -106,19 +134,7 @@ export async function run(_positional, _flags) {
     actions.push("doctrina index rebuild — index.json is missing or unreadable");
   }
 
-  if (actions.length === 0) {
-    console.log(c.green("ok") + " no open work.");
-    console.log("");
-    console.log("Start something:");
-    console.log(`  doctrina change new <id> "<title>"   open a change proposal`);
-    console.log(`  doctrina spec new <capability>       spec a new capability`);
-    return 0;
-  }
-
-  console.log(c.bold("Next actions") + c.gray(" (in priority order):"));
-  console.log("");
-  actions.forEach((a, i) => console.log(`${i + 1}. ${a}`));
-  return 0;
+  return actions;
 }
 
 // Return a single skill-capture nudge, or null. Fires only when no skill has
@@ -147,7 +163,7 @@ function suggestSkillCapture(projectRoot) {
 }
 
 export const help = `
-Usage: doctrina next
+Usage: doctrina next [--json]
 
 Inspect the .doctrina/ tree and print the recommended next workflow
 actions in priority order: open changes (missing proposal, unchecked

package/src/commands/prime.js

@@ -0,0 +1,118 @@
+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 { collectStatus } from "./status.js";
+import { computeActions } from "./next.js";
+import { acceptedDecisions, productSection } from "./constitution.js";
+import { c } from "../lib/colors.js";
+
+// Session primer: the ~40-line read that orients an agent at the start of a
+// session — where things stand, what the standing rules are, what work is
+// open, and what to do next — without paying for the full context pack.
+// It sits between `status` (numbers only) and `context --concat` (everything):
+// enough to act, cheap enough to run every session. Strictly read-only; every
+// line is assembled from artifacts that already own the fact (no new home).
+
+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 s = collectStatus(projectRoot);
+
+  console.log(c.bold("Doctrina prime") + c.gray(` — ${s.project}  (framework ${s.stamp ?? "—"} / CLI ${s.cli})`));
+  console.log("");
+
+  // One-line gate digest.
+  const cov = `${s.coverage.pct}% (${s.coverage.totalCovered}/${s.coverage.totalCriteria})`;
+  const tr = s.trace.anchors === 0 ? "no anchors" : `${s.trace.realized}/${s.trace.anchors}`;
+  const verify = s.verify.configured ? `${s.verify.checks} verify checks` : "verify not configured";
+  console.log(c.bold("Gates  ") + `index ${s.indexState} · coverage ${cov} · trace ${tr} · ${verify}`);
+  const implBreak = Object.entries(s.specs.impl).map(([k, v]) => `${v} ${k}`).join(", ");
+  console.log(
+    c.bold("Work   ") +
+      `${s.specs.total} specs${implBreak ? ` (${implBreak})` : ""} · ${s.specs.openChanges} open change${s.specs.openChanges === 1 ? "" : "s"} · ` +
+      `${s.decisions.total} decisions · ${s.skills} skills`,
+  );
+
+  // Standing rules, titles only — `constitution` has the full text.
+  const adrs = acceptedDecisions(projectRoot);
+  console.log("");
+  console.log(c.bold("Rules") + c.gray(`  (${adrs.length} accepted ADRs — \`doctrina constitution\` for detail)`));
+  for (const a of adrs) console.log(`  ${c.cyan(a.id)}  ${a.title}`);
+  const nonGoals = productSection(projectRoot, "Non-goals");
+  if (nonGoals.length > 0) {
+    console.log(c.gray(`  + ${nonGoals.length} non-goal${nonGoals.length === 1 ? "" : "s"} declared in product.md`));
+  }
+
+  // Open work, with unchecked-task counts — the resume points.
+  console.log("");
+  console.log(c.bold("Open work"));
+  const open = openChanges(projectRoot);
+  if (open.length === 0) {
+    console.log(c.gray("  none — `doctrina work \"<prompt>\"` opens the next change"));
+  } else {
+    for (const ch of open) {
+      const tasks = ch.tasksTotal > 0 ? ` · tasks ${ch.tasksDone}/${ch.tasksTotal}` : "";
+      console.log(`  ${c.cyan(ch.id)}  ${ch.title ?? ""}${c.gray(` (${ch.status}${tasks})`)}`);
+    }
+  }
+
+  // Next actions (top 5 — `doctrina next` for the full list).
+  const actions = computeActions(projectRoot);
+  console.log("");
+  console.log(c.bold("Next"));
+  if (actions.length === 0) {
+    console.log(c.gray("  nothing pending — pick up new work"));
+  } else {
+    actions.slice(0, 5).forEach((a, i) => console.log(`  ${i + 1}. ${a}`));
+    if (actions.length > 5) console.log(c.gray(`  … ${actions.length - 5} more — \`doctrina next\``));
+  }
+
+  console.log("");
+  console.log(c.gray("Read deeper: `doctrina context [<cap>] --concat` · `doctrina why <cap>` · `doctrina show <ref>`"));
+  return 0;
+}
+
+// Open changes with their proposal status/title and task progress.
+export function openChanges(projectRoot) {
+  const changesDir = path.join(projectRoot, ".doctrina", "changes");
+  const out = [];
+  if (!isDir(changesDir)) return out;
+  for (const id of readdirSync(changesDir).sort()) {
+    if (id === "archive" || id.startsWith(".")) continue;
+    if (!isDir(path.join(changesDir, id))) continue;
+    const proposalPath = path.join(changesDir, id, "proposal.md");
+    const proposal = isFile(proposalPath) ? read(proposalPath) : null;
+    const title = proposal?.match(/^#\s+(?:Change\s+[^—-]*[—-]\s*)?(.+)$/m)?.[1]?.trim() ?? null;
+    const status = proposal ? (listHeader(proposal, "Status") ?? "proposed") : "no proposal.md";
+    const tasksPath = path.join(changesDir, id, "tasks.md");
+    let tasksDone = 0, tasksTotal = 0, unchecked = [];
+    if (isFile(tasksPath)) {
+      for (const line of read(tasksPath).split(/\r?\n/)) {
+        const m = line.match(/^-\s+\[([ xX])\]\s+(.*)$/);
+        if (!m) continue;
+        tasksTotal += 1;
+        if (m[1] === " ") unchecked.push(m[2].trim());
+        else tasksDone += 1;
+      }
+    }
+    out.push({ id, title, status, tasksDone, tasksTotal, unchecked });
+  }
+  return out;
+}
+
+export const help = `
+Usage: doctrina prime
+
+Print the session primer: gate digest, standing rules (accepted ADR
+titles + non-goal count), open work with task progress, and the top
+next actions — the ~40-line read that orients an agent at session
+start without paying for the full context pack.
+
+Read-only; always exits 0. Deeper reads: \`doctrina context\`,
+\`doctrina why <cap>\`, \`doctrina show <ref>\`.
+`;

package/src/commands/report.js

@@ -0,0 +1,142 @@
+import path from "node:path";
+import process from "node:process";
+import { spawnSync } from "node:child_process";
+import { exists } from "../lib/fs-ops.js";
+import * as idx from "../lib/index-json.js";
+import { collectStatus } from "./status.js";
+import { openChanges } from "./prime.js";
+import { flagString } from "../lib/args.js";
+import { today } from "../lib/dates.js";
+import { c } from "../lib/colors.js";
+
+// Periodic digest in Markdown — the standup/PR-description view: what was
+// archived, where the gates stand, and what local git says about the period.
+// Read-only, no network; the git section degrades silently outside a repo.
+
+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 sinceRaw = flagString(flags, "since") ?? "7";
+  const days = Number.parseInt(sinceRaw, 10);
+  if (!Number.isFinite(days) || days <= 0) {
+    console.error(c.red("error:") + ` --since expects a positive day count, got "${sinceRaw}"`);
+    return 2;
+  }
+  const cutoff = new Date(Date.now() - days * 24 * 60 * 60 * 1000);
+  const cutoffIso = cutoff.toISOString().slice(0, 10);
+
+  const s = collectStatus(projectRoot);
+
+  console.log(`# Doctrina report — ${s.project} (${cutoffIso} → ${today()})`);
+  console.log("");
+
+  // Gates.
+  console.log("## Gates");
+  console.log("");
+  console.log(`- index: ${s.indexState} · framework stamp: ${s.stamp ?? "—"} (CLI ${s.cli})`);
+  console.log(`- coverage: ${s.coverage.pct}% (${s.coverage.totalCovered}/${s.coverage.totalCriteria} criteria)` +
+    (s.coverage.totalDangling ? ` — ${s.coverage.totalDangling} dangling` : "") +
+    (s.coverage.totalConditional ? ` — ${s.coverage.totalConditional} conditional` : ""));
+  console.log(`- trace: ${s.trace.anchors === 0 ? "no anchors declared" : `${s.trace.realized}/${s.trace.anchors} anchors realized`}`);
+  console.log(`- verify: ${s.verify.configured ? `${s.verify.checks} checks declared` : "not configured"}`);
+
+  // Work shipped in the window (from the index ledger) + work in flight.
+  console.log("");
+  console.log("## Changes");
+  console.log("");
+  const archived = archivedSince(projectRoot, cutoffIso);
+  if (archived.length === 0) {
+    console.log(`- archived in period: none`);
+  } else {
+    console.log(`- archived in period: ${archived.length}`);
+    for (const ch of archived) console.log(`  - ${ch.applied} — \`${ch.id}\` ${ch.title}`);
+  }
+  const open = openChanges(projectRoot);
+  if (open.length === 0) {
+    console.log("- open now: none");
+  } else {
+    console.log(`- open now: ${open.length}`);
+    for (const ch of open) {
+      const tasks = ch.tasksTotal > 0 ? ` (tasks ${ch.tasksDone}/${ch.tasksTotal})` : "";
+      console.log(`  - \`${ch.id}\`${ch.title ? ` ${ch.title}` : ""}${tasks}`);
+    }
+  }
+
+  // Artifact counts, for trend-watching between reports.
+  console.log("");
+  console.log("## Artifacts");
+  console.log("");
+  console.log(`- specs: ${s.specs.total} · decisions: ${s.decisions.total}` +
+    (s.decisions.proposed ? ` (${s.decisions.proposed} proposed)` : "") +
+    ` · skills: ${s.skills}`);
+
+  // Local git window — commits, fix share, top churn. No network.
+  console.log("");
+  console.log("## Git (local, last " + days + " days)");
+  console.log("");
+  const git = gitWindow(projectRoot, days);
+  if (!git) {
+    console.log("- no git history available (not a repository, or git not installed)");
+  } else {
+    console.log(`- commits: ${git.commits} (${git.fixes} fix-shaped, ${git.commits ? Math.round((git.fixes / git.commits) * 100) : 0}%)`);
+    if (git.churn.length > 0) {
+      console.log(`- top-churn files:`);
+      for (const [file, n] of git.churn) console.log(`  - ${file} (${n} touches)`);
+    }
+  }
+
+  console.log("");
+  console.log(`*Generated read-only by \`doctrina report --since ${days}\`; deeper numbers: \`doctrina metrics\`.*`);
+  return 0;
+}
+
+function archivedSince(projectRoot, cutoffIso) {
+  let index;
+  try {
+    index = idx.load(projectRoot);
+  } catch {
+    return [];
+  }
+  return (index.artifacts?.changes_archive ?? [])
+    .filter((ch) => typeof ch.applied === "string" && ch.applied >= cutoffIso)
+    .sort((a, b) => String(a.applied).localeCompare(String(b.applied)));
+}
+
+function gitWindow(projectRoot, days) {
+  const log = spawnSync("git", ["log", `--since=${days} days ago`, "--pretty=%s"], {
+    cwd: projectRoot,
+    encoding: "utf8",
+  });
+  if (log.status !== 0) return null;
+  const subjects = log.stdout.split(/\r?\n/).filter((l) => l.trim().length > 0);
+  const fixes = subjects.filter((sub) => /^(fix|bug|hotfix|patch)(\(|:|!)/i.test(sub)).length;
+
+  const files = spawnSync("git", ["log", `--since=${days} days ago`, "--name-only", "--pretty=format:"], {
+    cwd: projectRoot,
+    encoding: "utf8",
+  });
+  const counts = new Map();
+  if (files.status === 0) {
+    for (const line of files.stdout.split(/\r?\n/)) {
+      const f = line.trim();
+      if (!f) continue;
+      counts.set(f, (counts.get(f) ?? 0) + 1);
+    }
+  }
+  const churn = [...counts.entries()].sort((a, b) => b[1] - a[1]).slice(0, 5);
+  return { commits: subjects.length, fixes, churn };
+}
+
+export const help = `
+Usage: doctrina report [--since <days>]
+
+Print a Markdown digest for the period (default: last 7 days): gate
+state, changes archived in the window (from the index ledger), open
+work with task progress, artifact counts, and a local-git summary
+(commits, fix share, top-churn files). Made for standups and PR
+descriptions. Read-only; no network. \`doctrina metrics\` has the
+deeper git-derived numbers.
+`;

package/src/commands/show.js

@@ -0,0 +1,173 @@
+import path from "node:path";
+import process from "node:process";
+import { readdirSync } from "node:fs";
+import { exists, isDir, isFile, read, relPath } from "../lib/fs-ops.js";
+import { parseAcceptanceCriteria } from "../lib/criteria.js";
+import { suggest } from "../lib/suggest.js";
+import { c } from "../lib/colors.js";
+
+// Point reads. An agent that needs ONE requirement re-reads a whole spec —
+// hundreds of lines for a two-line fact. `show` resolves a compact reference
+// to exactly the lines that own it:
+//
+//   doctrina show cli-R12    twelfth requirement of the cli spec (file order)
+//   doctrina show gates-C3   acceptance criterion 3 (the spec's own numbering)
+//   doctrina show 0007       ADR 0007, whole decision (already a bounded read)
+//   doctrina show cli        the spec's header block + Purpose only
+//
+// R-refs are positional (file order across the EARS sections), so they shift
+// when a requirement is inserted above — cite them for point reads and
+// conversation, not as immutable identifiers. C-refs use the criteria's own
+// explicit numbers and are as stable as the spec keeps them.
+
+export async function run(positional, _flags) {
+  const ref = positional[0];
+  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.");
+  }
+  if (!ref) {
+    console.error(c.red("error:") + " show requires a reference");
+    console.error(c.gray("hint: ") + "`doctrina show cli-R12` (requirement), `doctrina show cli-C3` (criterion), `doctrina show 0007` (ADR), `doctrina show cli` (spec header + purpose)");
+    return 2;
+  }
+
+  // ADR by number.
+  if (/^\d{4}$/.test(ref)) return showAdr(projectRoot, ref);
+
+  const m = ref.match(/^([a-z][a-z0-9-]*)-([RC])(\d+)$/);
+  if (m) return showSpecItem(projectRoot, m[1], m[2], Number(m[3]));
+
+  if (/^[a-z][a-z0-9-]*$/.test(ref)) return showSpecHead(projectRoot, ref);
+
+  console.error(c.red("error:") + ` unrecognised reference "${ref}"`);
+  console.error(c.gray("hint: ") + "use <cap>-R<n>, <cap>-C<n>, an ADR number (0007), or a capability name");
+  return 2;
+}
+
+function showAdr(projectRoot, num) {
+  const dir = path.join(projectRoot, ".doctrina", "decisions");
+  const file = isDir(dir) ? readdirSync(dir).find((f) => f.startsWith(`${num}-`) && f.endsWith(".md")) : null;
+  if (!file) {
+    console.error(c.red("error:") + ` no ADR ${num} under .doctrina/decisions/`);
+    return 1;
+  }
+  const full = path.join(dir, file);
+  console.log(c.gray(`— ${relPath(projectRoot, full)} —`));
+  console.log(read(full).trimEnd());
+  return 0;
+}
+
+function loadSpec(projectRoot, cap) {
+  const specsDir = path.join(projectRoot, ".doctrina", "specs");
+  const specPath = path.join(specsDir, cap, "spec.md");
+  if (isFile(specPath)) return { specPath, text: read(specPath) };
+  const known = isDir(specsDir) ? readdirSync(specsDir).filter((e) => isFile(path.join(specsDir, e, "spec.md"))) : [];
+  console.error(c.red("error:") + ` no spec for capability "${cap}"`);
+  const guess = suggest(cap, known);
+  if (guess) console.error(c.gray("hint: ") + `did you mean "${guess}"?`);
+  else if (known.length) console.error(c.gray("known: ") + known.sort().join(", "));
+  return null;
+}
+
+function showSpecHead(projectRoot, cap) {
+  const spec = loadSpec(projectRoot, cap);
+  if (!spec) return 1;
+  const lines = spec.text.split(/\r?\n/);
+  const out = [];
+  let mode = "head"; // header block -> seek Purpose -> purpose body -> stop
+  for (const line of lines) {
+    const isH2 = /^##\s+/.test(line);
+    if (mode === "head" && isH2) mode = /^##\s+Purpose\b/i.test(line) ? "purpose" : "seek";
+    else if (mode === "seek" && isH2 && /^##\s+Purpose\b/i.test(line)) mode = "purpose";
+    else if (mode === "purpose" && isH2) break;
+
+    if (mode === "head" || (mode === "purpose")) out.push(line);
+  }
+  console.log(c.gray(`— ${relPath(projectRoot, spec.specPath)} (header + purpose; \`doctrina context ${cap}\` for the full spec) —`));
+  console.log(out.join("\n").trimEnd());
+  return 0;
+}
+
+function showSpecItem(projectRoot, cap, kind, n) {
+  const spec = loadSpec(projectRoot, cap);
+  if (!spec) return 1;
+
+  if (kind === "C") {
+    const criteria = parseAcceptanceCriteria(spec.text);
+    const crit = criteria.find((r) => r.n === n);
+    if (!crit) {
+      console.error(c.red("error:") + ` ${cap} has no acceptance criterion #${n} (it declares ${criteria.length})`);
+      return 1;
+    }
+    console.log(c.gray(`— ${cap}-C${n} · ${relPath(projectRoot, spec.specPath)} · ## Acceptance criteria —`));
+    console.log(`${n}. ${crit.body}`);
+    if (crit.proofPaths.length > 0) {
+      console.log(c.gray(`   evidence: ${crit.proofPaths.join(", ")}`));
+    }
+    return 0;
+  }
+
+  const reqs = parseRequirements(spec.text);
+  const req = reqs[n - 1];
+  if (!req) {
+    console.error(c.red("error:") + ` ${cap} has no requirement R${n} (it declares ${reqs.length})`);
+    return 1;
+  }
+  console.log(c.gray(`— ${cap}-R${n} · ${relPath(projectRoot, spec.specPath)} · ${req.section} —`));
+  console.log(req.text);
+  return 0;
+}
+
+// Top-level bullets of the "## Requirements (EARS)" section, in file order,
+// each with its `### <grammar>` sub-section name and continuation lines.
+export function parseRequirements(text) {
+  const lines = text.split(/\r?\n/);
+  const out = [];
+  let inSection = false;
+  let sub = "";
+  let cur = null;
+  const flush = () => {
+    if (cur) out.push({ section: cur.section, text: cur.lines.join("\n").trimEnd() });
+    cur = null;
+  };
+  for (const line of lines) {
+    if (/^##\s+/.test(line)) {
+      flush();
+      inSection = /^##\s+Requirements\b/i.test(line);
+      sub = "";
+      continue;
+    }
+    if (!inSection) continue;
+    const subMatch = line.match(/^###\s+(.+)$/);
+    if (subMatch) {
+      flush();
+      sub = subMatch[1].trim();
+      continue;
+    }
+    if (/^-\s+/.test(line)) {
+      flush();
+      cur = { section: sub || "Requirements", lines: [line] };
+    } else if (cur && (line.startsWith("  ") || line.trim() === "")) {
+      cur.lines.push(line);
+    } else {
+      flush();
+    }
+  }
+  flush();
+  return out;
+}
+
+export const help = `
+Usage: doctrina show <ref>
+
+Point-read one artifact fragment instead of a whole file:
+
+  doctrina show cli-R12    requirement 12 of the cli spec (file order)
+  doctrina show cli-C3     acceptance criterion 3 (the spec's numbering)
+  doctrina show 0007       ADR 0007 (the whole decision)
+  doctrina show cli        the spec's header block + Purpose only
+
+R-refs are positional (they shift when a requirement is inserted above);
+C-refs use the criteria's own numbers. Read-only.
+`;