doctrina-cli 0.12.0 → 0.13.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "doctrina-cli",
-  "version": "0.12.0",
+  "version": "0.13.0",
   "description": "Doctrina CLI — spec-driven, AGENTS.md-native framework for multi-agent AI development.",
   "license": "MIT",
   "keywords": [

package/src/commands/analyze.js

@@ -41,6 +41,16 @@ export async function run(positional, _flags) {
   } else {
     results.push(pass("tasks.md present"));
     const text = read(tasksPath);
+    // Scaffold placeholders never replaced ("- [ ]" with no text, checked or
+    // not) mean the change was OPENED but never PLANNED — the agent went
+    // straight to implementing on a hollow change and nothing barked
+    // (operator report 2026-07-19). A hard failure here blocks `change
+    // check` and `close` until the plan is real; ticking an empty box does
+    // not help, `change tick` refuses those too.
+    const placeholders = (text.match(/^\s*-\s*\[[ xX]\]\s*$/gm) ?? []).length;
+    if (placeholders > 0) {
+      results.push(fail(`tasks.md still carries ${placeholders} scaffold placeholder task${placeholders === 1 ? "" : "s"} ("- [ ]" with no text) — plan the change before implementing: replace them with real tasks (or delete the lines)`));
+    }
     if (/^\s*-\s*\[\s\]/m.test(text)) results.push(pass("tasks.md has at least one unchecked task"));
     else results.push(info("tasks.md has no unchecked tasks (already done?)"));
   }

package/src/commands/change.js

@@ -1,17 +1,18 @@
 import path from "node:path";
 import process from "node:process";
-import { exists, isDir, lineCount, mkdirp, move, read, relPath, remove, walk, write } from "../lib/fs-ops.js";
+import { exists, isDir, isFile, lineCount, mkdirp, move, read, relPath, remove, walk, write } from "../lib/fs-ops.js";
 import { diffLines, formatUnified } from "../lib/diff.js";
 import { locateTemplatesDir, loadTemplateTree, materialiseEntry } from "../lib/templates.js";
 import * as idx from "../lib/index-json.js";
 import { deriveIndex } from "../lib/scan.js";
 import { extractOps, applyOps } from "../lib/spec-ops.js";
+import { printAdrCheckpoint } from "../lib/adr-guard.js";
 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";
 
-const SUBCOMMANDS = ["new", "apply", "archive", "diff", "abandon"];
+const SUBCOMMANDS = ["new", "apply", "archive", "check", "tick", "diff", "abandon"];
 
 export async function run(positional, flags) {
   const sub = positional[0];
@@ -19,9 +20,13 @@ export async function run(positional, flags) {
     case "new":
       return changeNew(positional.slice(1), flags);
     case "apply":
-      return changeApply(positional.slice(1), flags);
+      return forEachId(positional.slice(1), "apply", (id) => changeApply([id], flags));
     case "archive":
-      return changeArchive(positional.slice(1), flags);
+      return forEachId(positional.slice(1), "archive", (id) => changeArchive([id], flags));
+    case "check":
+      return forEachId(positional.slice(1), "check", (id) => changeCheck(id));
+    case "tick":
+      return changeTick(positional.slice(1), flags);
     case "diff":
       return changeDiff(positional.slice(1), flags);
     case "abandon":
@@ -36,6 +41,40 @@ export async function run(positional, flags) {
   }
 }
 
+// Batch driver (operator review 2026-07-19 §3.5/§4.5): apply/archive/check
+// accept multiple ids so a backlog closes without a bash loop. Each id runs
+// independently — one failure does not stop the rest — and the exit code is
+// the worst one seen. `new` and `abandon` stay single-id on purpose (creation
+// wants a title; abandonment is destructive and deserves one deliberate call).
+async function forEachId(ids, name, one) {
+  if (ids.length === 0) {
+    console.error(c.red("error:") + ` change ${name} requires at least one <id>`);
+    return 2;
+  }
+  let worst = 0;
+  for (const id of ids) {
+    if (ids.length > 1) {
+      console.log("");
+      console.log(c.bold(`──── change ${name} ${id}`));
+    }
+    let code;
+    try {
+      code = await one(id);
+    } catch (err) {
+      console.error(c.red("error:") + ` ${err.message}`);
+      code = 1;
+    }
+    worst = Math.max(worst, code);
+  }
+  if (ids.length > 1) {
+    console.log("");
+    console.log(worst === 0
+      ? c.green("ok") + ` all ${ids.length} changes passed ${name}`
+      : c.red("fail") + ` at least one change failed ${name}`);
+  }
+  return worst;
+}
+
 function changeNew(args, flags) {
   const id = args[0];
   const title = args.slice(1).join(" ").trim();
@@ -246,6 +285,191 @@ function changeApply(args, _flags) {
   return errors > 0 ? 1 : 0;
 }
 
+// Pre-close dry-run (operator review 2026-07-19 §4.4): everything analyze,
+// apply, and archive would refuse, listed BEFORE any of them runs, with the
+// remediation next to each finding. Read-only — the per-change `doctor`.
+async function changeCheck(id) {
+  const projectRoot = process.cwd();
+  ensureDoctrinaProject(projectRoot);
+  const changeDir = path.join(projectRoot, ".doctrina", "changes", id);
+  if (!isDir(changeDir)) {
+    console.error(c.red("error:") + ` change "${id}" not found at ${relPath(projectRoot, changeDir)}`);
+    return 1;
+  }
+
+  let failures = 0;
+
+  // 1. Structural analysis — same checks analyze runs before an apply.
+  console.log(c.gray("──── 1/3 structure (analyze)"));
+  const analyze = await import("./analyze.js");
+  if ((await analyze.run([id], new Map())) !== 0) failures += 1;
+
+  // 2. Ops dry-run: execute every MODIFIED delta's ops block against the
+  //    target spec in memory. An op that would fail at apply time (missing
+  //    header, no such criterion, unknown verb) is reported here, not days
+  //    later; a delta with no ops block is flagged as a manual merge so the
+  //    close is planned around it instead of surprised by it.
+  console.log(c.gray("──── 2/3 ops dry-run (what apply would do)"));
+  const deltaFiles = walk(path.join(changeDir, "specs")).filter((p) => p.endsWith("delta.md"));
+  let opsFindings = 0;
+  for (const deltaPath of deltaFiles) {
+    const text = read(deltaPath);
+    if (parseOperation(text) !== "MODIFIED") continue;
+    const capability = parseCapabilityFromDelta(text, deltaPath);
+    const rel = relPath(projectRoot, deltaPath);
+    const ops = extractOps(text);
+    if (ops.length === 0) {
+      console.log(c.yellow("⚠ ") + `${rel}: no ops block — apply will print a manual-merge pointer`);
+      continue;
+    }
+    const targetPath = path.join(projectRoot, ".doctrina", "specs", capability ?? "", "spec.md");
+    if (!capability || !exists(targetPath)) {
+      console.log(c.red("✗ ") + `${rel}: MODIFIED targets missing spec`);
+      opsFindings += 1;
+      continue;
+    }
+    const result = applyOps(read(targetPath), ops);
+    if (result.errors.length > 0) {
+      console.log(c.red("✗ ") + `${rel}: ${result.errors.length} op error${result.errors.length === 1 ? "" : "s"} (apply would refuse):`);
+      for (const e of result.errors) console.log(`    - ${e}`);
+      opsFindings += 1;
+    } else {
+      console.log(c.green("✓ ") + `${rel}: ${result.applied.length} op${result.applied.length === 1 ? "" : "s"} would apply cleanly`);
+    }
+  }
+  if (deltaFiles.length === 0) console.log(c.gray("- no spec deltas"));
+  if (opsFindings > 0) failures += 1;
+
+  // 3. Archive gate preview: what archive will refuse, listed with the fix.
+  console.log(c.gray("──── 3/3 archive gate"));
+  const blockers = collectArchiveBlockers(changeDir);
+  if (blockers.length === 0) {
+    console.log(c.green("✓ ") + "archive gate clear (all boxes checked)");
+  } else {
+    failures += 1;
+    for (const b of blockers) console.log(c.red("✗ ") + b);
+    console.log(c.gray("    check them off as they land, or in bulk: ") + c.cyan(`doctrina change tick ${id} --all`));
+  }
+
+  // Advisory (never gates): accepted ADRs citing the touched capabilities.
+  const caps = [...new Set(deltaFiles.map((p) => parseCapabilityFromDelta(read(p), p)).filter(Boolean))].sort();
+  console.log("");
+  printAdrCheckpoint(projectRoot, caps, { c });
+
+  console.log("");
+  if (failures === 0) {
+    console.log(c.green("ok") + ` ${id} is ready to close: ` + c.cyan(`doctrina close ${id}`));
+    return 0;
+  }
+  console.log(c.red("fail") + ` ${failures} area${failures === 1 ? "" : "s"} would block the close — fix them first`);
+  return 1;
+}
+
+// Bulk checkbox marking (operator review 2026-07-19 §3.5: "marcar checkbox
+// não tem comando nenhum" — it was sed/Python by hand). With no args it
+// LISTS the unchecked boxes with ordinals; `tick <id> 2 5` checks those;
+// `tick <id> --all` checks everything (tasks.md + the proposal's
+// ## Verification). Ticking is a claim of completion — the honest gate is
+// still archive/verify; this only removes the mechanical friction.
+function changeTick(args, flags) {
+  const id = args[0];
+  if (!id) {
+    console.error(c.red("error:") + " change tick requires <id> [ordinals... | --all]");
+    return 2;
+  }
+  const projectRoot = process.cwd();
+  ensureDoctrinaProject(projectRoot);
+  const changeDir = path.join(projectRoot, ".doctrina", "changes", id);
+  if (!isDir(changeDir)) {
+    console.error(c.red("error:") + ` change "${id}" not found at ${relPath(projectRoot, changeDir)}`);
+    return 1;
+  }
+
+  // Unified ordinal space over both files, in reading order: every unchecked
+  // `- [ ]` in tasks.md, then in the proposal's ## Verification section.
+  const files = [
+    { label: "tasks.md", path: path.join(changeDir, "tasks.md"), section: null },
+    { label: "proposal.md ## Verification", path: path.join(changeDir, "proposal.md"), section: "Verification" },
+  ];
+  const boxes = [];
+  for (const f of files) {
+    if (!isFile(f.path)) continue;
+    const lines = read(f.path).split(/\r?\n/);
+    const inScope = f.section === null
+      ? () => true
+      : (() => {
+          const scoped = new Set();
+          let inSection = false;
+          for (let i = 0; i < lines.length; i++) {
+            if (/^##\s+/.test(lines[i])) inSection = new RegExp(`^##\\s+${f.section}\\b`, "i").test(lines[i]);
+            else if (inSection) scoped.add(i);
+          }
+          return (i) => scoped.has(i);
+        })();
+    for (let i = 0; i < lines.length; i++) {
+      if (/^\s*-\s*\[ \]/.test(lines[i]) && inScope(i)) {
+        boxes.push({ file: f, lineIndex: i, text: lines[i].replace(/^\s*-\s*\[ \]\s*/, "") });
+      }
+    }
+  }
+
+  if (boxes.length === 0) {
+    console.log(c.green("ok") + " no unchecked boxes in tasks.md or the proposal's ## Verification");
+    return 0;
+  }
+
+  const all = flagBool(flags, "all", false);
+  const ordinals = args.slice(1).map(Number);
+  const isPlaceholder = (box) => box.text.trim() === "";
+  if (!all && ordinals.length === 0) {
+    console.log(c.bold(`Unchecked boxes in ${id}:`));
+    console.log("");
+    for (let i = 0; i < boxes.length; i++) {
+      const label = isPlaceholder(boxes[i])
+        ? c.yellow("(scaffold placeholder — write the real task, or delete the line)")
+        : boxes[i].text;
+      console.log(`  ${String(i + 1).padStart(3)}. ${label}  ${c.gray(`[${boxes[i].file.label}]`)}`);
+    }
+    console.log("");
+    console.log(c.gray("tick some: ") + c.cyan(`doctrina change tick ${id} 1 3`) + c.gray(" · all: ") + c.cyan(`doctrina change tick ${id} --all`));
+    return 0;
+  }
+
+  const picked = all ? boxes.map((_, i) => i + 1) : ordinals;
+  for (const n of picked) {
+    if (!Number.isInteger(n) || n < 1 || n > boxes.length) {
+      console.error(c.red("error:") + ` no box #${n} (1..${boxes.length} — run \`doctrina change tick ${id}\` to list)`);
+      return 2;
+    }
+  }
+  // Ticking an empty scaffold placeholder is a meaningless claim — it is how
+  // a hollow change games the archive gate. Refuse (all-or-nothing) and name
+  // the fix; analyze/close hard-fail on the placeholders regardless.
+  const empties = picked.filter((n) => isPlaceholder(boxes[n - 1]));
+  if (empties.length > 0) {
+    console.error(c.red("error:") + ` box${empties.length === 1 ? "" : "es"} ${empties.join(", ")} ${empties.length === 1 ? "is a" : "are"} scaffold placeholder${empties.length === 1 ? "" : "s"} with no text — nothing was ticked`);
+    console.error(c.gray("hint: ") + "write the real task on each line (or delete it), then tick");
+    return 2;
+  }
+
+  // Group edits per file so each file is read/written once.
+  const byPath = new Map();
+  for (const n of picked) {
+    const box = boxes[n - 1];
+    if (!byPath.has(box.file.path)) byPath.set(box.file.path, []);
+    byPath.get(box.file.path).push(box);
+  }
+  for (const [filePath, hits] of byPath) {
+    const lines = read(filePath).split(/\r?\n/);
+    for (const box of hits) {
+      lines[box.lineIndex] = lines[box.lineIndex].replace(/\[ \]/, "[x]");
+    }
+    write(filePath, lines.join("\n"), { force: true });
+  }
+  console.log(c.green("ticked ") + `${picked.length} box${picked.length === 1 ? "" : "es"} in ${byPath.size} file${byPath.size === 1 ? "" : "s"}`);
+  return 0;
+}
+
 function changeArchive(args, flags) {
   const id = args[0];
   if (!id) {
@@ -589,7 +813,7 @@ Subcommands:
                          (--chore / --no-spec: a spec-less change for infra /
                          docs / build that still gets a proposal + ledger;
                          --design: also scaffold design.md, opt-in)
-  apply <id>             Apply spec deltas: ADDED writes the full body (it
+  apply <id...>          Apply spec deltas: ADDED writes the full body (it
                          also REPLACES a target that is still the untouched
                          \`spec new\` scaffold — the canonical new-capability
                          flow; real content refuses), REMOVED deletes,
@@ -597,19 +821,34 @@ Subcommands:
                          (set-header / bump-version / set-criterion / ...),
                          MODIFIED without one prints a manual-merge pointer.
                          On any spec write the index is rebuilt from the tree.
-  archive <id>           Move the change to .doctrina/changes/archive/YYYY-MM-DD-<id>/
+  archive <id...>        Move the change to .doctrina/changes/archive/YYYY-MM-DD-<id>/
+  check <id...>          Pre-close dry-run, read-only: analyze's structural
+                         checks + every ops block executed in memory against
+                         its target + the archive gate preview + an advisory
+                         list of accepted ADRs citing the touched capabilities.
+                         Everything close would refuse, listed BEFORE it runs.
+  tick <id> [n... |--all]  List the unchecked boxes (tasks.md + proposal
+                         ## Verification) with ordinals; tick the given ones,
+                         or every one with --all. No args = list only.
   abandon <id>           Delete an open change folder and its index entry, and
                          record the abandonment in the ledger ([--reason "..."]).
   diff <id>              Preview every spec delta: line diff for MODIFIED,
                          summary for ADDED/REMOVED. Read-only.
 
+apply / archive / check accept multiple ids (batch close of a backlog); the
+exit code is the worst per-id result.
+
 A MODIFIED delta may carry a fenced operations block that \`apply\` executes:
   \`\`\`ops
   set-header Implementation: verified — durable adapter (\`src/db.ts\`)
   bump-version minor
   set-criterion 1: verified
   append-criterion [unverified] new signal — verified by \`test/x.test.ts\`
+  append-requirement event: When <trigger>, the system shall <action>.
+  replace-requirement ubiquitous 2: The system shall <action>.
   \`\`\`
+append-* ops resolve numbering/position at apply time, so concurrent open
+changes appending to the same spec cannot collide.
 
 Options:
   --force                Overwrite existing files (where applicable)

package/src/commands/clarify.js

@@ -2,7 +2,7 @@ import path from "node:path";
 import process from "node:process";
 import { readdirSync } from "node:fs";
 import { exists, isDir, isFile, read, relPath, walk } from "../lib/fs-ops.js";
-import { flagBool } from "../lib/args.js";
+import { flagBool, flagString } from "../lib/args.js";
 import { c } from "../lib/colors.js";
 
 // Two lexicons, one linter (0.11.0 field review item 3: an English-only
@@ -78,16 +78,30 @@ function detectLang(text) {
   return pt > en ? "pt" : "en";
 }
 
-function rulesFor(projectRoot, text) {
-  const declared = projectLanguage(projectRoot);
-  const lang = declared ?? detectLang(text);
+function rulesFor(projectRoot, text, forcedLang = null) {
+  const lang = forcedLang ?? projectLanguage(projectRoot) ?? detectLang(text);
   return lang === "pt" ? RULES_PT : RULES_EN;
 }
 
+// --lang pt|en wins over the project config and the per-file heuristic
+// (operator review 2026-07-19 §4.8: on a PT-BR project with no config.json,
+// a file whose stopword count tips English gets the EN lexicon and "some" —
+// the verb *sumir* — is flagged as the vague quantifier). One flag, zero
+// guessing; persist it with .doctrina/config.json { "language": "pt-BR" }.
+function forcedLang(flags) {
+  const raw = flagString(flags, "lang");
+  if (!raw || raw === true) return null;
+  const lang = String(raw).toLowerCase();
+  if (lang.startsWith("pt")) return "pt";
+  if (lang.startsWith("en")) return "en";
+  console.error(c.yellow("warn:") + ` unknown --lang "${raw}" (use pt|en) — falling back to detection`);
+  return null;
+}
+
 export async function run(positional, flags) {
   const projectRoot = process.cwd();
 
-  if (flagBool(flags, "all", false)) return clarifyAll(projectRoot);
+  if (flagBool(flags, "all", false)) return clarifyAll(projectRoot, forcedLang(flags));
 
   const target = positional[0];
   if (!target) {
@@ -103,7 +117,7 @@ export async function run(positional, flags) {
   console.log(`clarify ${relPath(projectRoot, fullPath)}`);
   console.log("");
 
-  const smells = scanFile(fullPath);
+  const smells = scanFile(fullPath, projectRoot, forcedLang(flags));
   for (const s of smells) {
     console.log(`${c.yellow("⚠")} line ${s.line}: ${s.rule} "${s.token}" — ${s.hint}`);
   }
@@ -122,7 +136,7 @@ export async function run(positional, flags) {
 // and clarify each. ADRs are immutable and the archive is history, so
 // neither is included; AGENTS.md is dense command text, a different
 // register from prose specs.
-function clarifyAll(projectRoot) {
+function clarifyAll(projectRoot, lang = null) {
   if (!exists(path.join(projectRoot, ".doctrina"))) {
     throw new Error("not a Doctrina project (no .doctrina/ in cwd). Run `doctrina init` first.");
   }
@@ -149,7 +163,7 @@ function clarifyAll(projectRoot) {
 
   let total = 0;
   for (const f of files) {
-    const smells = scanFile(f);
+    const smells = scanFile(f, projectRoot, lang);
     if (smells.length === 0) continue;
     total += smells.length;
     const rel = relPath(projectRoot, f);
@@ -167,10 +181,10 @@ function clarifyAll(projectRoot) {
   return 1;
 }
 
-function scanFile(fullPath, projectRoot = process.cwd()) {
+function scanFile(fullPath, projectRoot = process.cwd(), lang = null) {
   const text = read(fullPath);
   const skippedRanges = collectSkippedRanges(text);
-  const rules = rulesFor(projectRoot, text);
+  const rules = rulesFor(projectRoot, text, lang);
   const smells = [];
 
   // Per-line rules: regex pass with skip-range filter. A line carrying the
@@ -257,20 +271,20 @@ function findAcceptanceLine(text) {
 }
 
 export const help = `
-Usage: doctrina clarify <path>
-       doctrina clarify --all
+Usage: doctrina clarify <path> [--lang pt|en]
+       doctrina clarify --all [--lang pt|en]
 
 Read a Markdown file and report weasel words, vague quantifiers,
 placeholders, and empty Acceptance criteria sections. Exits 0 when
 no smells are found, 1 otherwise. Matches inside fenced code
 blocks, HTML comments, and inline backtick spans are skipped.
 
-Language-aware: declare it in .doctrina/config.json
-({ "language": "pt-BR" }) or let a per-file stopword count decide.
-Portuguese mode uses a PT lexicon (bare TODO is the pronoun, only
-"TODO:" is a marker; "some"/"several" are not smells). A line ending
-in <!-- clarify:ok --> is author-accepted and never flagged — the
-escape hatch for a false positive.
+Language-aware: --lang pt|en forces the lexicon; otherwise
+.doctrina/config.json ({ "language": "pt-BR" }) decides, else a
+per-file stopword count. Portuguese mode uses a PT lexicon (bare
+TODO is the pronoun, only "TODO:" is a marker; "some"/"several" are
+not smells). A line ending in <!-- clarify:ok --> is author-accepted
+and never flagged — the escape hatch for a false positive.
 
 With --all, every living document is scanned in one pass:
 product.md, capability specs, open changes, and skills. ADRs

package/src/commands/close.js

@@ -4,12 +4,14 @@ import { exists, isFile, read, walk } from "../lib/fs-ops.js";
 import { flagBool } from "../lib/args.js";
 import { c } from "../lib/colors.js";
 import { parseCapabilityFromDelta } from "./change.js";
+import { printAdrCheckpoint } from "../lib/adr-guard.js";
 import * as analyze from "./analyze.js";
 import * as change from "./change.js";
 import * as verify from "./verify.js";
 import * as coverage from "./coverage.js";
 import * as trace from "./trace.js";
 import * as validate from "./validate.js";
+import * as skill from "./skill.js";
 
 // One-command close (review 2026-06-27 passive-user feature #2). The work
 // playbook lists the closing sequence — analyze → apply → verify → coverage →
@@ -20,8 +22,7 @@ import * as validate from "./validate.js";
 // driver over the existing commands; it adds no new checks of its own.
 
 export async function run(positional, flags) {
-  const id = positional[0];
-  if (!id) {
+  if (positional.length === 0) {
     console.error(c.red("error:") + " close requires a change <id> (e.g. doctrina close 0001-add-login)");
     return 2;
   }
@@ -30,6 +31,27 @@ export async function run(positional, flags) {
     throw new Error("not a Doctrina project (no .doctrina/ in cwd). Run `doctrina init` first.");
   }
 
+  // Batch close (operator review 2026-07-19 §4.5): each id closes
+  // independently, worst exit code wins, so a 9-change implementation lot is
+  // one command, not nine.
+  let worst = 0;
+  for (const id of positional) {
+    if (positional.length > 1) {
+      console.log("");
+      console.log(c.bold(`════ close ${id}`));
+    }
+    worst = Math.max(worst, await closeOne(projectRoot, id, flags));
+  }
+  if (positional.length > 1) {
+    console.log("");
+    console.log(worst === 0
+      ? c.green("ok") + ` all ${positional.length} changes closed`
+      : c.red("fail") + " at least one close stopped — see above");
+  }
+  return worst;
+}
+
+async function closeOne(projectRoot, id, flags) {
   const force = flagBool(flags, "force", false);
   const archiveFlags = force ? new Map([["force", true]]) : new Map();
 
@@ -52,6 +74,20 @@ export async function run(positional, flags) {
   const verifyConfigured = isFile(path.join(projectRoot, ".doctrina", "verify.json"));
   const steps = [
     { label: "analyze", rerun: `doctrina analyze ${id}`, run: () => analyze.run([id], new Map()) },
+    // ADR checkpoint (operator review §4.6): the playbook's "record an ADR"
+    // step was skippable in silence. Advisory — it names the accepted ADRs
+    // whose text cites the touched capabilities and the amend commands, but
+    // an ADR merely mentioning a capability is normal, so it never blocks.
+    {
+      label: "ADR checkpoint (advisory)",
+      rerun: "doctrina decision list",
+      run: async () => {
+        if (printAdrCheckpoint(projectRoot, touched, { c }) === 0) {
+          console.log(c.green("ok") + " no accepted ADR cites the touched capabilities");
+        }
+        return 0;
+      },
+    },
     { label: "apply", rerun: `doctrina change apply ${id}`, run: () => change.run(["apply", id], new Map()) },
     verifyConfigured
       ? { label: "verify", rerun: "doctrina verify", run: () => verify.run([], new Map()) }
@@ -68,7 +104,7 @@ export async function run(positional, flags) {
     { label: "validate", rerun: "doctrina validate", run: () => validate.run([], new Map()) },
   ];
 
-  console.log(c.bold(`Closing change ${id}`) + c.gray(" — analyze → apply → verify → coverage → trace → archive → validate"));
+  console.log(c.bold(`Closing change ${id}`) + c.gray(" — analyze → ADR checkpoint → apply → verify → coverage → trace → archive → validate"));
 
   for (let i = 0; i < steps.length; i++) {
     const step = steps[i];
@@ -95,6 +131,16 @@ export async function run(positional, flags) {
     }
   }
 
+  // Capture the lesson while it is fresh (operator review §4.7): surface the
+  // fix-shaped lessons not yet written as skills, right where the operator
+  // just proved they finish what they start. Advisory — a listing, never a
+  // gate, and a suggest failure never un-closes the change.
+  console.log("");
+  console.log(c.gray("──── skills (advisory)"));
+  try {
+    await skill.run(["suggest"], new Map());
+  } catch { /* advisory only */ }
+
   console.log("");
   console.log(c.green(`✓ change ${id} closed`) + c.gray(" — verified, archived, and validated."));
   console.log(c.gray("Next: ") + c.cyan("doctrina next"));
@@ -115,21 +161,28 @@ function touchedCapabilities(projectRoot, id) {
 }
 
 export const help = `
-Usage: doctrina close <id> [--force]
+Usage: doctrina close <id...> [--force]
 
 Run the whole closing sequence for a change in one pass, stopping at the
 first failure with the exact command to rerun:
 
-  analyze → change apply → verify → coverage --strict (scoped to the
-  change's touched capabilities) → trace → change archive → validate
+  analyze → ADR checkpoint (advisory) → change apply → verify → coverage
+  --strict (scoped to the change's touched capabilities) → trace → change
+  archive → validate → skill suggest (advisory)
 
 The coverage gate is scoped to the capabilities the change's deltas touch,
 so a deliberately deferred spec elsewhere cannot block an unrelated close;
 a change with no deltas gates on the whole tree. verify is skipped (with a
-note) when no .doctrina/verify.json is declared; trace is advisory (a
-report, never a blocker). This is a driver over the existing commands — it
-adds no checks of its own — so the agent makes one call instead of seven
-and the human approves once.
+note) when no .doctrina/verify.json is declared; trace, the ADR checkpoint
+(accepted ADRs citing the touched capabilities — amend via \`decision
+supersede\`, not silence), and the closing skill-suggest listing are
+advisory (reports, never blockers). This is a driver over the existing
+commands so the agent makes one call instead of nine and the human
+approves once.
+
+Multiple ids close in sequence, each independently; the exit code is the
+worst per-id result. Preview what close would refuse: \`doctrina change
+check <id>\`.
 
 Options:
   --force    Pass through to \`change archive\` (archive even if verification

package/src/commands/init.js

@@ -2,6 +2,7 @@ import path from "node:path";
 import process from "node:process";
 import { exists, isDir, isFile, read, relPath, write } from "../lib/fs-ops.js";
 import { locateTemplatesDir, loadTemplateTree, materialiseEntry, substitute } from "../lib/templates.js";
+import { surfaceBlock, findSurfaceBlock } from "../lib/commands.js";
 import { today } from "../lib/dates.js";
 import { cliVersion } from "../lib/version.js";
 import { flagBool, flagString } from "../lib/args.js";
@@ -108,10 +109,13 @@ export async function run(_positional, flags) {
     FRAMEWORK_VERSION: cliVersion(),
   };
 
-  // Root AGENTS.md — with optional --from base content prepended.
+  // Root AGENTS.md — with optional --from base content prepended. The
+  // doctrina:surface block is regenerated from the installed catalog at init
+  // time, so a freshly scaffolded hub can never document a stale surface even
+  // if the static template lags a release (ADR 0015).
   const agentsTemplatePath = path.join(templatesDir, "AGENTS.md.template");
   const agentsTemplateBody = read(agentsTemplatePath);
-  const projectAgents = substitute(agentsTemplateBody, tokens);
+  const projectAgents = refreshSurfaceBlock(substitute(agentsTemplateBody, tokens));
   const finalAgents = fromAgentsContent
     ? fromAgentsContent.replace(/\n+$/, "") + "\n\n---\n\n## Project-specific\n\n" + projectAgents
     : projectAgents;
@@ -178,6 +182,15 @@ export async function run(_positional, flags) {
   return 0;
 }
 
+// Replace the template's doctrina:surface span with the one generated from
+// the running CLI's catalog; pass the text through untouched when the
+// template carries no markers (older custom templates).
+function refreshSurfaceBlock(text) {
+  const block = findSurfaceBlock(text);
+  if (!block) return text;
+  return text.slice(0, block.start) + surfaceBlock() + text.slice(block.end);
+}
+
 // First non-empty line of the intake, stripped of Markdown heading marks
 // and clipped, as the one-line description token for the templates.
 function firstLineSummary(text) {