doctrina-cli 0.15.1 → 0.16.0

package/src/commands/skill.js

@@ -2,7 +2,6 @@
 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 { readTemplate, locateTemplatesDir, substitute } from "../lib/templates.js";
 import * as idx from "../lib/index-json.js";
@@ -11,6 +10,10 @@ import { flagBool, flagString, flagGivenWithoutValue } from "../lib/args.js";
 import { c } from "../lib/colors.js";
 import { suggest } from "../lib/suggest.js";
 import { notADoctrinaProject } from "../lib/exit-codes.js";
+import { parseFrontmatter } from "../lib/doc-model.js";
+import { git, GIT_STATE } from "../lib/git.js";
+import { FIX_SHAPED, FIX_SHAPED_SUBJECT } from "../lib/lexicon.js";
+import { artifactNameError } from "../lib/names.js";
 
 const SUBCOMMANDS = ["new", "list", "sync", "suggest"];
 
@@ -46,15 +49,7 @@ export async function run(positional, flags) {
 // --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.
@@ -379,8 +374,8 @@ function gitFixCommits(projectRoot, { since, limit }) {
   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 r = git(projectRoot, args);
+  if (r.state !== GIT_STATE.OK || !r.stdout) return [];
 
   /** @type {SkillCandidate[]} */
   const out = [];
@@ -449,8 +444,9 @@ function firstWhyLine(proposalText) {
 
 function skillNew(args, flags) {
   const name = args[0];
-  if (!name || !/^[a-z][a-z0-9-]*$/.test(name)) {
-    console.error(c.red("error:") + " skill name must be lowercase letters, digits, or hyphens (e.g. \"db-migration\")");
+  const nameError = artifactNameError(name, "skill name");
+  if (nameError) {
+    console.error(c.red("error:") + ` ${nameError} (e.g. "db-migration")`);
     return 2;
   }
   const force = flagBool(flags, "force", false);
@@ -512,6 +508,13 @@ function skillSync() {
       console.log(c.yellow("skip   ") + ` ${id} (no description frontmatter)`);
       continue;
     }
+    // A description still in the template's `<...>` form is not "up to
+    // date" (change 0111): it is a file nobody wrote yet, and mirroring it
+    // into the index is what put the placeholder in every context pack.
+    if (/^<[^<>]*>$/.test(desc.trim())) {
+      console.log(c.yellow("scaffold") + ` ${id} — description is still the scaffold's placeholder; write description/when, then sync`);
+      continue;
+    }
     const entry = (index.artifacts.skills ?? []).find((s) => s.id === id);
     if (!entry) {
       idx.addSkill(index, {
@@ -568,15 +571,6 @@ function skillList() {
   return 0;
 }
 
-function parseFrontmatter(text, key) {
-  // Match frontmatter blocks bounded by `---` lines at start of file.
-  const fmMatch = text.match(/^---\s*\n([\s\S]*?)\n---\s*\n/);
-  if (!fmMatch) return null;
-  const block = fmMatch[1];
-  const lineRe = new RegExp(`^${key}\\s*:\\s*(.+)$`, "m");
-  const m = block.match(lineRe);
-  return m ? m[1].trim() : null;
-}
 
 function ensureDoctrinaProject(projectRoot) {
   if (!exists(path.join(projectRoot, ".doctrina"))) {
@@ -618,6 +612,3 @@ Skills are written by humans, not generated. See docs/en/skills.md
 for the design rationale and the distinction from specs / AGENTS.md /
 the rejected memory/ folder.
 `;
-
-// Re-export the frontmatter parser so validate.js can reuse it.
-export { parseFrontmatter };

package/src/commands/spec.js

@@ -11,7 +11,9 @@ import { today } from "../lib/dates.js";
 import { flagBool, flagString } from "../lib/args.js";
 import { c } from "../lib/colors.js";
 import { suggest } from "../lib/suggest.js";
-import { notADoctrinaProject } from "../lib/exit-codes.js";
+import { notADoctrinaProject, EXIT } from "../lib/exit-codes.js";
+import { derivedImplementations } from "../lib/coverage-model.js";
+import { artifactNameError } from "../lib/names.js";
 
 const SUBCOMMANDS = ["new", "list", "set"];
 
@@ -34,8 +36,9 @@ export async function run(positional, flags) {
   if (sub === "set") return specSet(positional.slice(1), flags);
 
   const capability = positional[1];
-  if (!capability || !/^[a-z][a-z0-9-]*$/.test(capability)) {
-    console.error(c.red("error:") + " capability must be lowercase letters, digits, or hyphens (e.g. \"core\", \"templates\").");
+  const nameError = artifactNameError(capability, "capability");
+  if (nameError) {
+    console.error(c.red("error:") + ` ${nameError} (e.g. "core", "templates")`);
     return 2;
   }
 
@@ -135,7 +138,7 @@ function specSet(args, flags) {
   const specPath = path.join(projectRoot, ".doctrina", "specs", capability, "spec.md");
   if (!isFile(specPath)) {
     console.error(c.red("error:") + ` no spec at ${relPath(projectRoot, specPath)} (create it with \`doctrina spec new ${capability}\`)`);
-    return 1;
+    return EXIT.USAGE;
   }
 
   const impl = flagString(flags, "implementation");
@@ -159,7 +162,25 @@ function specSet(args, flags) {
   // Order: headers, then version, then criterion — independent edits, all or
   // none (a failed op leaves the spec untouched, like `change apply`).
   if (status !== undefined) apply(setHeader(text, "Status", status));
-  if (impl !== undefined) apply(setHeader(text, "Implementation", impl));
+  if (impl !== undefined) {
+    // `--implementation auto` reads the value off the coverage arithmetic
+    // instead of the author's memory (audit finding F10): coverage already
+    // knows how many of this spec's criteria cite proof that resolves, and
+    // that is the definition of "verified". A spec with no acceptance
+    // criteria has nothing to derive from, so `auto` refuses rather than
+    // guessing — the spec is left untouched, like any other failed op.
+    if (String(impl).trim().toLowerCase() === "auto") {
+      const derivedValue = derivedImplementations(projectRoot, { only: new Set([capability]) })
+        .get(capability)?.derived;
+      if (!derivedValue) {
+        errors.push(`--implementation auto needs acceptance criteria to derive from; ${capability} declares none`);
+      } else {
+        apply(setHeader(text, "Implementation", derivedValue));
+      }
+    } else {
+      apply(setHeader(text, "Implementation", impl));
+    }
+  }
   if (bump !== undefined) {
     if (!["major", "minor", "patch"].includes(bump)) errors.push(`--bump needs major|minor|patch (got "${bump}")`);
     else apply(bumpVersion(text, bump));

package/src/commands/status.js

@@ -1,27 +1,27 @@
 // @ts-check
 import path from "node:path";
 import process from "node:process";
-import { readdirSync } from "node:fs";
-import { exists, isDir, isFile, read, walk } from "../lib/fs-ops.js";
-import * as idx from "../lib/index-json.js";
-import { deriveIndex, indexesMatch, specHeader, listHeader } from "../lib/scan.js";
-import { cliVersion } from "../lib/version.js";
-import { summarize as coverageSummary } from "./coverage.js";
-import { summarize as traceSummary } from "./trace.js";
-import { flagBool } from "../lib/args.js";
+import { exists } from "../lib/fs-ops.js";
+import { flagBool, flagString } from "../lib/args.js";
 import { c } from "../lib/colors.js";
 import { emitJson } from "../lib/json-out.js";
 import { notADoctrinaProject } from "../lib/exit-codes.js";
+import { collectSnapshot, collectStatus } from "../lib/snapshot.js";
+import { renderView, VIEWS } from "../lib/views.js";
+import { gitWindow, historyState, windowCutoff } from "../lib/git.js";
+import { suggest } from "../lib/suggest.js";
 
 // One-glance project health (review 2026-06-27 passive-user feature #1): a
 // dashboard that answers "where do things stand?" in a single read, so neither
 // the human nor the agent has to run validate + coverage + trace + next
-// separately. Strictly read-only; never mutates and always exits 0. It reports
-// the gate signals it can compute cheaply (index drift, the framework stamp,
-// coverage/trace ratios, whether verify is configured) and the artifact counts;
-// `doctrina validate` / `verify` remain the full, authoritative gates.
-
-const CONFIG_REL = ".doctrina/verify.json";
+// separately. Strictly read-only; never mutates and always exits 0.
+//
+// Since change 0037 this is also the HOME of the other read-only views:
+// `--view prime|handoff|report` renders the same snapshot in a different
+// shape. `prime`, `handoff` and `report` remain as their own commands (they
+// are what AGENTS.md tells an agent to run) and delegate straight here, so
+// there is one collector, one set of formatters, and no way for the four to
+// report different numbers (audit finding F7).
 
 // Flags this command accepts. Declared HERE, with the command, so
 // adding a command never requires editing the entrypoint — the gap that
@@ -30,7 +30,7 @@ const CONFIG_REL = ".doctrina/verify.json";
 // wrap it in the generic envelope.
 export const jsonNative = true;
 
-export const flags = { boolean: ["json"], string: [] };
+export const flags = { boolean: ["json"], string: ["view", "since"] };
 
 export async function run(_positional, flags) {
   const projectRoot = process.cwd();
@@ -38,173 +38,42 @@ export async function run(_positional, flags) {
     throw notADoctrinaProject();
   }
 
-  const s = collectStatus(projectRoot);
+  const view = flagString(flags, "view") ?? "dashboard";
+  if (!VIEWS.includes(view)) {
+    console.error(c.red("error:") + ` unknown view "${view}"`);
+    const guess = suggest(view, VIEWS);
+    console.error(c.gray("hint: ") + (guess ? `did you mean --view ${guess}?` : `available: ${VIEWS.join(", ")}`));
+    return 2;
+  }
 
+  // --json always answers with the status shape, whatever the view: the
+  // envelope is a machine contract and must not change with a formatting flag.
   if (flagBool(flags, "json", false)) {
-    emitJson("status", s);
+    emitJson("status", collectStatus(projectRoot));
     return 0;
   }
 
-  console.log(c.bold("Doctrina status") + c.gray(` — ${s.project}  (framework ${s.stamp ?? "—"} / CLI ${s.cli})`));
-  console.log("");
-
-  // --- Gates ---
-  console.log(c.bold("  Gates"));
-  let driftLine;
-  if (s.indexState === "missing") {
-    driftLine = c.red("missing/unreadable") + c.gray(" — run `doctrina index rebuild`");
-  } else if (s.indexState === "in-sync") {
-    driftLine = c.green("in sync");
-  } else {
-    driftLine = c.yellow("drifted") + c.gray(" — run `doctrina validate --fix`");
-  }
-  console.log(`    ${"index".padEnd(11)} ${driftLine}`);
-
-  const stampLine = s.stamp === s.cli
-    ? c.green("current")
-    : c.yellow(`${s.stamp ?? "—"} (CLI ${s.cli})`) + c.gray(" — `doctrina index rebuild`");
-  console.log(`    ${"stamp".padEnd(11)} ${stampLine}`);
-
-  const cov = s.coverage;
-  const covExtra = cov.totalDangling + cov.totalConditional > 0
-    ? c.yellow(` ${cov.totalDangling} dangling, ${cov.totalConditional} conditional`)
-    : "";
-  const covColor = cov.pct === 100 ? c.green : cov.pct >= 50 ? c.yellow : c.red;
-  console.log(`    ${"coverage".padEnd(11)} ${covColor(`${cov.pct}%`)} ${c.gray(`(${cov.totalCovered}/${cov.totalCriteria} criteria)`)}${covExtra}`);
-
-  const tr = s.trace;
-  const trExtra = tr.untraceable + tr.dropped + tr.dangling > 0
-    ? c.yellow(` ${tr.dropped} dropped, ${tr.untraceable} untraceable`)
-    : "";
-  const trColor = tr.anchors === 0 ? c.gray : (tr.realized === tr.anchors && tr.untraceable === 0 ? c.green : c.yellow);
-  const trText = tr.anchors === 0 ? "no anchors" : `${tr.realized}/${tr.anchors} anchors`;
-  console.log(`    ${"trace".padEnd(11)} ${trColor(trText)}${trExtra}`);
-
-  let verifyLine = c.gray("not configured") + c.gray(" — `doctrina verify --init`");
-  if (s.verify.invalid) {
-    verifyLine = c.red("invalid JSON");
-  } else if (s.verify.configured) {
-    const n = s.verify.checks;
-    verifyLine = c.cyan(`${n} check${n === 1 ? "" : "s"}`) + c.gray(" — run `doctrina verify`");
-  }
-  console.log(`    ${"verify".padEnd(11)} ${verifyLine}`);
-
-  // --- Work ---
-  console.log("");
-  console.log(c.bold("  Work"));
-  const implBreak = Object.entries(s.specs.impl).map(([k, v]) => `${v} ${k}`).join(", ");
-  console.log(`    ${"specs".padEnd(11)} ${s.specs.total}${implBreak ? c.gray(`  (${implBreak})`) : ""}`);
-  console.log(`    ${"changes".padEnd(11)} ${s.specs.openChanges} open`);
-  const adrNotes = [];
-  if (s.decisions.proposed > 0) adrNotes.push(c.yellow(`${s.decisions.proposed} proposed`));
-  if (s.decisions.bare > 0) adrNotes.push(c.yellow(`${s.decisions.bare} unproven`));
-  console.log(`    ${"decisions".padEnd(11)} ${s.decisions.total}${adrNotes.length ? c.gray("  (") + adrNotes.join(c.gray(", ")) + c.gray(")") : ""}`);
-  console.log(`    ${"skills".padEnd(11)} ${s.skills}`);
-
-  console.log("");
-  console.log(c.gray("  Full gates: `doctrina validate` · `doctrina verify`.  Next step: `doctrina next`."));
-  return 0;
-}
-
-// Pure, render-free status snapshot — the data behind the dashboard, shared
-// with `prime`, `handoff`, `doctor`, and the `--json` output so every consumer
-// reads the same numbers.
-export function collectStatus(projectRoot) {
-  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";
-  }
-
-  const verifyCfg = path.join(projectRoot, CONFIG_REL);
-  let verify = { configured: false, checks: 0, invalid: false };
-  if (isFile(verifyCfg)) {
-    try {
-      const cfg = JSON.parse(read(verifyCfg));
-      verify = { configured: true, checks: Array.isArray(cfg?.checks) ? cfg.checks.length : 0, invalid: false };
-    } catch {
-      verify = { configured: true, checks: 0, invalid: true };
+  const options = {};
+  if (view === "report") {
+    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;
     }
+    options.days = days;
+    options.cutoffIso = windowCutoff(days);
+    options.git = gitWindow(projectRoot, days);
+    options.gitState = historyState(projectRoot);
   }
 
-  return {
-    project: index?.project ?? path.basename(projectRoot),
-    stamp: index?.framework_version ?? null,
-    cli: cliVersion(),
-    indexState,
-    coverage: coverageSummary(projectRoot),
-    trace: traceSummary(projectRoot),
-    verify,
-    specs: countSpecs(projectRoot),
-    decisions: countDecisions(projectRoot),
-    skills: countSkills(projectRoot),
-  };
-}
-
-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 openChanges = 0;
-  if (isDir(changesDir)) {
-    for (const e of readdirSync(changesDir)) {
-      if (e === "archive" || e.startsWith(".")) continue;
-      if (isDir(path.join(changesDir, e))) openChanges += 1;
-    }
-  }
-  return { total, impl, openChanges };
-}
-
-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;
+  const snapshot = collectSnapshot(projectRoot);
+  for (const line of renderView(view, snapshot, options)) console.log(line);
+  return 0;
 }
 
 export const help = `
-Usage: doctrina status [--json]
+Usage: doctrina status [--view <name>] [--since <days>] [--json]
 
 Print a one-glance health dashboard for the .doctrina/ project: the gate
 signals (index drift, framework stamp, coverage %, trace anchors, whether
@@ -212,7 +81,17 @@ verify is configured) and the artifact counts (specs by implementation
 state, open changes, decisions, skills). Read-only; always exits 0.
 
 Flags:
-  --json   Emit the snapshot as JSON (stable shape for agents and CI).
+  --view <name>   Render a different shape of the same snapshot:
+                    dashboard  the default one-glance health board
+                    prime      the session primer (\`doctrina prime\`)
+                    handoff    the Markdown resume note (\`doctrina handoff\`)
+                    report     the period digest (\`doctrina report\`)
+  --since <days>  With --view report: the window (default 7).
+  --json          Emit the snapshot as JSON (stable shape for agents and CI).
+
+All four views read ONE collection of the tree, so they can never report
+different numbers; \`prime\`, \`handoff\` and \`report\` are the same views
+under their own names.
 
 It is a fast summary, not the authoritative gate: run \`doctrina validate\`
 and \`doctrina verify\` for the full structural and build checks, and

package/src/commands/templates.js

@@ -13,28 +13,15 @@ import { cliVersion } from "../lib/version.js";
 import { ARTIFACT_CATEGORIES } from "../lib/index-json.js";
 import { flagBool } from "../lib/args.js";
 import { c } from "../lib/colors.js";
+import { collectFindings, agentsSectionCost, AGENTS_SECTIONS, PRODUCT_SECTIONS, normalizeBlock, hasHeading } from "../lib/templates-model.js";
+
+// The findings are collected in lib/templates-model.js, which `doctor` reads
+// too (audit finding F7); this command renders and fixes them.
+export { collectFindings } from "../lib/templates-model.js";
 import { suggest } from "../lib/suggest.js";
 
 const SUBCOMMANDS = ["list", "check", "update"];
 
-// 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).
-const AGENTS_SECTIONS = [
-  "## Stack",
-  "## Commands",
-  "## Repository structure",
-  "## Conventions and boundaries",
-  "## How to read context",
-];
-const PRODUCT_SECTIONS = [
-  "## Vision",
-  "## Problem",
-  "## Target users",
-  "## Scope",
-  "## Success criteria",
-];
-const INDEX_FIELDS = ["$schema_version", "project", "artifacts"];
 
 // Flags this command accepts. Declared HERE, with the command, so
 // adding a command never requires editing the entrypoint — the gap that
@@ -69,6 +56,9 @@ function updateTemplates(flags) {
   }
 
   const plan = [];
+  // Updates this run declines to make, each with the reason and the number.
+  // Standing down is a RESULT, not a silence (change 0078).
+  const held = [];
 
   // AGENTS.md command-surface block: the one CLI-OWNED span of the file
   // (marker-delimited, generated from the command catalog). Three cases:
@@ -165,6 +155,20 @@ function updateTemplates(flags) {
     if (!isFile(filePath)) continue;
     const text = read(filePath);
     const missing = sections.filter((h) => !hasHeading(text, h));
+    // AGENTS.md has a declared line ceiling, and `analyze` refuses a change
+    // that resolves an overflow by raising it — so appending stubs that do
+    // not fit would trade one gate's recommendation for another's refusal,
+    // silently. The plan says what it would cost and stands down instead
+    // (change 0078); the check's remedy already names the cut to make first.
+    if (missing.length > 0 && rel === "AGENTS.md") {
+      const budget = agentsSectionCost(projectRoot, missing);
+      if (!budget.fits) {
+        held.push(`AGENTS.md: ${missing.length} stub section(s) not appended — they cost ` +
+          `${budget.cost} lines and only ${budget.slack} remain of the declared ceiling; ` +
+          `cut ${budget.over} line(s) of prose first`);
+        continue;
+      }
+    }
     if (missing.length > 0) {
       plan.push({
         describe: missing.map((h) => `${rel}: append stub section "${h}"`),
@@ -215,7 +219,16 @@ function updateTemplates(flags) {
   }
 
   const steps = plan.flatMap((p) => p.describe);
+  for (const reason of held) {
+    console.log(c.yellow("held   ") + reason);
+  }
   if (steps.length === 0) {
+    if (held.length > 0) {
+      console.log("");
+      console.log(c.yellow("hold") + ` ${held.length} update${held.length === 1 ? "" : "s"} not applied — ` +
+        "make room first, then re-run");
+      return 0;
+    }
     console.log(c.green("ok") + " project already follows the current template shape");
     return 0;
   }
@@ -284,117 +297,6 @@ function checkTemplates() {
   return report(findings, ok);
 }
 
-// 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);
-    for (const heading of AGENTS_SECTIONS) {
-      if (hasHeading(text, heading)) ok.push(`AGENTS.md: ${heading}`);
-      else findings.push({ message: `AGENTS.md missing recommended section "${heading}"`, remedy: "doctrina templates update --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 templates update --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 templates update --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 templates update --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)) continue; // command shim, not a pointer
-      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 surfaceLines = surfaceMarkdown().split("\n").length;
-  if (surfaceLines > SURFACE_LINE_BUDGET) {
-    findings.push({
-      message: `the generated surface block is ${surfaceLines} lines (budget ${SURFACE_LINE_BUDGET}) — cut commands rather than raising the budget`,
-      remedy: null,
-    });
-  } else {
-    ok.push(`surface block within budget (${surfaceLines}/${SURFACE_LINE_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 templates update --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
-  return { findings, ok };
-}
 
 function report(findings, ok) {
   for (const o of ok) console.log(c.green("✓ ") + o);
@@ -443,9 +345,6 @@ function templateAnchors() {
   }
 }
 
-function normalizeBlock(s) {
-  return s.replace(/\r\n/g, "\n").replace(/[ \t]+$/gm, "").trim();
-}
 
 // A pre-marker AGENTS.md's hand-written surface section: from the
 // "## Doctrina command surface" heading up to (excluding) the next "## "
@@ -459,12 +358,6 @@ function findLegacySurfaceSection(text) {
   return { start: head.index, end: next ? head.index + head[0].length + next.index : text.length };
 }
 
-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);
-}
 
 export const help = `
 Usage: doctrina templates <subcommand>