doctrina-cli 0.10.0 → 0.12.0

package/src/commands/doctor.js

@@ -0,0 +1,135 @@
+import path from "node:path";
+import process from "node:process";
+import { spawnSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import { exists } from "../lib/fs-ops.js";
+import { collectStatus } from "./status.js";
+import { c } from "../lib/colors.js";
+
+// Aggregate diagnostic: the one command to run when "something looks wrong"
+// and you do not know which gate to ask. It sequences the existing checks —
+// validate, index drift, clean-checkout lint, template shape — and reports
+// each with its exact remediation command. A DRIVER over existing commands
+// (like `close`): it adds no checks of its own, so it can never disagree
+// with the authoritative gates it fronts.
+
+const cliEntry = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "index.js");
+
+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.");
+  }
+
+  console.log(c.bold("Doctrina doctor") + c.gray(" — aggregate diagnostic (read-only):"));
+  console.log("");
+
+  let failures = 0;
+  let warningsTotal = 0;
+  const row = (state, name, detail, fix) => {
+    const mark = state === "ok" ? c.green("ok  ") : state === "warn" ? c.yellow("warn") : c.red("FAIL");
+    console.log(`  ${mark}  ${name.padEnd(16)} ${detail}`);
+    if (fix) console.log(`        ${" ".repeat(16)} ${c.gray(`fix: ${fix}`)}`);
+    if (state === "fail") failures += 1;
+  };
+
+  // 1. Structural gate (validate), machine-read so the counts are exact.
+  const v = runSelf(["validate", "--json"], projectRoot);
+  let vParsed = null;
+  try {
+    vParsed = JSON.parse(v.stdout);
+  } catch {
+    vParsed = null;
+  }
+  if (!vParsed) {
+    row("fail", "validate", "did not produce a report", "doctrina validate");
+  } else if (!vParsed.ok) {
+    row("fail", "validate", `${vParsed.errors.length} error${vParsed.errors.length === 1 ? "" : "s"}, ${vParsed.warnings.length} warning${vParsed.warnings.length === 1 ? "" : "s"}`, "doctrina validate  (then `doctrina validate --fix` for index drift)");
+    for (const e of vParsed.errors.slice(0, 3)) console.log(`        ${" ".repeat(16)} ${c.red("·")} ${e}`);
+  } else if (vParsed.warnings.length > 0) {
+    warningsTotal += vParsed.warnings.length;
+    row("warn", "validate", `0 errors, ${vParsed.warnings.length} warning${vParsed.warnings.length === 1 ? "" : "s"}`, "doctrina validate  (warnings listed there)");
+  } else {
+    row("ok", "validate", "all structural checks pass");
+  }
+
+  // 2. Index ↔ tree drift.
+  const drift = runSelf(["index", "rebuild", "--check"], projectRoot);
+  if (drift.status === 0) row("ok", "index", "index.json matches the tree");
+  else row("fail", "index", "index.json has drifted from the tree", "doctrina validate --fix   (or `doctrina index rebuild`)");
+
+  // 3. Evidence and provenance ratios (cheap summaries; strict gates confirm).
+  const s = collectStatus(projectRoot);
+  if (s.coverage.totalCriteria === 0) {
+    row("warn", "coverage", "no acceptance criteria declared yet", "write criteria with evidence — see `doctrina coverage`");
+    warningsTotal += 1;
+  } else if (s.coverage.pct === 100 && s.coverage.totalDangling === 0 && s.coverage.totalConditional === 0) {
+    row("ok", "coverage", `${s.coverage.pct}% (${s.coverage.totalCovered}/${s.coverage.totalCriteria} criteria)`);
+  } else {
+    row("warn", "coverage", `${s.coverage.pct}% (${s.coverage.totalCovered}/${s.coverage.totalCriteria}${s.coverage.totalDangling ? `, ${s.coverage.totalDangling} dangling` : ""}${s.coverage.totalConditional ? `, ${s.coverage.totalConditional} conditional` : ""})`, "doctrina coverage   (cite the missing evidence)");
+    warningsTotal += 1;
+  }
+  if (s.trace.anchors === 0) {
+    row("warn", "trace", "no intent anchors declared in product.md", "tag bullets `- [SC1] ...`, add `**Realizes:**` to specs");
+    warningsTotal += 1;
+  } else if (s.trace.realized === s.trace.anchors && s.trace.untraceable === 0 && s.trace.dangling === 0) {
+    row("ok", "trace", `${s.trace.realized}/${s.trace.anchors} anchors realized`);
+  } else {
+    row("warn", "trace", `${s.trace.realized}/${s.trace.anchors} realized, ${s.trace.dropped} dropped, ${s.trace.untraceable} untraceable`, "doctrina trace");
+    warningsTotal += 1;
+  }
+
+  // 4. Clean-checkout reproducibility lint (ADR 0008).
+  const clean = runSelf(["verify", "--clean"], projectRoot);
+  if (clean.status === 0) row("ok", "clean-checkout", "no reproducibility footguns detected");
+  else row("fail", "clean-checkout", "a fresh clone would not build/run as-is", "doctrina verify --clean   (fix the listed package.json footguns)");
+
+  // 5. Template shape vs the running CLI's recommendation.
+  const tmpl = runSelf(["templates", "check"], projectRoot);
+  if (tmpl.status === 0) row("ok", "templates", "project follows the current template shape");
+  else {
+    row("warn", "templates", "recommended sections/fields are missing", "doctrina templates update   (--write applies)");
+    warningsTotal += 1;
+  }
+
+  // 6. Verify configuration (the real build gate must exist to be run).
+  if (s.verify.invalid) row("fail", "verify config", ".doctrina/verify.json is invalid JSON", "fix the JSON, then `doctrina verify`");
+  else if (!s.verify.configured) {
+    row("warn", "verify config", "no verify.json — the build gate is undeclared", "doctrina verify --init");
+    warningsTotal += 1;
+  } else {
+    row("ok", "verify config", `${s.verify.checks} check${s.verify.checks === 1 ? "" : "s"} declared (run \`doctrina verify\` to execute)`);
+  }
+
+  console.log("");
+  if (failures > 0) {
+    console.log(c.red("fail") + ` ${failures} failing area${failures === 1 ? "" : "s"} — fix commands above, then re-run \`doctrina doctor\``);
+    return 1;
+  }
+  if (warningsTotal > 0) {
+    console.log(c.yellow("warn") + ` no failures; ${warningsTotal} advisory item${warningsTotal === 1 ? "" : "s"} above`);
+    return 0;
+  }
+  console.log(c.green("ok") + " every diagnostic is green — `doctrina verify` remains the build gate to execute");
+  return 0;
+}
+
+function runSelf(args, cwd) {
+  return spawnSync(process.execPath, [cliEntry, ...args], {
+    cwd,
+    encoding: "utf8",
+    env: { ...process.env, NO_COLOR: "1" },
+  });
+}
+
+export const help = `
+Usage: doctrina doctor
+
+Aggregate diagnostic: run the structural gate (validate), the index
+drift check, the coverage/trace ratios, the clean-checkout lint
+(verify --clean), the template-shape check, and the verify-config
+presence — each reported with its exact remediation command.
+
+A driver over the existing commands; it adds no checks of its own.
+Read-only. Exits 1 when any area fails, 0 otherwise (warnings allowed).
+`;

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/intent.js

