doctrina-cli 0.15.1 → 0.17.0

package/src/lib/snapshot.js

@@ -0,0 +1,231 @@
+// @ts-check
+import path from "node:path";
+import { readdirSync } from "node:fs";
+import { isDir, isFile, read, walk } from "./fs-ops.js";
+import { projectName } from "./project.js";
+import * as idx from "./index-json.js";
+import { deriveIndex, indexesMatch, specHeader, listHeader } from "./scan.js";
+import { cliVersion } from "./version.js";
+import { summarize as coverageSummary } from "./coverage-model.js";
+import { summarize as traceSummary } from "./trace-model.js";
+import { acceptedDecisions, productSection, hasProductSection } from "./constitution-model.js";
+import { computeActions } from "./actions.js";
+import { readLedger } from "./ledger.js";
+import { parseChangeTitle, checklistProgress } from "./doc-model.js";
+import { summarizeSignoffs } from "./signoff.js";
+import { gitWindow, historyState, windowCutoff } from "./git.js";
+import { collectMetrics } from "./metrics-model.js";
+
+// ONE collector, several views (audit finding F7).
+//
+// `status`, `prime`, `handoff` and `report` were four commands rendering the
+// same three collections, and they got at them by importing functions out of
+// each other's modules: `prime` reached into `status` for `collectStatus`,
+// `handoff` and `report` reached into `prime` for `openChanges`, and all
+// three reached into `coverage` and `trace` for their summaries. Every one of
+// those is a command module — a RENDERER — being used as a data source, which
+// is how four surfaces end up able to disagree about the same number.
+//
+// So the project's state is collected ONCE, here, into a plain object. The
+// four commands become formatters over it: same numbers, four shapes, and a
+// new view costs a function rather than a fifth traversal of the tree.
+//
+// Nothing here prints and nothing here writes.
+
+const VERIFY_CONFIG_REL = ".doctrina/verify.json";
+
+/**
+ * Everything the read-only views report, collected in one pass.
+ *
+ * `actions` is included because three of the four views end with "what next",
+ * and computing it separately in each was the same duplication one level up.
+ */
+export function collectSnapshot(projectRoot, { actions = true } = {}) {
+  let index = null;
+  try {
+    index = idx.load(projectRoot);
+  } catch {
+    index = null;
+  }
+  let indexState = "missing";
+  if (index) {
+    indexState = indexesMatch(deriveIndex(projectRoot, index), index) ? "in-sync" : "drifted";
+  }
+
+  // Collected once, then shared: the views render it and `computeActions`
+  // recommends from it, so a recommendation can never disagree with the row
+  // it comes from (change 0037, extended to `next` by change 0064).
+  const coverage = coverageSummary(projectRoot);
+  const trace = traceSummary(projectRoot);
+  const verify = readVerifyConfig(projectRoot);
+
+  return {
+    project: projectName(projectRoot, index),
+    stamp: index?.framework_version ?? null,
+    cli: cliVersion(),
+    indexState,
+    coverage,
+    trace,
+    verify,
+    specs: countSpecs(projectRoot),
+    decisions: countDecisions(projectRoot),
+    skills: countSkills(projectRoot),
+    openChanges: openChanges(projectRoot),
+    adrs: acceptedDecisions(projectRoot),
+    nonGoals: productSection(projectRoot, "Non-goals"),
+    hasNonGoalsSection: hasProductSection(projectRoot, "Non-goals"),
+    // The gate state is already collected above; hand it over so the whole
+    // snapshot stays one read of the tree (change 0037).
+    actions: actions ? computeActions(projectRoot, { coverage, trace, verify }) : [],
+    archive: index?.artifacts?.changes_archive ?? [],
+    // The lane each open change was born in, for the report's mix. Read from
+    // the index rather than re-parsed, so one derivation owns the field.
+    openLanes: (index?.artifacts?.changes ?? []).map((c) => c.lane ?? null),
+    // The archive ledger, parsed (change 0046). The index records WHICH
+    // changes landed; the ledger records what each one touched and when, in
+    // one append-only file — which is what a question like "how often has
+    // this capability moved?" is actually asking about.
+    ledger: readLedger(projectRoot).entries,
+  };
+}
+
+/**
+ * The subset `status --json`, `doctor` and the dashboard have always
+ * published. Kept as its own shape so the JSON envelope does not silently
+ * grow the day a view needs one more field.
+ */
+export function collectStatus(projectRoot) {
+  const s = collectSnapshot(projectRoot, { actions: false });
+  return {
+    project: s.project,
+    stamp: s.stamp,
+    cli: s.cli,
+    indexState: s.indexState,
+    coverage: s.coverage,
+    trace: s.trace,
+    verify: s.verify,
+    specs: s.specs,
+    decisions: s.decisions,
+    skills: s.skills,
+  };
+}
+
+function readVerifyConfig(projectRoot) {
+  const p = path.join(projectRoot, VERIFY_CONFIG_REL);
+  if (!isFile(p)) return { configured: false, checks: 0, invalid: false, signoffs: null };
+  try {
+    const cfg = JSON.parse(read(p));
+    const checks = Array.isArray(cfg?.checks) ? cfg.checks : [];
+    // Executed proof and SIGNED proof are different claims (change 0039), and
+    // a report that adds them together hides which is which. The counts ride
+    // along so every view can say so without loading the sign-off store
+    // itself.
+    const signoffs = summarizeSignoffs(projectRoot, checks);
+    return { configured: true, checks: checks.length, invalid: false, signoffs };
+  } catch {
+    return { configured: true, checks: 0, invalid: true, signoffs: null };
+  }
+}
+
+/** 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 ? parseChangeTitle(proposal) : null;
+    const status = proposal ? (listHeader(proposal, "Status") ?? "proposed") : "no proposal.md";
+    const tasksPath = path.join(changesDir, id, "tasks.md");
+    // One counter for every surface (change 0067). This one used to require
+    // TEXT after the box, so the scaffold's empty placeholders were invisible
+    // and `prime` reported "tasks 0/3" for a change with six open boxes.
+    const progress = isFile(tasksPath)
+      ? checklistProgress(read(tasksPath))
+      : { total: 0, done: 0, open: [], placeholders: 0 };
+    const tasksTotal = progress.total;
+    const tasksDone = progress.done;
+    const unchecked = progress.open.map((t) => t || "(unwritten task — the scaffold's placeholder)");
+    out.push({ id, title, status, tasksDone, tasksTotal, unchecked });
+  }
+  return out;
+}
+
+function countSpecs(projectRoot) {
+  const specsDir = path.join(projectRoot, ".doctrina", "specs");
+  const impl = {};
+  let total = 0;
+  if (isDir(specsDir)) {
+    for (const cap of readdirSync(specsDir).sort()) {
+      const p = path.join(specsDir, cap, "spec.md");
+      if (!isFile(p)) continue;
+      total += 1;
+      const implRaw = specHeader(read(p), "Implementation");
+      if (implRaw) {
+        const word = implRaw.trim().split(/[\s—-]+/)[0].toLowerCase();
+        impl[word] = (impl[word] ?? 0) + 1;
+      }
+    }
+  }
+  const changesDir = path.join(projectRoot, ".doctrina", "changes");
+  let open = 0;
+  if (isDir(changesDir)) {
+    for (const e of readdirSync(changesDir)) {
+      if (e === "archive" || e.startsWith(".")) continue;
+      if (isDir(path.join(changesDir, e))) open += 1;
+    }
+  }
+  return { total, impl, openChanges: open };
+}
+
+function countDecisions(projectRoot) {
+  const adrDir = path.join(projectRoot, ".doctrina", "decisions");
+  let total = 0, proposed = 0, bare = 0;
+  const isBare = (v) => {
+    const t = (v ?? "").trim();
+    return t === "" || t === "—" || t === "-";
+  };
+  if (isDir(adrDir)) {
+    for (const f of walk(adrDir)) {
+      if (!/^\d{4}-.+\.md$/.test(path.basename(f))) continue;
+      total += 1;
+      const text = read(f);
+      const status = (listHeader(text, "Status") ?? "").toLowerCase();
+      if (status === "proposed") proposed += 1;
+      if (status === "accepted") {
+        const evidence = listHeader(text, "Evidence");
+        const landed = listHeader(text, "Landed");
+        if (evidence !== null && isBare(evidence) && isBare(landed)) bare += 1;
+      }
+    }
+  }
+  return { total, proposed, bare };
+}
+
+function countSkills(projectRoot) {
+  const skillsDir = path.join(projectRoot, ".doctrina", "skills");
+  if (!isDir(skillsDir)) return 0;
+  return walk(skillsDir).filter((f) => f.endsWith(".md")).length;
+}
+
+/**
+ * Everything the period digest reads beyond the snapshot, for a window of
+ * `days`. ONE collector for every door that renders the digest: `report`
+ * passed the metrics and `status --view report` did not, so the view that
+ * promised "never different numbers" printed two lines fewer (change 0176).
+ *
+ * @param {string} projectRoot
+ * @param {number} days
+ */
+export function collectReportWindow(projectRoot, days) {
+  return {
+    days,
+    cutoffIso: windowCutoff(days),
+    git: gitWindow(projectRoot, days),
+    gitState: historyState(projectRoot),
+    metrics: collectMetrics(projectRoot, `${days} days ago`),
+  };
+}

