doctrina-cli 0.12.0 → 0.13.0

package/src/commands/templates.js

@@ -1,7 +1,8 @@
 import path from "node:path";
 import process from "node:process";
 import { exists, isDir, isFile, lineCount, read, relPath, walk, write } from "../lib/fs-ops.js";
-import { locateTemplatesDir } from "../lib/templates.js";
+import { locateTemplatesDir, loadTemplateTree } from "../lib/templates.js";
+import { surfaceBlock, findSurfaceBlock } from "../lib/commands.js";
 import { flagBool } from "../lib/args.js";
 import { c } from "../lib/colors.js";
 import { suggest } from "../lib/suggest.js";
@@ -56,6 +57,50 @@ function updateTemplates(flags) {
 
   const plan = [];
 
+  // AGENTS.md command-surface block: the one CLI-OWNED span of the file
+  // (marker-delimited, generated from the command catalog). Three cases:
+  // markers present but stale -> regenerate the span; a legacy hand-written
+  // "## Doctrina command surface" section without markers -> replace that
+  // section with the managed block (the section was CLI-scaffolded content
+  // to begin with — this is the one sanctioned exception to additive-only,
+  // see ADR 0015); neither -> append the block. This is what makes
+  // `doctrina upgrade --write` actually refresh AGENTS.md when the CLI
+  // gains commands, instead of only bumping the stamp.
+  const agentsMdPath = path.join(projectRoot, "AGENTS.md");
+  if (isFile(agentsMdPath)) {
+    const text = read(agentsMdPath);
+    const block = findSurfaceBlock(text);
+    const fresh = surfaceBlock();
+    if (block) {
+      if (normalizeBlock(text.slice(block.start, block.end)) !== normalizeBlock(fresh)) {
+        plan.push({
+          describe: ["AGENTS.md: regenerate the doctrina:surface block (stale vs installed CLI)"],
+          apply() {
+            const cur = read(agentsMdPath);
+            const b = findSurfaceBlock(cur);
+            if (b) write(agentsMdPath, cur.slice(0, b.start) + fresh + cur.slice(b.end), { force: true });
+          },
+        });
+      }
+    } else {
+      const legacy = findLegacySurfaceSection(text);
+      plan.push({
+        describe: [legacy
+          ? "AGENTS.md: replace the hand-written \"## Doctrina command surface\" section with the generated doctrina:surface block"
+          : "AGENTS.md: append the generated doctrina:surface command block (agents discover commands through this file)"],
+        apply() {
+          const cur = read(agentsMdPath);
+          const l = findLegacySurfaceSection(cur);
+          if (l) {
+            write(agentsMdPath, cur.slice(0, l.start) + fresh + "\n\n" + cur.slice(l.end), { force: true });
+          } else {
+            write(agentsMdPath, cur + (cur.endsWith("\n") ? "" : "\n") + "\n" + fresh + "\n", { force: true });
+          }
+        },
+      });
+    }
+  }
+
   // Markdown files: append stub sections for missing recommended headings.
   for (const [rel, sections] of [
     ["AGENTS.md", AGENTS_SECTIONS],
@@ -178,6 +223,15 @@ function checkTemplates() {
       if (hasHeading(text, heading)) ok.push(`AGENTS.md: ${heading}`);
       else findings.push(`AGENTS.md missing recommended section "${heading}"`);
     }
+    // Command-surface block: present and current vs the installed catalog.
+    const block = findSurfaceBlock(text);
+    if (!block) {
+      findings.push("AGENTS.md has no doctrina:surface block — agents discover commands through this file (`templates update --write` adds it)");
+    } else if (normalizeBlock(text.slice(block.start, block.end)) !== normalizeBlock(surfaceBlock())) {
+      findings.push("AGENTS.md doctrina:surface block is stale vs the installed CLI (`templates update --write` or `doctrina upgrade --write` regenerates it)");
+    } else {
+      ok.push("AGENTS.md: doctrina:surface block current");
+    }
   } else {
     findings.push("AGENTS.md missing at project root");
   }
@@ -194,6 +248,32 @@ function checkTemplates() {
     findings.push(".doctrina/product.md missing");
   }
 
+  // Installed agent adapters: every adapter is a thin POINTER at AGENTS.md
+  // (that is why one `upgrade --write` refresh of the hub reaches every
+  // installed agent). Verify the contract holds for each adapter file the
+  // project actually has: it must still reference AGENTS.md. The shipped
+  // adapter template tree is the inventory, so a new adapter is covered
+  // automatically.
+  try {
+    const templatesDir = locateTemplatesDir();
+    const adaptersRoot = path.join(templatesDir, "adapters");
+    if (isDir(adaptersRoot)) {
+      for (const agent of walk(adaptersRoot).map((f) => relPath(adaptersRoot, f))) {
+        const posix = agent.replace(/\\/g, "/");
+        if (posix.endsWith("README.md") || posix.endsWith(".gitkeep")) continue;
+        const rel = posix.split("/").slice(1).join("/").replace(/\.template$/, "");
+        if (!rel) continue;
+        const installed = path.join(projectRoot, rel);
+        if (!isFile(installed)) continue; // not installed — nothing to check
+        if (read(installed).includes("AGENTS.md")) {
+          ok.push(`adapter ${rel}: points at AGENTS.md`);
+        } else {
+          findings.push(`adapter ${rel} no longer references AGENTS.md — agents loading it will miss the hub (restore the pointer, e.g. re-run \`doctrina init --agent <name> --force\`)`);
+        }
+      }
+    }
+  } catch { /* no templates dir (unusual install) — skip the adapter pass */ }
+
   // index.json schema fields
   const indexPath = path.join(projectRoot, ".doctrina", "index.json");
   if (isFile(indexPath)) {
@@ -227,6 +307,24 @@ function checkTemplates() {
   return 1;
 }
 
+// Whitespace/EOL-insensitive comparison for the surface block, so a CRLF
+// checkout is not eternally "stale".
+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 "## "
+// heading. The trailing "Continuous: ..." paragraph the old template put
+// after the bullets belongs to the section body, so it is replaced too.
+function findLegacySurfaceSection(text) {
+  const head = text.match(/^##\s+Doctrina command surface.*$/m);
+  if (!head) return null;
+  const after = text.slice(head.index + head[0].length);
+  const next = after.match(/^##\s+/m);
+  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).
@@ -245,15 +343,20 @@ Subcommands:
             their relative paths and line counts.
   check     Compare the current project's AGENTS.md, product.md,
             and index.json against the recommended sections and
-            schema fields shipped in this CLI version. Reports any
-            recommended section that is missing. Read-only; never
-            modifies any files. Exits 1 when recommendations exist,
-            0 when the project follows the current template shape.
-  update    Additive-only fixer for what check reports: appends
-            missing recommended sections as stubs and adds missing
-            index.json fields. Preview by default (exits 1 while
-            updates are pending); pass --write to apply. Never
-            rewrites or removes existing content.
+            schema fields shipped in this CLI version — including
+            whether the AGENTS.md doctrina:surface block (the
+            CLI-owned, generated command catalog) is present and
+            current. Read-only; never modifies any files. Exits 1
+            when recommendations exist, 0 otherwise.
+  update    Fixer for what check reports: appends missing
+            recommended sections as stubs, adds missing index.json
+            fields, and regenerates the AGENTS.md doctrina:surface
+            block from the installed command catalog. Preview by
+            default (exits 1 while updates are pending); pass
+            --write to apply. Additive-only outside the surface
+            block: the marker-delimited span is the one CLI-owned
+            region it rewrites (ADR 0015); your content is never
+            touched.
 
 Distinct from \`doctrina validate\`: validate answers "is this a
 well-formed Doctrina tree?"; templates check answers "does this

package/src/commands/upgrade.js

@@ -82,10 +82,12 @@ export async function run(_positional, flags) {
     }
   }
 
-  // 4. Full structural check — surfaces what an automatic, additive upgrade
-  //    cannot fix: an AGENTS.md documenting a stale command surface, new
-  //    validate checks the old scaffold fails, and so on. --fix under --write
-  //    so the mechanical part self-heals.
+  // 4. Full structural check — surfaces what the upgrade cannot fix by
+  //    itself (new validate checks the old scaffold fails, hand-authored
+  //    drift). The command surface in AGENTS.md is NOT in this bucket any
+  //    more: step 1 regenerates the doctrina:surface block from the
+  //    installed catalog (ADR 0015). --fix under --write so the mechanical
+  //    part self-heals.
   console.log("");
   console.log(c.gray("──── 3/3 validate" + (writeMode ? " --fix" : "")));
   const vFlags = writeMode ? new Map([["fix", true]]) : new Map();
@@ -102,7 +104,7 @@ export async function run(_positional, flags) {
   }
   if (vCode === 0) {
     console.log(c.green(`✓ project upgraded to ${running}`) + c.gray(" — review any warnings above; new commands: `doctrina --help`."));
-    console.log(c.gray("If AGENTS.md lists the command surface, refresh that section so agents see the new commands."));
+    console.log(c.gray("AGENTS.md's doctrina:surface block was regenerated from the installed catalog, so agents reading the hub now discover the current commands."));
   } else {
     console.log(c.yellow("upgraded with findings") + " — resolve the validate errors above (they predate or exceed what an additive upgrade can fix).");
   }
@@ -116,14 +118,16 @@ Bring an existing project up to the installed CLI after an npm update.
 The project keeps the scaffold of the version that init-ed it; this is
 the one command that closes the gap, orchestrating the existing pieces:
 
-  1. templates update   — append missing recommended sections to AGENTS.md
-                          / product.md and missing index.json fields
-                          (additive-only; never rewrites your content)
+  1. templates update   — regenerate the AGENTS.md doctrina:surface block
+                          from the installed command catalog (the block is
+                          CLI-owned, ADR 0015 — this is how agents reading
+                          the hub discover commands added since init), and
+                          append missing recommended sections / index.json
+                          fields (additive-only outside the block)
   2. index rebuild      — regenerate index.json from the tree and migrate
                           the framework_version stamp to the running CLI
-  3. validate (--fix)   — surface anything the additive upgrade cannot fix
-                          (e.g. an AGENTS.md documenting a stale command
-                          surface — refresh it so agents see new commands)
+  3. validate (--fix)   — surface anything the upgrade cannot fix
+                          (hand-authored drift, new validate checks)
 
 Preview by default (exits 1 when steps are pending); --write applies.
 `;

package/src/commands/validate.js

@@ -254,7 +254,12 @@ export async function run(_positional, flags) {
     }
   }
 
-  // 7. Every open change has a proposal
+  // 7. Every open change has a proposal, and its delta files carry a
+  //    well-formed **Operation:** header. The delta used to be the one
+  //    100% hand-authored file with no early check: a missing header passed
+  //    silently at creation and exploded days later in the closing analyze
+  //    (operator review 2026-07-19 §3.2). Warning-level — the change is
+  //    still a draft — but now every `validate` run names it.
   const changesDir = path.join(projectRoot, ".doctrina", "changes");
   if (isDir(changesDir)) {
     const { readdirSync } = await import("node:fs");
@@ -267,6 +272,35 @@ export async function run(_positional, flags) {
             `(every dir under .doctrina/changes/ needs a proposal.md — that exact filename)`,
         );
       }
+      // A change whose tasks are still the scaffold placeholders was opened
+      // but never planned — the agent is (or will be) implementing with no
+      // recorded plan. Early, every-run signal; analyze/close hard-fail it.
+      const tasksPath = path.join(changesDir, entry, "tasks.md");
+      if (isFile(tasksPath)) {
+        const ph = (read(tasksPath).match(/^\s*-\s*\[[ xX]\]\s*$/gm) ?? []).length;
+        if (ph > 0) {
+          warnings.push(
+            `open change "${entry}" tasks.md still carries ${ph} scaffold placeholder task${ph === 1 ? "" : "s"} — ` +
+              `the change was opened but never planned (replace them with real tasks; analyze/close refuse them)`,
+          );
+        }
+      }
+      for (const deltaPath of walk(path.join(changesDir, entry, "specs"))) {
+        if (!deltaPath.endsWith("delta.md")) continue;
+        const text = read(deltaPath);
+        const m = text.match(/^\*\*Operation:\*\*\s*(\S+)/m);
+        if (!m) {
+          warnings.push(
+            `${relPath(projectRoot, deltaPath)} has no **Operation:** header — ` +
+              `analyze/apply will refuse it at close time (add "**Operation:** ADDED|MODIFIED|REMOVED")`,
+          );
+        } else if (!["ADDED", "MODIFIED", "REMOVED"].includes(m[1])) {
+          warnings.push(
+            `${relPath(projectRoot, deltaPath)} Operation "${m[1]}" is not ADDED|MODIFIED|REMOVED — ` +
+              `analyze/apply will refuse it at close time`,
+          );
+        }
+      }
     }
   }
 

package/src/commands/work.js

@@ -2,11 +2,12 @@ import path from "node:path";
 import process from "node:process";
 import { readdirSync } from "node:fs";
 import { spawnSync } from "node:child_process";
-import { exists, isDir, isFile, read, relPath, write } from "../lib/fs-ops.js";
+import { exists, isDir, isFile, mkdirp, read, relPath, write } from "../lib/fs-ops.js";
 import { flagString, flagBool } from "../lib/args.js";
 import * as idx from "../lib/index-json.js";
 import { c } from "../lib/colors.js";
 import { assessBrief } from "../lib/clarity.js";
+import { locateTemplatesDir, substitute } from "../lib/templates.js";
 import { changeNew } from "./change.js";
 
 // `work` is the second half of the no-ceremony path (ADR 0005): a brief
@@ -106,6 +107,26 @@ export async function run(positional, flags) {
     if (updated !== txt) write(proposalPath, updated, { force: true });
   }
 
+  // A pinned capability is an explicit statement of intent, so the delta —
+  // historically the only 100% hand-authored file in the flow, and the one
+  // whose missing **Operation:** header exploded days later at analyze
+  // (operator review 2026-07-19 §3.2) — is scaffolded from the template with
+  // the Operation prefilled: MODIFIED when the spec exists, ADDED when it
+  // does not. Never scaffolded from a ranked GUESS (that would put a wrong
+  // capability's delta in the change); only from --capability.
+  if (pinned && !chore) {
+    const deltaPath = path.join(projectRoot, ".doctrina", "changes", id, "specs", pinned, "delta.md");
+    if (!exists(deltaPath)) {
+      const tpl = read(path.join(locateTemplatesDir(), "change", "spec-delta.md.template"));
+      const op = isFile(path.join(projectRoot, ".doctrina", "specs", pinned, "spec.md")) ? "MODIFIED" : "ADDED";
+      const body = substitute(tpl, { CAPABILITY: pinned })
+        .replace(/^\*\*Operation:\*\*.*$/m, `**Operation:** ${op}`);
+      mkdirp(path.dirname(deltaPath));
+      write(deltaPath, body);
+      console.log(c.green("created") + ` ${relPath(projectRoot, deltaPath)}` + c.gray(` (Operation: ${op} prefilled)`));
+    }
+  }
+
   // Capability hint: term overlap for a prompt, changed-file overlap for a diff
   // (review F10 — rank by what the working tree touched, not just prompt words).
   const allChanged = fromDiff ? files : changedFiles(projectRoot);
@@ -114,6 +135,16 @@ export async function run(positional, flags) {
   const capability = pinned ?? matches[0]?.id ?? null;
   const clarity = assessBrief(effPrompt, { kind: "prompt" });
 
+  // --quiet: registering backlog, not starting now (operator review §3.7 — 19
+  // works printed 19 identical 50-line playbooks). One line per change; the
+  // playbook is reprintable on demand with --resume.
+  if (flagBool(flags, "quiet", false)) {
+    console.log("");
+    console.log(c.green("opened ") + c.cyan(id) +
+      c.gray(` — playbook on demand: doctrina work --resume ${id}`));
+    return 0;
+  }
+
   console.log("");
   if (chore) {
     printChorePlaybook(projectRoot, { id, prompt: effPrompt });
@@ -339,6 +370,8 @@ function printChorePlaybook(projectRoot, { id, prompt }) {
   console.log("");
   console.log(`1. Replace the placeholder tasks in .doctrina/changes/${id}/tasks.md`);
   console.log("   with small, checkable steps; implement them, checking each box.");
+  console.log(c.gray("   (Do it before implementing — analyze/close refuse leftover scaffold"));
+  console.log(c.gray("   placeholders, and `change tick` will not tick an empty box.)"));
   console.log("2. Prove it (archive refuses unchecked boxes):");
   console.log(`       ${c.cyan("doctrina verify")}     — the project's typecheck/test/build gate`);
   console.log(`       ${c.cyan("doctrina verify --clean")} — clean-checkout reproducibility lint`);
@@ -406,8 +439,14 @@ function printPlaybook(projectRoot, { id, prompt, pinned, matches, capability, c
   console.log(c.gray("   \"**Realizes:** SC1\" header (or \"n/a — <why>\"). `doctrina validate` warns"));
   console.log(c.gray("   on an active spec with no Realizes; `doctrina trace` reports the link."));
   console.log("");
-  console.log("3. Write one delta per affected capability at");
-  console.log(`   .doctrina/changes/${id}/specs/<capability>/delta.md:`);
+  if (pinned) {
+    console.log(`3. A delta is already scaffolded (Operation prefilled) at`);
+    console.log(`   .doctrina/changes/${id}/specs/${pinned}/delta.md — fill its body.`);
+    console.log("   Add one more delta per additional affected capability:");
+  } else {
+    console.log("3. Write one delta per affected capability at");
+    console.log(`   .doctrina/changes/${id}/specs/<capability>/delta.md:`);
+  }
   console.log(c.gray("       # Spec Delta — capability: <capability>"));
   console.log(c.gray("       **Operation:** ADDED | MODIFIED | REMOVED"));
   console.log(c.gray("       **Target spec on apply:** `.doctrina/specs/<capability>/spec.md`"));
@@ -423,8 +462,12 @@ function printPlaybook(projectRoot, { id, prompt, pinned, matches, capability, c
   console.log(c.gray("       bump-version minor"));
   console.log(c.gray("       set-criterion 1: verified"));
   console.log(c.gray("       append-criterion [unverified] new signal — verified by `test/y.test.js`"));
+  console.log(c.gray("       append-requirement event: When <trigger>, the system shall <action>."));
+  console.log(c.gray("       replace-requirement ubiquitous 2: The system shall <action>."));
   console.log(c.gray("       ```"));
-  console.log(c.gray("   Only prose rewrites stay a by-hand merge."));
+  console.log(c.gray("   append-* ops number/position at APPLY time, so concurrent changes"));
+  console.log(c.gray("   appending to the same spec never collide. Only free-prose rewrites"));
+  console.log(c.gray("   (Purpose, Maturity, ...) stay a by-hand merge."));
   if (fromDiff) {
     console.log(c.gray("   --from-diff: the code already exists — describe its CURRENT behaviour, and"));
     console.log(c.gray("   mark each criterion [unverified] until a test proves it (don't assume the"));
@@ -432,7 +475,10 @@ function printPlaybook(projectRoot, { id, prompt, pinned, matches, capability, c
   }
   console.log("");
   console.log(`4. Replace the placeholder tasks in .doctrina/changes/${id}/tasks.md`);
-  console.log("   with small, checkable implementation tasks (a few hours each, max).");
+  console.log("   with small, checkable implementation tasks (a few hours each, max),");
+  console.log("   and record the change's What/Scope in its proposal.md. Do this BEFORE");
+  console.log("   implementing — analyze and close refuse a change whose scaffold");
+  console.log("   placeholders were never replaced, and `change tick` will not tick them.");
   console.log("");
   console.log("5. Implement task by task, checking each box as it lands. Advance the");
   console.log("   spec's Implementation: planned → partial → implemented as code lands.");
@@ -442,6 +488,10 @@ function printPlaybook(projectRoot, { id, prompt, pinned, matches, capability, c
   console.log("   (an architecture, a boundary, a trade-off a future session must");
   console.log(`   not relitigate)? If yes: ${c.cyan("doctrina decision new \"<title>\"")} now,`);
   console.log("   before closing — the definition of done requires it recorded.");
+  console.log(c.gray("   (close re-checks this: it warns when the change touches capabilities"));
+  console.log(c.gray("   cited by an accepted ADR — amend via decision supersede, not silence.)"));
+  console.log("   Touching an integration surface (ports, env vars, public endpoints)?");
+  console.log(`   Own it in a contract: ${c.cyan("doctrina contract new <id>")} · ${c.cyan("doctrina contract check")}.`);
   console.log("");
   console.log(`7. Close in one attested pass (preferred — runs every gate and stops`);
   console.log("   at the first failure with the exact rerun command):");
@@ -476,7 +526,12 @@ named after that word (review G1). Use --resume to do so directly.
 Options:
   --title "<short>"    Short display title: drives the slug and the proposal
                        H1; the full prompt still lands under ## Why
-  --capability <cap>   Pin the capability instead of ranking matches
+  --capability <cap>   Pin the capability instead of ranking matches. Also
+                       scaffolds specs/<cap>/delta.md in the change with the
+                       Operation header prefilled (MODIFIED when the spec
+                       exists, ADDED when it does not)
+  --quiet              Register the change and print one line — no playbook
+                       (backlog entry; reprint later with --resume <id>)
   --id <id>            Override the derived change id
   --resume <id>        Reprint the playbook for an open change; create nothing
   --from-diff          Backfill: scaffold from the working-tree changes (no

package/src/lib/adr-guard.js

@@ -0,0 +1,46 @@
+import path from "node:path";
+import { isDir, read, walk } from "./fs-ops.js";
+import { listHeader } from "./scan.js";
+
+// Deterministic ADR checkpoint (operator review 2026-07-19 §4.6). The work
+// playbook's "record an ADR" step was ignorable in silence: a change that
+// flexibilised an accepted ADR closed with no amendment and nothing barked.
+// This helper names the accepted ADRs whose text cites any of the change's
+// touched capabilities, so `change check` and `close` can print a loud,
+// advisory reminder: if the change alters what the ADR decided, record it
+// (`decision supersede` / `decision new`) instead of drifting past it.
+// A word match on capability names — a hint, never a decision (ADR 0005),
+// and never a blocker (an ADR merely MENTIONING a capability is normal).
+export function adrAdvisories(projectRoot, capabilities) {
+  const adrDir = path.join(projectRoot, ".doctrina", "decisions");
+  if (!isDir(adrDir) || capabilities.length === 0) return [];
+  const out = [];
+  for (const f of walk(adrDir)) {
+    const base = path.basename(f);
+    const m = base.match(/^(\d{4})-.*\.md$/);
+    if (!m) continue;
+    const text = read(f);
+    if ((listHeader(text, "Status") ?? "").toLowerCase() !== "accepted") continue;
+    const caps = capabilities.filter((cap) =>
+      new RegExp(`(^|[^a-z0-9-])${cap.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}([^a-z0-9-]|$)`, "im").test(text),
+    );
+    if (caps.length === 0) continue;
+    const titleMatch = text.match(/^#\s+ADR\s+\d{4}\s*[—-]\s*(.+)$/m);
+    out.push({ id: m[1], title: titleMatch ? titleMatch[1].trim() : base, caps });
+  }
+  return out;
+}
+
+// Print the advisory block shared by `change check` and `close`. Returns the
+// number of ADRs flagged (informational; callers never gate on it).
+export function printAdrCheckpoint(projectRoot, capabilities, { c }) {
+  const hits = adrAdvisories(projectRoot, capabilities);
+  if (hits.length === 0) return 0;
+  console.log(c.yellow("ADR checkpoint") + c.gray(" — accepted ADRs cite the touched capabilities:"));
+  for (const h of hits) {
+    console.log(`    ADR ${c.cyan(h.id)}  ${h.title}  ${c.gray(`(cites: ${h.caps.join(", ")})`)}`);
+  }
+  console.log(c.gray("    If this change alters what an ADR decided, record it now:"));
+  console.log(c.gray("    ") + c.cyan("doctrina decision supersede <n>") + c.gray(" · ") + c.cyan("doctrina decision new \"<title>\""));
+  return hits.length;
+}

package/src/lib/commands.js

@@ -40,8 +40,10 @@ export const OPERATIONS = [
   ["spec list", "List specs with version, status, and size"],
   ["spec set", "Edit spec headers / a criterion mark and resync the index"],
   ["change new", "Open a change proposal"],
-  ["change apply", "Apply spec deltas (ADDED/REMOVED auto, MODIFIED manual)"],
-  ["change archive", "Archive an applied change"],
+  ["change apply", "Apply spec deltas (ops blocks mechanically; batch ids ok)"],
+  ["change archive", "Archive an applied change (batch ids ok)"],
+  ["change check", "Pre-close dry-run: everything close would refuse, listed first"],
+  ["change tick", "List/tick the unchecked boxes (tasks + verification; --all)"],
   ["change diff", "Preview spec deltas (line diff for MODIFIED)"],
   ["change abandon", "Discard an open change cleanly (recorded in the ledger)"],
   ["contract new", "Own the integration surface (ports, env, interfaces)"],
@@ -94,6 +96,102 @@ export function surfaceHelp() {
   return OPERATIONS.map(([op, summary]) => `  ${op.padEnd(21)}${summary}`).join("\n");
 }
 
+// ---------------------------------------------------------------------------
+// The CLI-owned AGENTS.md command-surface block (operator review 2026-07-19,
+// meta-conclusion): for an agent, AGENTS.md IS the discovery interface — it
+// never runs `--help` spontaneously — so every command absent from the hub
+// was invisible for ~35 changes (`prime`, `handoff`, `doctor`, `show`, ...).
+// The fix is a marker-delimited section GENERATED from OPERATIONS, so the
+// hub's catalog is the CLI's catalog by construction: `init` scaffolds it,
+// `templates check` flags it stale, and `templates update --write` (hence
+// `doctrina upgrade --write`) regenerates exactly the marked span and
+// nothing else. Content between the markers is CLI-owned; everything
+// outside remains the adopter's, under the additive-only guarantee.
+
+export const SURFACE_BEGIN =
+  "<!-- doctrina:surface:begin — CLI-owned block, generated from the installed command catalog. Refreshed by `doctrina upgrade --write`; edits inside are overwritten. -->";
+export const SURFACE_END = "<!-- doctrina:surface:end -->";
+
+// Workflow grouping for the generated block. A test asserts the flattened
+// names equal COMMAND_NAMES, so a new command cannot ship ungrouped (and
+// therefore cannot ship invisible to AGENTS.md).
+export const SURFACE_GROUPS = [
+  ["Start", ["init", "intake", "work"]],
+  ["Author", ["spec", "change", "contract", "decision", "skill", "intent"]],
+  ["Read / orient", ["prime", "context", "show", "search", "status", "next", "why", "handoff", "constitution"]],
+  ["Gates", ["analyze", "clarify", "validate", "coverage", "trace", "review", "verify", "close", "doctor"]],
+  ["Maintain", ["templates", "hooks", "index", "watch", "metrics", "report", "completion", "upgrade"]],
+];
+
+// Per-command usage hints appended to the generated reference — arguments and
+// the flags an agent reaches for daily. Cosmetic only; the operation list
+// itself always comes from OPERATIONS.
+const SURFACE_HINTS = {
+  work: '"<prompt>" (--capability · --chore · --from-diff · --quiet)',
+  context: "[<cap>] --concat",
+  validate: "(--fix)",
+  coverage: "--strict",
+  trace: "--strict",
+  clarify: "--all (--lang pt|en)",
+  close: "<id...>",
+  upgrade: "--write",
+  prime: "(session start)",
+  handoff: "(before compaction/handover)",
+};
+
+// The full managed section, heading included, between the markers.
+export function surfaceMarkdown() {
+  const subsByCmd = new Map();
+  for (const [op] of OPERATIONS) {
+    const [cmd, sub] = op.split(" ");
+    if (!subsByCmd.has(cmd)) subsByCmd.set(cmd, []);
+    if (sub) subsByCmd.get(cmd).push(sub);
+  }
+  const renderCmd = (cmd) => {
+    const subs = subsByCmd.get(cmd) ?? [];
+    const hint = SURFACE_HINTS[cmd] ? ` ${SURFACE_HINTS[cmd]}` : "";
+    return subs.length > 0 ? `\`doctrina ${cmd} ${subs.join("|")}\`` : `\`doctrina ${cmd}${hint}\``;
+  };
+  const lines = [
+    "## Doctrina command surface (generated — reach for these, don't hand-author)",
+    "",
+    "Every operation of the installed CLI, grouped by workflow. The CLI",
+    "scaffolds from canonical templates and keeps `index.json` in sync, so",
+    "prefer it over writing artifacts by hand. Details: `doctrina --help`.",
+    "",
+  ];
+  for (const [label, cmds] of SURFACE_GROUPS) {
+    lines.push(`- **${label}:** ${cmds.map(renderCmd).join(" · ")}`);
+  }
+  lines.push("");
+  lines.push("Session bookends: `doctrina prime` to orient at session start;");
+  lines.push("`doctrina handoff` before compaction or handover. Continuous:");
+  lines.push("`doctrina watch`. Capture lessons: `doctrina skill suggest`.");
+  return lines.join("\n");
+}
+
+// The block as written to AGENTS.md: markers wrapping the generated section.
+export function surfaceBlock() {
+  return `${SURFACE_BEGIN}\n${surfaceMarkdown()}\n${SURFACE_END}`;
+}
+
+// Locate the managed block in an AGENTS.md text. Returns
+// { start, end, inner } (string offsets; inner excludes the marker lines)
+// or null when either marker is absent.
+export function findSurfaceBlock(text) {
+  const begin = text.match(/<!--\s*doctrina:surface:begin[\s\S]*?-->/);
+  if (!begin) return null;
+  const endRe = /<!--\s*doctrina:surface:end\s*-->/;
+  const end = endRe.exec(text.slice(begin.index + begin[0].length));
+  if (!end) return null;
+  const innerStart = begin.index + begin[0].length;
+  return {
+    start: begin.index,
+    end: innerStart + end.index + end[0].length,
+    inner: text.slice(innerStart, innerStart + end.index).replace(/^\r?\n|\r?\n$/g, ""),
+  };
+}
+
 // Extract the set of top-level `doctrina <command>` references that appear in
 // CODE context (fenced blocks or inline backtick spans) of a Markdown file —
 // AGENTS.md, typically. Restricting to code context avoids matching prose like