@@ -0,0 +1,173 @@
+import path from "node:path";
+import process from "node:process";
+import { exists, isFile, read, relPath, write } from "../lib/fs-ops.js";
+import { c } from "../lib/colors.js";
+import { suggest } from "../lib/suggest.js";
+
+// Post-intake intent evolution (0.11.0 field review item 8). The intake is
+// converted once; capabilities born later — brainstorms, pivots, new asks —
+// had no way to gain a product anchor, so they inevitably ended at
+// `Realizes: n/a` and `trace` reported "14/14 ok" while blind to 40% of the
+// system. `intent add` appends a new [SC*] anchor bullet to product.md's
+// Success criteria (allocating the next number), so growth keeps provenance:
+// new intent gets an anchor, the new spec Realizes it, `trace` sees it.
+//
+// The CLI allocates and appends; WHAT the intent says is the human/agent's
+// words verbatim (ADR 0005).
+
+const SUBCOMMANDS = ["add", "list"];
+
+export async function run(positional, _flags) {
+  const sub = positional[0];
+  if (!SUBCOMMANDS.includes(sub)) {
+    console.error(c.red("error:") + ` unknown intent subcommand "${sub ?? ""}"`);
+    const guess = suggest(sub, SUBCOMMANDS);
+    console.error(c.gray("hint: ") + (guess
+      ? `did you mean \`doctrina intent ${guess}\`?`
+      : `available: ${SUBCOMMANDS.join(", ")}`));
+    return 2;
+  }
+  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 (sub === "list") return intentList(projectRoot);
+  return intentAdd(projectRoot, positional.slice(1).join(" ").trim());
+}
+
+function productPathOf(projectRoot) {
+  return path.join(projectRoot, ".doctrina", "product.md");
+}
+
+// Every "[A-Z]+\d+" anchor at the head of a bullet, in document order —
+// the same convention `trace` reads.
+function collectAnchors(text) {
+  const out = [];
+  const seen = new Set();
+  const lines = text.split(/\r?\n/);
+  for (let i = 0; i < lines.length; i++) {
+    const m = lines[i].match(/^\s*[-*]\s+\[([A-Z]+)(\d+)\]\s+(.*)$/);
+    if (m && !seen.has(m[1] + m[2])) {
+      seen.add(m[1] + m[2]);
+      out.push({ prefix: m[1], num: Number(m[2]), id: m[1] + m[2], text: m[3].trim(), line: i });
+    }
+  }
+  return out;
+}
+
+function intentList(projectRoot) {
+  const p = productPathOf(projectRoot);
+  if (!isFile(p)) {
+    console.error(c.red("error:") + " no .doctrina/product.md");
+    return 1;
+  }
+  const anchors = collectAnchors(read(p));
+  if (anchors.length === 0) {
+    console.log(c.gray("no intent anchors in product.md — tag bullets with `- [SC1] ...`, or add one: doctrina intent add \"<text>\""));
+    return 0;
+  }
+  console.log(c.bold("Intent anchors") + c.gray(" — product.md, document order:"));
+  console.log("");
+  for (const a of anchors) {
+    console.log(`  ${c.cyan(a.id.padEnd(6))} ${a.text}`);
+  }
+  console.log("");
+  console.log(c.gray(`${anchors.length} anchor${anchors.length === 1 ? "" : "s"}. Provenance: doctrina trace · doctrina why <id>`));
+  return 0;
+}
+
+function intentAdd(projectRoot, textArg) {
+  if (!textArg) {
+    console.error(c.red("error:") + " intent add requires the intent text (quote it)");
+    console.error(c.gray("hint: ") + `example: doctrina intent add "Risk map answers 'what should we test next?' in one read"`);
+    return 2;
+  }
+  const p = productPathOf(projectRoot);
+  if (!isFile(p)) {
+    console.error(c.red("error:") + " no .doctrina/product.md — run `doctrina init` / `doctrina intake` first");
+    return 1;
+  }
+  const original = read(p);
+  const anchors = collectAnchors(original);
+
+  // Accept "SC15: text" to pin an explicit id; otherwise allocate the next
+  // number for the dominant prefix (SC by default).
+  let id = null;
+  let text = textArg;
+  const pinned = textArg.match(/^([A-Z]+)(\d+)\s*:\s*(.+)$/);
+  if (pinned) {
+    id = pinned[1] + pinned[2];
+    text = pinned[3].trim();
+    if (anchors.some((a) => a.id === id)) {
+      console.error(c.red("error:") + ` anchor [${id}] already exists in product.md`);
+      return 1;
+    }
+  } else {
+    const prefix = anchors.length > 0 ? dominantPrefix(anchors) : "SC";
+    const maxNum = anchors.filter((a) => a.prefix === prefix).reduce((m, a) => Math.max(m, a.num), 0);
+    id = `${prefix}${maxNum + 1}`;
+  }
+
+  const lines = original.split(/\r?\n/);
+  const bullet = `- [${id}] ${text}`;
+
+  // Insertion point: after the LAST existing anchor bullet (keeps them
+  // contiguous); else at the end of "## Success criteria"; else appended as a
+  // new Success criteria section (a product.md without one gains it).
+  const samePrefix = anchors.length > 0;
+  let inserted = false;
+  if (samePrefix) {
+    const last = anchors[anchors.length - 1];
+    lines.splice(last.line + 1, 0, bullet);
+    inserted = true;
+  } else {
+    for (let i = 0; i < lines.length; i++) {
+      if (/^##\s+Success criteria\b/i.test(lines[i])) {
+        // Insert before the next "## " heading (or at EOF).
+        let j = i + 1;
+        while (j < lines.length && !/^##\s+/.test(lines[j])) j += 1;
+        // Trim trailing blank lines inside the section for a tidy append.
+        let k = j;
+        while (k > i + 1 && lines[k - 1].trim() === "") k -= 1;
+        lines.splice(k, 0, bullet);
+        inserted = true;
+        break;
+      }
+    }
+  }
+  if (!inserted) {
+    lines.push("", "## Success criteria", "", bullet);
+  }
+
+  write(p, lines.join("\n"), { force: true });
+  console.log(c.green("added") + ` [${id}] to ${relPath(projectRoot, p)}`);
+  console.log("");
+  console.log(`  ${c.cyan(id.padEnd(6))} ${text}`);
+  console.log("");
+  console.log(c.gray("Next: the spec that delivers this intent declares it —"));
+  console.log(`    ${c.cyan(`**Realizes:** ${id}`)}  ${c.gray("(in .doctrina/specs/<capability>/spec.md; `doctrina trace` closes the loop)")}`);
+  return 0;
+}
+
+function dominantPrefix(anchors) {
+  const counts = new Map();
+  for (const a of anchors) counts.set(a.prefix, (counts.get(a.prefix) ?? 0) + 1);
+  return [...counts.entries()].sort((x, y) => y[1] - x[1] || x[0].localeCompare(y[0]))[0][0];
+}
+
+export const help = `
+Usage: doctrina intent add "<text>"
+       doctrina intent add "SC15: <text>"
+       doctrina intent list
+
+Post-intake intent evolution. \`add\` appends a new intent anchor bullet
+(\`- [SC5] <text>\`) to product.md's Success criteria, allocating the next
+number automatically (or pin one with the "SC15: ..." form). New
+capabilities born after the intake — brainstorms, pivots — get an anchor
+to Realize instead of inevitably landing at "Realizes: n/a", so
+\`doctrina trace\` keeps seeing the whole system as it grows.
+
+\`list\` prints every anchor in document order (the same convention trace
+reads). The CLI allocates and appends; the intent's wording is yours,
+verbatim (ADR 0005).
+`;

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>\`.
+`;