package/src/lib/spec-ops.js

@@ -1,4 +1,5 @@
 // @ts-check
+import { commentRanges, isInsideComment } from "./doc-model.js";
 // Structured spec operations (ADR 0007 / review F3). A MODIFIED spec delta
 // historically carried prose ("flip criterion 2 to verified", "bump to
 // 0.3.0") that a human merged by hand — the single most error-prone step in
@@ -39,6 +40,40 @@
 const HEADER_RE = (name) =>
   new RegExp(`^(\\s*(?:-\\s+)?\\*\\*${escapeRe(name)}:\\*\\*)\\s*(.*)$`, "m");
 
+// The ENUMS behind the two machine-read headers and the criterion mark
+// (change 0102). `--version` and `--bump` always validated their input;
+// `--status`, `--implementation` and `--criterion` wrote whatever string they
+// were given, synced it into the index, and `validate` passed it — so a spec
+// could say `Status: bogus` and `prime` would report "1 banana" without
+// finding anything odd. A header every gate branches on has a domain, and
+// this is it. A note after the state word stays legal ("planned — deferred,
+// see ADR 0007"): only the WORD is checked.
+export const STATUS_VALUES = ["draft", "active", "deprecated"];
+export const IMPLEMENTATION_VALUES = ["planned", "partial", "implemented", "verified"];
+export const CRITERION_MARKS = ["verified", "unverified", "orchestration"];
+
+/** The state word of a header/mark value: the first token, note stripped. */
+export function stateWord(value) {
+  const first = String(value ?? "").trim().split(/\s+/)[0] ?? "";
+  return first.replace(/[—:-]+$/, "").toLowerCase();
+}
+
+/** null when `value` is a legal value for `name`; otherwise the error text. */
+export function headerValueError(name, value) {
+  const allowed = name === "Status" ? STATUS_VALUES : name === "Implementation" ? IMPLEMENTATION_VALUES : null;
+  if (!allowed) return null;
+  const word = stateWord(value);
+  if (allowed.includes(word)) return null;
+  return `${name} must be one of ${allowed.join("|")} (got "${String(value).trim()}") — a note may follow the value, the value itself does not change`;
+}
+
+/** null when `mark` is a legal criterion mark; otherwise the error text. */
+export function criterionMarkError(mark) {
+  const word = stateWord(mark);
+  if (CRITERION_MARKS.includes(word)) return null;
+  return `a criterion mark must be one of ${CRITERION_MARKS.join("|")} (got "${String(mark).trim()}")`;
+}
+
 function escapeRe(s) {
   return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 }
@@ -71,11 +106,8 @@ export function extractOps(deltaText) {
 // contain a comment (an `<!-- illustrative -->` marker inside an
 // append-criterion landed in the spec with the marker silently gutted).
 function matchOpsBlock(text) {
-  const commentRanges = [];
-  for (const m of text.matchAll(/<!--[\s\S]*?-->/g)) {
-    commentRanges.push([m.index, m.index + m[0].length]);
-  }
-  const insideComment = (offset) => commentRanges.some(([a, b]) => offset >= a && offset < b);
+  const ranges = commentRanges(text);
+  const insideComment = (offset) => isInsideComment(ranges, offset);
 
   const fenceRe = /^[ \t]*```[ \t]*ops[ \t]*\r?\n([\s\S]*?)^[ \t]*```[ \t]*$/gm;
   let m;
@@ -219,6 +251,15 @@ export function setHeader(text, name, value) {
   if (!re.test(text)) {
     return { error: `set-header: no "**${name}:**" header in the spec to set` };
   }
+  // The domain is the SPEC's (bare bold header). The list form
+  // (`- **Status:** proposed`) is a proposal's or an ADR's, whose Status
+  // has a lifecycle of its own (proposed -> applied, accepted, superseded).
+  const listForm = /^\s*-/.test(text.match(re)?.[1] ?? "");
+  const domain = listForm ? null : headerValueError(name, value);
+  // `cause: "argument"` marks an error about the value supplied, not about
+  // the document: `spec set` answers it as USAGE, a delta as a defect of
+  // the work (ADR 0018).
+  if (domain) return { error: `set-header: ${domain}`, cause: "argument" };
   const next = text.replace(re, (_m, prefix) => `${prefix} ${value}`.replace(/\s+$/, ""));
   return { text: next, summary: `set ${name}: ${value}` };
 }
@@ -271,8 +312,10 @@ export function setCriterionMark(text, n, markRaw) {
   const loc = locateCriteria(text);
   if (!loc) return { error: "set-criterion: spec has no '## Acceptance criteria' section" };
   const item = loc.items.find((it) => it.n === n);
-  if (!item) return { error: `set-criterion: no criterion #${n} found` };
+  if (!item) return { error: `set-criterion: no criterion #${n} found`, cause: "argument" };
   const mark = markRaw.replace(/^\[|\]$/g, "").trim();
+  const domain = criterionMarkError(mark);
+  if (domain) return { error: `set-criterion: ${domain}`, cause: "argument" };
   const line = loc.lines[item.lineIndex];
   let next;
   if (/\[[^\]]*\]/.test(line)) {
@@ -441,8 +484,24 @@ export function replaceRequirement(text, section, n, value) {
   if (n > real.length) {
     return { error: `replace-requirement: section "${section}" has ${real.length} requirement${real.length === 1 ? "" : "s"}, no #${n}` };
   }
-  const indent = loc.lines[real[n - 1]].match(/^(\s*)/)[1];
-  loc.lines[real[n - 1]] = `${indent}- ${value}`;
+  // REPLACE THE WHOLE ITEM, continuation lines included.
+  //
+  // Writing only the first line leaves the old bullet's wrapped prose sitting
+  // under the new one, indented, reading as part of it. That is not cosmetic:
+  // the orphan is the PREVIOUS version of the requirement, so the spec ends up
+  // stating a contract and then contradicting it two lines later, and a spec
+  // is the one artifact this framework asks everyone to trust.
+  //
+  // It had already happened four times in this repository's own tree before
+  // anyone noticed — twice in `gates` (a closing sequence missing its review
+  // and runtime steps, a doctor set missing its runtime row) and once in
+  // `insight`, all three describing older behaviour beside the current one.
+  //
+  // `append-requirement` learned this in 0.13.0 and got `endOfItem`; this verb
+  // was written afterwards and never picked it up.
+  const start = real[n - 1];
+  const indent = loc.lines[start].match(/^(\s*)/)[1];
+  loc.lines.splice(start, endOfItem(loc.lines, start) - start + 1, `${indent}- ${value}`);
   return { text: loc.lines.join("\n"), summary: `replace-requirement ${section} ${n}` };
 }
 
@@ -454,6 +513,11 @@ export function appendCriterion(text, value) {
   if (loc.items.length === 0) {
     return { error: "append-criterion: no existing numbered criterion to append after" };
   }
+  const leadingMark = String(value).match(/^\s*\[([^\]]*)\]/);
+  if (leadingMark) {
+    const domain = criterionMarkError(leadingMark[1]);
+    if (domain) return { error: `append-criterion: ${domain}` };
+  }
   const last = loc.items[loc.items.length - 1];
   const nextN = Math.max(...loc.items.map((it) => it.n)) + 1;
   loc.lines.splice(endOfItem(loc.lines, last.lineIndex) + 1, 0, `${last.indent}${nextN}. ${value}`);

package/src/lib/templates-model.js

@@ -0,0 +1,289 @@
+// @ts-check
+// The template-shape FINDINGS.
+//
+// `doctor` reports these as one of its rows and used to import them out of
+// `commands/templates.js` (audit finding F7). Collecting is not rendering, so
+// the collection lives here and both surfaces read it.
+import path from "node:path";
+import { exists, isDir, isFile, lineCount, read, relPath, walk, write } from "./fs-ops.js";
+import { adapterFiles, isHubPointer, listAdapterNames } from "./adapters.js";
+import { readTemplate } from "./templates.js";
+import { PLAYBOOKS } from "./playbook.js";
+import { COMMAND_META, COMMAND_NAMES, DEPRECATED, REMOVED, SURFACE_LINE_BUDGET, surfaceBlock, surfaceMarkdown, findSurfaceBlock } from "./commands.js";
+import { declaredBudget } from "./runtime.js";
+import { agentsMdBudget } from "./validation-model.js";
+/**
+ * The surface-block budget: how many lines the generated block spends, the
+ * ceiling it spends them against, and what is left.
+ *
+ * This number is COUPLED to `agents-md-lines`: the block is written into
+ * AGENTS.md, so one command added to the catalog spends a line of both.
+ * Every caller that reports on it reads it HERE, so `templates check` and
+ * `doctor` can never quote two different sizes for one block — the second
+ * count is how the two AGENTS.md numbers drifted before change 0059, and
+ * this budget had no owner at all until 0072.
+ *
+ * @param {string|null} [projectRoot] The project whose contract may declare
+ *   the ceiling; omit to measure against the shipped default alone.
+ * @returns {{ used: number, budget: number, slack: number, declared: boolean }}
+ */
+export function surfaceBudget(projectRoot = null) {
+  const used = surfaceMarkdown().split("\n").length;
+  const { value: budget, declared } = projectRoot
+    ? declaredBudget(projectRoot, "surface-block-lines", SURFACE_LINE_BUDGET)
+    : { value: SURFACE_LINE_BUDGET, declared: false };
+  return { used, budget, slack: budget - used, declared };
+}
+
+// What one appended stub section costs AGENTS.md: a blank line, the heading,
+// a blank line and the fill-me comment. Kept beside the writer that emits
+// that shape (`templates update --write`) so the estimate and the write
+// cannot drift.
+export const STUB_SECTION_LINES = 4;
+
+/**
+ * What appending stub sections to AGENTS.md would cost, against what the
+ * file has left of its declared ceiling.
+ *
+ * `templates check` recommends the sections and `agents-md-lines` caps the
+ * file, and the two never spoke: following the recommendation on this very
+ * repository took AGENTS.md from 147 to 155 lines, past a ceiling `analyze`
+ * refuses to raise because the budget is declared OUTPUT. A recommendation
+ * that cannot say what it costs is a recommendation that sends you into
+ * another gate's refusal (change 0078).
+ *
+ * @param {string} projectRoot
+ * @param {string[]} missing The recommended headings AGENTS.md does not have.
+ * @returns {{ cost: number, slack: number, fits: boolean, over: number }}
+ */
+export function agentsSectionCost(projectRoot, missing) {
+  const cost = missing.length * STUB_SECTION_LINES;
+  const { slack } = agentsMdBudget(projectRoot);
+  return { cost, slack, fits: cost <= slack, over: Math.max(0, cost - slack) };
+}
+// Recommended sections per file kind. Adopters whose files lack these
+// headings get a warning from `templates check`; they are recommendations,
+// not hard requirements (validate handles the hard requirements).
+export const AGENTS_SECTIONS = [
+  "## Stack",
+  "## Commands",
+  "## Repository structure",
+  "## Conventions and boundaries",
+  "## How to read context",
+];
+export const INDEX_FIELDS = ["$schema_version", "project", "artifacts"];
+export const PRODUCT_SECTIONS = [
+  "## Vision",
+  "## Problem",
+  "## Target users",
+  "## Scope",
+  "## Success criteria",
+];
+
+// The first deprecated or removed operation a text tells you to run, as
+// `doctrina <op>`, or null.
+function retiredCommandIn(text) {
+  for (const op of [...Object.keys(DEPRECATED), ...Object.keys(REMOVED)]) {
+    const name = op.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    if (new RegExp(`doctrina ${name}(?![a-z-])`).test(text)) return op;
+  }
+  return null;
+}
+
+// The findings `templates check` reports, as structured records with an
+// executable remedy. Exported so a test can seed each finding, run the
+// remedy it names, and assert the finding clears — a remedy that cannot
+// resolve its own finding is not a remedy (C2).
+export function collectFindings(projectRoot) {
+  const findings = [];
+  const ok = [];
+
+
+  // AGENTS.md sections
+  const agentsPath = path.join(projectRoot, "AGENTS.md");
+  if (isFile(agentsPath)) {
+    const text = read(agentsPath);
+    const missingSections = AGENTS_SECTIONS.filter((h) => !hasHeading(text, h));
+    const budget = agentsSectionCost(projectRoot, missingSections);
+    for (const heading of AGENTS_SECTIONS) {
+      if (hasHeading(text, heading)) {
+        ok.push(`AGENTS.md: ${heading}`);
+        continue;
+      }
+      // The recommendation names its price. When the stubs do not fit, the
+      // remedy names the CUT first — appending them anyway would clear this
+      // finding by breaching a ceiling `analyze` refuses to raise, which is
+      // one gate sending you into another's refusal.
+      findings.push({
+        message: `AGENTS.md missing recommended section "${heading}"` +
+          (budget.fits
+            ? ``
+            : ` — the ${missingSections.length} missing stub(s) cost ${budget.cost} lines and ` +
+              `AGENTS.md has ${budget.slack} left of its declared ceiling`),
+        remedy: budget.fits
+          ? "doctrina upgrade --write"
+          : `cut ${budget.over} line(s) of prose from AGENTS.md, then \`doctrina upgrade --write\``,
+      });
+    }
+    // Command-surface block: present and current vs the installed catalog.
+    const block = findSurfaceBlock(text);
+    if (!block) {
+      findings.push({ message: "AGENTS.md has no doctrina:surface block — agents discover commands through this file", remedy: "doctrina upgrade --write" });
+    } else if (normalizeBlock(text.slice(block.start, block.end)) !== normalizeBlock(surfaceBlock())) {
+      findings.push({ message: "AGENTS.md doctrina:surface block is stale vs the installed CLI", remedy: "doctrina upgrade --write" });
+    } else {
+      ok.push("AGENTS.md: doctrina:surface block current");
+    }
+  } else {
+    findings.push({ message: "AGENTS.md missing at project root", remedy: "doctrina init --force" });
+  }
+
+  // product.md sections
+  const productPath = path.join(projectRoot, ".doctrina", "product.md");
+  if (isFile(productPath)) {
+    const text = read(productPath);
+    for (const heading of PRODUCT_SECTIONS) {
+      if (hasHeading(text, heading)) ok.push(`product.md: ${heading}`);
+      else findings.push({ message: `.doctrina/product.md missing recommended section "${heading}"`, remedy: "doctrina upgrade --write" });
+    }
+  } else {
+    findings.push({ message: ".doctrina/product.md missing", remedy: "doctrina init --force" });
+  }
+
+  // Installed agent adapters: a HUB POINTER file must still reference
+  // AGENTS.md (that is why one `upgrade --write` refresh of the hub reaches
+  // every installed agent). Only files whose template declares the
+  // {{AGENTS_MD_PATH}} token are pointers; a slash-command shim reaches the
+  // hub through its parent pointer file and is not checked (C2).
+  for (const name of listAdapterNames(projectRoot)) {
+    const spec = adapterFiles(projectRoot, name);
+    if (!spec) continue;
+    for (const file of spec.files) {
+      const installed = path.join(projectRoot, file.relativePath);
+      if (!isFile(installed)) continue; // not installed — nothing to check
+      if (!isHubPointer(file)) {
+        // A command shim is copied into the project once, so an upgrade
+        // of the CLI leaves it teaching whatever the CLI taught then: the
+        // 0.16 `/doctrina-work` still ran `analyze` → `change apply` after
+        // 0.17 deprecated one and handed the other to the close (change
+        // 0187). A shim naming a retired command is stale; the same rewrite
+        // from the template that repairs a pointer repairs it.
+        const retired = retiredCommandIn(read(installed));
+        if (retired) {
+          findings.push({
+            message: `adapter ${file.relativePath} still teaches \`doctrina ${retired}\`, which this CLI ${DEPRECATED[retired] ? "deprecated" : "removed"} — the agent running it follows the old flow`,
+            remedy: `doctrina adapter add ${name} --force`,
+          });
+        } else {
+          ok.push(`adapter ${file.relativePath}: teaches live commands only`);
+        }
+        continue;
+      }
+      if (read(installed).includes("AGENTS.md")) {
+        ok.push(`adapter ${file.relativePath}: points at AGENTS.md`);
+      } else {
+        findings.push({
+          message: `adapter ${file.relativePath} no longer references AGENTS.md — agents loading it will miss the hub`,
+          // Executable and verified: `adapter add --force` rewrites exactly
+          // this file from its template. A remedy that cannot resolve the
+          // finding it is attached to is not a remedy (C2).
+          remedy: `doctrina adapter add ${name} --force`,
+        });
+      }
+    }
+  }
+
+  // M2: a command that cannot state its trigger has not earned a place on
+  // the surface. The block is an agent's only discovery surface, so both
+  // fields are required and the block has a declared size budget.
+  for (const name of COMMAND_NAMES) {
+    const meta = COMMAND_META[name];
+    if (!meta || !meta.purpose || !meta.when) {
+      findings.push({
+        message: `command "${name}" declares no ${!meta ? "purpose or when" : (!meta.purpose ? "purpose" : "when")} — the surface block cannot say when to reach for it`,
+        remedy: null,
+      });
+    }
+  }
+  const surface = surfaceBudget(projectRoot);
+  if (surface.used > surface.budget) {
+    findings.push({
+      message: `the generated surface block is ${surface.used} lines (budget ${surface.budget}) — cut commands rather than raising the budget`,
+      remedy: null,
+    });
+  } else {
+    ok.push(`surface block within budget (${surface.used}/${surface.budget} lines)`);
+  }
+
+  // index.json schema fields
+  const indexPath = path.join(projectRoot, ".doctrina", "index.json");
+  if (isFile(indexPath)) {
+    try {
+      const idx = JSON.parse(read(indexPath));
+      for (const field of INDEX_FIELDS) {
+        if (idx[field] !== undefined) ok.push(`index.json: ${field}`);
+        else findings.push({ message: `.doctrina/index.json missing field "${field}"`, remedy: "doctrina upgrade --write" });
+      }
+      if (idx.$schema_version && idx.$schema_version !== "0.1.0") {
+        findings.push({ message: `.doctrina/index.json $schema_version is "${idx.$schema_version}" (expected "0.1.0")`, remedy: null });
+      }
+    } catch (err) {
+      findings.push({ message: `.doctrina/index.json failed to parse: ${err.message}`, remedy: null });
+    }
+  } else {
+    findings.push({ message: ".doctrina/index.json missing", remedy: "doctrina index rebuild" });
+  }
+
+  // Output
+  // The playbooks (change 0038). A playbook is the procedure the agent
+  // actually executes, and since it became a template an adopter can replace
+  // it — which means it can also be MISSING or malformed, and a playbook that
+  // does not render is a broken session, not a cosmetic gap. Each is checked
+  // for resolution and for the shape every playbook must have: a title line
+  // and the ordered steps.
+  for (const name of PLAYBOOKS) {
+    const rel = `playbooks/${name}.md.template`;
+    let body = null;
+    try {
+      body = readTemplate(projectRoot, rel).body;
+    } catch {
+      body = null;
+    }
+    if (body === null) {
+      findings.push({
+        message: `playbook "${name}" does not resolve (${rel} is missing from the project AND the installed CLI)`,
+        remedy: "reinstall doctrina-cli, or restore .doctrina/templates/" + rel,
+      });
+      continue;
+    }
+    const problems = [];
+    if (body.trim() === "") problems.push("it is empty");
+    if (!/^\s*1\./m.test(body)) problems.push("it has no numbered first step");
+    for (const [open, close] of [["[[c]]", "[[/c]]"], ["[[g]]", "[[/g]]"], ["[[b]]", "[[/b]]"], ["[[y]]", "[[/y]]"]]) {
+      const opens = body.split(open).length - 1;
+      const closes = body.split(close).length - 1;
+      if (opens !== closes) problems.push(`${opens} ${open} spans but ${closes} ${close}`);
+    }
+    if (problems.length > 0) {
+      findings.push({
+        message: `playbook "${name}" is malformed: ${problems.join("; ")}`,
+        remedy: `fix .doctrina/templates/${rel}, or delete it to fall back to the bundled playbook`,
+      });
+    } else {
+      ok.push(`playbook: ${name}`);
+    }
+  }
+
+  return { findings, ok };
+}
+
+export function normalizeBlock(s) {
+  return s.replace(/\r\n/g, "\n").replace(/[ \t]+$/gm, "").trim();
+}
+
+export function hasHeading(text, heading) {
+  // Match an exact h2 heading at line start (case-insensitive for the body
+  // after "## ", so "## Vision" matches "## VISION" or "## vision" too).
+  const escaped = heading.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  return new RegExp(`^${escaped}\\b`, "im").test(text);
+}