doctrina-cli 0.12.0 → 0.14.0

package/src/lib/adapters.js

@@ -0,0 +1,140 @@
+// @ts-check
+import path from "node:path";
+import { readdirSync } from "node:fs";
+import { exists, isDir, isFile, read, relPath, walk } from "./fs-ops.js";
+import { locateTemplatesDir, substitute } from "./templates.js";
+
+// Agent adapters: the thin per-agent files that point at AGENTS.md.
+//
+// Installing one used to be reachable ONLY through a full `doctrina init`
+// run, and `init` refuses to run twice — so `init --force` was the only
+// path, and it regenerated AGENTS.md and product.md from blank templates,
+// destroying every hand-authored rule and the entire product definition
+// with no warning (audit item C1, data loss). This module owns adapters as
+// their own concern so adding one can be strictly additive.
+//
+// Three states, which the old surface could not tell apart:
+//   installed      — the adapter's files are present in the project
+//   available      — the adapter ships files and none are installed
+//   native         — the agent reads AGENTS.md directly and needs no file
+//                    (its template dir carries only a README)
+
+export const ADAPTER_STATES = Object.freeze({
+  INSTALLED: "installed",
+  AVAILABLE: "available",
+  NATIVE: "native",
+});
+
+// Where a named adapter's templates live. A project-local adapter under
+// `.doctrina/templates/adapters/<name>/` wins over the bundled one, so a
+// team can ship an adapter for an agent Doctrina does not know about.
+export function resolveAdapterDir(projectRoot, name) {
+  const local = path.join(projectRoot, ".doctrina", "templates", "adapters", name);
+  if (isDir(local) && walk(local).length > 0) return { dir: local, source: "project" };
+  const bundledRoot = path.join(locateTemplatesDir(), "adapters");
+  const bundled = path.join(bundledRoot, name);
+  if (isDir(bundled)) return { dir: bundled, source: "bundled" };
+  return null;
+}
+
+// Every adapter name known to this project: bundled plus project-local.
+export function listAdapterNames(projectRoot) {
+  const names = new Set();
+  try {
+    const bundledRoot = path.join(locateTemplatesDir(), "adapters");
+    if (isDir(bundledRoot)) {
+      for (const e of readdirSync(bundledRoot)) {
+        if (isDir(path.join(bundledRoot, e))) names.add(e);
+      }
+    }
+  } catch { /* unusual install without a templates dir */ }
+  const localRoot = path.join(projectRoot, ".doctrina", "templates", "adapters");
+  if (isDir(localRoot)) {
+    for (const e of readdirSync(localRoot)) {
+      if (isDir(path.join(localRoot, e))) names.add(e);
+    }
+  }
+  return [...names].sort();
+}
+
+// The files a named adapter would write, as project-relative POSIX paths
+// paired with their template source. A README inside the adapter template
+// dir documents the adapter and is never materialised.
+export function adapterFiles(projectRoot, name) {
+  const resolved = resolveAdapterDir(projectRoot, name);
+  if (!resolved) return null;
+  const out = [];
+  for (const templatePath of walk(resolved.dir)) {
+    const rel = relPath(resolved.dir, templatePath).replace(/\\/g, "/");
+    if (rel === "README.md" || rel.endsWith(".gitkeep")) continue;
+    out.push({
+      templatePath,
+      relativePath: rel.replace(/\.template$/, ""),
+    });
+  }
+  return { source: resolved.source, files: out.sort((a, b) => a.relativePath.localeCompare(b.relativePath)) };
+}
+
+// Adapter state plus the files backing it, for `adapter list`.
+export function describeAdapter(projectRoot, name) {
+  const spec = adapterFiles(projectRoot, name);
+  if (!spec) return { name, state: ADAPTER_STATES.AVAILABLE, source: "unknown", files: [], installed: [] };
+  if (spec.files.length === 0) {
+    // Reads AGENTS.md natively — "no adapter installed" and "no adapter
+    // needed" were indistinguishable before this distinction existed.
+    return { name, state: ADAPTER_STATES.NATIVE, source: spec.source, files: [], installed: [] };
+  }
+  const installed = spec.files.filter((f) => isFile(path.join(projectRoot, f.relativePath)));
+  return {
+    name,
+    source: spec.source,
+    files: spec.files,
+    installed,
+    state: installed.length > 0 ? ADAPTER_STATES.INSTALLED : ADAPTER_STATES.AVAILABLE,
+  };
+}
+
+// The AGENTS.md path an adapter file should point at, relative to its own
+// location — a nested command file needs "../../AGENTS.md".
+export function agentsMdPathFor(relativePath) {
+  const depth = relativePath.split("/").length - 1;
+  return depth === 0 ? "AGENTS.md" : "../".repeat(depth) + "AGENTS.md";
+}
+
+// Is this adapter file a HUB POINTER — a file whose job is to route the
+// agent at AGENTS.md?
+//
+// Declared by the template itself: a template that uses the
+// {{AGENTS_MD_PATH}} token is saying "I point at the hub". Everything else
+// is a command shim — a Claude/Cursor slash command like `/doctrina-status`
+// whose job is to invoke the CLI, and which reaches the hub through its
+// parent CLAUDE.md rather than by naming it.
+//
+// This distinction is the fix for audit item C2: the pointer check demanded
+// the literal string "AGENTS.md" in EVERY adapter file, so a clean
+// `init --agent claude` failed `templates check` on four command shims that
+// were never pointers, and neither suggested remedy could clear it.
+export function isHubPointer(file) {
+  return read(file.templatePath).includes("{{AGENTS_MD_PATH}}");
+}
+
+// Render one adapter file's body for this project.
+export function renderAdapterFile(file, tokens) {
+  return substitute(read(file.templatePath), {
+    ...tokens,
+    AGENTS_MD_PATH: agentsMdPathFor(file.relativePath),
+  });
+}
+
+// Is this project-relative path one that some adapter owns? Used by
+// `adapter remove` so it deletes only what an adapter created, and by
+// `init` so it never counts adapter files as user content.
+export function isAdapterOwnedPath(projectRoot, relPathPosix) {
+  for (const name of listAdapterNames(projectRoot)) {
+    const spec = adapterFiles(projectRoot, name);
+    if (spec?.files.some((f) => f.relativePath === relPathPosix)) return true;
+  }
+  return false;
+}
+
+export { exists };

package/src/lib/adr-guard.js

@@ -0,0 +1,47 @@
+// @ts-check
+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/args.js

@@ -1,3 +1,4 @@
+// @ts-check
 // Tiny argv parser. Returns { positional: string[], flags: Map<string, string|boolean> }.
 // Supports:
 //   --flag                          -> flags.set("flag", true)
@@ -82,6 +83,15 @@ export function flagString(flags, name, fallback = undefined) {
   return String(v);
 }
 
+// True when a value-taking flag was written WITHOUT one — `--budget` at the
+// end of the line, or `--budget -100`, where the parser cannot tell a value
+// from the next flag. `flagString` reports both as absent, so without this
+// a mistyped number silently becomes "use the default", which is the one
+// outcome the author definitely did not ask for.
+export function flagGivenWithoutValue(flags, name) {
+  return flags.get(name) === true;
+}
+
 export function flagBool(flags, name, fallback = false) {
   const v = flags.get(name);
   if (v === undefined) return fallback;

package/src/lib/clarity.js

@@ -1,3 +1,4 @@
+// @ts-check
 // Deterministic under-specification detector for free-text briefs and
 // intakes — the clarification gate (review Topic A). It does NOT judge
 // meaning (that stays the agent's job, ADR 0005); it flags input that is

package/src/lib/colors.js

@@ -1,3 +1,4 @@
+// @ts-check
 // ANSI colour helpers. Falls back to plain text when:
 //   - stdout is not a TTY, OR
 //   - the NO_COLOR environment variable is set (any value), OR

package/src/lib/commands.js

@@ -1,3 +1,4 @@
+// @ts-check
 // Single canonical list of top-level `doctrina` commands.
 //
 // This is the one place the command surface is named. `src/index.js` builds
@@ -13,7 +14,7 @@ export const COMMAND_NAMES = [
   // bootstrap / day-to-day
   "init", "intake", "work",
   // authoring
-  "spec", "change", "contract", "decision", "skill", "intent",
+  "spec", "change", "contract", "decision", "skill", "intent", "adapter",
   // read / orient
   "prime", "context", "show", "search", "status", "next", "why", "handoff", "constitution",
   // gates
@@ -40,8 +41,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)"],
@@ -52,10 +55,14 @@ export const OPERATIONS = [
   ["decision land", "Record that an accepted ADR is now implemented (non-mutating)"],
   ["decision supersede", "Create a new ADR that supersedes an existing one"],
   ["decision list", "List ADRs with status, date, and title"],
+  ["decision scope", "Show and propose the capabilities each ADR governs"],
   ["skill new", "Scaffold an on-demand procedural memory skill"],
   ["skill list", "List skills with their descriptions"],
   ["skill sync", "Mirror skill frontmatter descriptions into index.json"],
   ["skill suggest", "Surface fix-shaped lessons worth a skill (--write scaffolds)"],
+  ["adapter list", "Inventory agent adapters: installed / available / native"],
+  ["adapter add", "Install one agent adapter (additive; never touches AGENTS.md)"],
+  ["adapter remove", "Delete the files an adapter installed"],
   ["intent add", "Append a new product intent anchor post-intake (- [SC5] ...)"],
   ["intent list", "List product.md intent anchors in document order"],
   ["analyze", "Inspect a change folder before applying"],
@@ -88,12 +95,263 @@ export const OPERATIONS = [
   ["upgrade", "Bring an existing project up to the installed CLI (--write applies)"],
 ];
 
+// ---------------------------------------------------------------------------
+// Per-command PURPOSE and WHEN (audit item M2).
+//
+// The generated surface block was a name index. An agent reading
+// "`doctrina trace --strict`" learns that the command exists and nothing
+// about what triggers it, what it costs, or what it returns — so learning
+// the surface meant running `--help` 35 times, roughly the whole context
+// budget spent on a lookup.
+//
+// Doctrina already solved this for SKILLS: `context` prints a description
+// and a `when:` trigger per skill and tells the agent to load the body only
+// when the trigger fires. Commands get the same treatment.
+//
+// `when` is the moment you reach for it, in the agent's own terms.
+// `purpose` is one line on what it does. Both are required: a command that
+// cannot state its trigger has not earned a place on the surface, and
+// `templates check` fails when either is missing.
+export const COMMAND_META = {
+  init:         { moment: "Bootstrap",  when: "starting a project that has no AGENTS.md yet", purpose: "scaffold AGENTS.md and .doctrina/" },
+  intake:       { moment: "Bootstrap",  when: "you have a full project description and no specs yet", purpose: "store the intent and print the bootstrap playbook" },
+  adapter:      { moment: "Bootstrap",  when: "adding or removing an agent's pointer files", purpose: "install/remove agent adapters (additive)" },
+
+  prime:        { moment: "Orient",     when: "at the START of every session", purpose: "gates, standing rules, and open work in one read" },
+  status:       { moment: "Orient",     when: "you need the health of the tree at a glance", purpose: "index, coverage, trace, and artifact counts" },
+  next:         { moment: "Orient",     when: "you finished something and do not know what follows", purpose: "the recommended next workflow action" },
+  context:      { moment: "Orient",     when: "before working on any task, to load the right files", purpose: "the read pack, assembled to fit a token budget" },
+  show:         { moment: "Orient",     when: "you need one requirement, criterion, or ADR, not a file", purpose: "point-read a single artifact by reference" },
+  search:       { moment: "Orient",     when: "you do not know which artifact mentions a term", purpose: "search the artifact tree, grouped by category" },
+  why:          { moment: "Orient",     when: "you need to justify or trace a capability's existence", purpose: "provenance: intent, proof, ADRs, and history" },
+  constitution: { moment: "Orient",     when: "you need the standing rules before deciding something", purpose: "accepted ADRs and product non-goals" },
+  handoff:      { moment: "Orient",     when: "BEFORE compaction or handing over to another session", purpose: "a resume note: open work, task state, next command" },
+
+  work:         { moment: "Change",     when: "any request arrives that changes behaviour", purpose: "scaffold a change and print the playbook to execute" },
+  spec:         { moment: "Change",     when: "a capability needs creating or its headers advancing", purpose: "create, list, and edit capability specs" },
+  change:       { moment: "Change",     when: "driving a change through its lifecycle by hand", purpose: "new / apply / archive / check / tick / diff / abandon" },
+  decision:     { moment: "Change",     when: "the change decides something a later session must not relitigate", purpose: "record, accept, land, scope, and supersede ADRs" },
+  contract:     { moment: "Change",     when: "the change touches ports, env vars, or public endpoints", purpose: "own and verify the integration surface" },
+  intent:       { moment: "Change",     when: "new product intent appears after the intake", purpose: "append and list product intent anchors" },
+  skill:        { moment: "Change",     when: "a lesson is worth not relearning", purpose: "capture on-demand procedural memory" },
+
+  analyze:      { moment: "Gate",       when: "before applying a change", purpose: "structural pre-flight on a change folder" },
+  clarify:      { moment: "Gate",       when: "before applying, or before opening a PR", purpose: "smell-test Markdown for ambiguity" },
+  validate:     { moment: "Gate",       when: "after any artifact edit, and before considering work done", purpose: "schema, structure, EARS, and index drift" },
+  coverage:     { moment: "Gate",       when: "before claiming a capability is proven", purpose: "acceptance criteria against cited evidence" },
+  trace:        { moment: "Gate",       when: "checking that product intent still maps to capabilities", purpose: "intent provenance across the tree" },
+  review:       { moment: "Gate",       when: "before handing work back, to self-review it", purpose: "conformance of your changes vs specs/ADRs/contracts" },
+  verify:       { moment: "Gate",       when: "the real build gate must run", purpose: "the project's declared typecheck/test/build checks" },
+  close:        { moment: "Gate",       when: "a change is implemented and ready to finish", purpose: "the whole closing sequence in one attested pass" },
+  doctor:       { moment: "Gate",       when: "something looks wrong and you do not know which gate to ask", purpose: "aggregate diagnostic with per-finding remedies" },
+
+  templates:    { moment: "Maintain",   when: "after upgrading the CLI, or to customise a scaffold", purpose: "inspect, check, and refresh the template shape" },
+  upgrade:      { moment: "Maintain",   when: "you just updated the doctrina-cli package", purpose: "bring this project up to the installed CLI" },
+  index:        { moment: "Maintain",   when: "the index drifted from the tree", purpose: "regenerate index.json from the artifacts on disk" },
+  hooks:        { moment: "Maintain",   when: "setting up a repo so drift cannot be committed", purpose: "install the pre-commit gate" },
+  watch:        { moment: "Maintain",   when: "you want the tree re-synced on every save", purpose: "re-run validate --fix and next continuously" },
+  metrics:      { moment: "Maintain",   when: "reporting adoption over a period", purpose: "local git-derived adoption metrics" },
+  report:       { moment: "Maintain",   when: "summarising a period for a human", purpose: "a Markdown digest of changes, gates, and git" },
+  completion:   { moment: "Maintain",   when: "setting up a human's shell", purpose: "print shell completions from the catalog" },
+};
+
+// The order moments appear in the generated block.
+export const MOMENTS = ["Bootstrap", "Orient", "Change", "Gate", "Maintain"];
+
 // The Commands block of `doctrina --help`, generated from OPERATIONS so the
 // printed surface can never omit an operation the catalog knows about.
 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 -->";
+
+
+// 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>] --for \"<task>\" --concat",
+  validate: "(--fix)",
+  coverage: "--strict",
+  trace: "--strict",
+  clarify: "--all (--lang pt|en)",
+  close: "<id...>",
+  upgrade: "--write",
+  prime: "(session start)",
+  handoff: "(before compaction/handover)",
+};
+
+// The declared size budget for the generated block. A surface that cannot
+// describe itself in this many lines is too large — the answer is to cut
+// commands (M8), never to raise the number.
+export const SURFACE_LINE_BUDGET = 40;
+
+// Moments an agent works IN get a trigger per command. "Maintain" is
+// compressed to one line: those commands are reached for by a human after
+// an upgrade or when wiring a repo, not by an agent mid-loop, and giving
+// each its own line pushed the block past its budget. The budget is the
+// forcing function — a surface that cannot describe itself in 40 lines is
+// too large, and the answer is to cut commands (M8), not to raise it.
+const COMPACT_MOMENTS = new Set(["Maintain"]);
+
+// The full managed section, heading included, between the markers.
+//
+// Organised by MOMENT rather than by category, and each line carries the
+// trigger: an agent scanning it learns WHEN to reach for a command, which
+// a name index never told it. Same shape `context` prints for skills —
+// description plus `when:`, body on demand.
+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 invocation = (cmd) => {
+    const subs = subsByCmd.get(cmd) ?? [];
+    const hint = SURFACE_HINTS[cmd] ? ` ${SURFACE_HINTS[cmd]}` : "";
+    return subs.length > 0 ? `${cmd} ${subs.join("|")}` : `${cmd}${hint}`;
+  };
+
+  const lines = [
+    "## Doctrina command surface (generated — reach for these, don't hand-author)",
+    "",
+    "Every command, with the moment you reach for it. The CLI scaffolds from",
+    "canonical templates and keeps `index.json` in sync — prefer it over",
+    "hand-authoring. Flags and detail: `doctrina <command> --help`.",
+  ];
+  for (const moment of MOMENTS) {
+    const cmds = COMMAND_NAMES.filter((n) => COMMAND_META[n]?.moment === moment);
+    if (cmds.length === 0) continue;
+    if (COMPACT_MOMENTS.has(moment)) {
+      // Each name still carries the `doctrina ` prefix: the compact line is
+      // read by validate's drift gate too, which only recognises a command
+      // reference in that form.
+      lines.push(`**${moment}** (triggers: \`doctrina <command> --help\`) — ` +
+        cmds.map((n) => `\`doctrina ${invocation(n)}\``).join(" · "));
+      continue;
+    }
+    lines.push(`**${moment}**`);
+    for (const cmd of cmds) {
+      const meta = COMMAND_META[cmd];
+      lines.push(`- \`doctrina ${invocation(cmd)}\` — ${meta.purpose}. *When:* ${meta.when}.`);
+    }
+  }
+  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}`;
+}
+
+// The block's CANONICAL POSITION, defined once — by the shipped template,
+// which is the only place the intended layout exists.
+//
+// `templates update` used to APPEND the block, so the same CLI produced two
+// different AGENTS.md layouts: third section on a fresh `init`, dead last
+// after an `upgrade` — behind 117 lines the agent reads first, which is the
+// attention problem design principle #2 exists to prevent, and with no
+// heading of its own before it, so a hierarchical parse read the command
+// surface as content of "## What never goes in this file" (audit item C4).
+//
+// Returns { after, before }: the heading text the block follows in the
+// template, and the heading it precedes. Either may be null.
+export function surfaceAnchors(templateText) {
+  const block = findSurfaceBlock(templateText);
+  if (!block) return { after: null, before: null };
+  const headingsBefore = [...templateText.slice(0, block.start).matchAll(/^##\s+.*$/gm)];
+  const headingAfter = templateText.slice(block.end).match(/^##\s+.*$/m);
+  return {
+    after: headingsBefore.length > 0 ? headingsBefore[headingsBefore.length - 1][0].trim() : null,
+    before: headingAfter ? headingAfter[0].trim() : null,
+  };
+}
+
+// Place `block` into `text` at the canonical position, returning the new
+// text. Used by both `init` (via the template, which already has it there)
+// and `templates update` (on a project that has none), so the two produce
+// the same layout and running it twice is a no-op.
+export function placeSurfaceBlock(text, block, anchors) {
+  const existing = findSurfaceBlock(text);
+  if (existing) return text.slice(0, existing.start) + block + text.slice(existing.end);
+
+  const lines = text.split("\n");
+  const headingIndex = (heading) =>
+    heading ? lines.findIndex((l) => l.trim() === heading) : -1;
+
+  // A section ends at the next heading OR at the start of another CLI-owned
+  // block. The marker comment precedes that block's heading, so scanning for
+  // headings alone would place this block BETWEEN a marker and its own
+  // heading — nesting the two, after which the next regeneration treats the
+  // outer span as stale and deletes everything inside it. That corrupted a
+  // real file before this guard existed.
+  const isBoundary = (line) => /^##\s+/.test(line) || /^\s*<!--\s*doctrina:\w+:begin/.test(line);
+
+  // Preferred: immediately after the section the template puts it after.
+  const afterIdx = headingIndex(anchors.after);
+  if (afterIdx >= 0) {
+    let end = afterIdx + 1;
+    while (end < lines.length && !isBoundary(lines[end])) end += 1;
+    const head = lines.slice(0, end).join("\n").replace(/\s+$/, "");
+    const tail = lines.slice(end).join("\n");
+    return `${head}\n\n${block}\n\n${tail}`.replace(/\n{3,}/g, "\n\n");
+  }
+
+  // Next: immediately before the section the template puts it before.
+  const beforeIdx = headingIndex(anchors.before);
+  if (beforeIdx >= 0) {
+    const head = lines.slice(0, beforeIdx).join("\n").replace(/\s+$/, "");
+    const tail = lines.slice(beforeIdx).join("\n");
+    return `${head}\n\n${block}\n\n${tail}`.replace(/\n{3,}/g, "\n\n");
+  }
+
+  // Last resort: append, with a trailing newline so the file stays well-formed.
+  return `${text.replace(/\s+$/, "")}\n\n${block}\n`;
+}
+
+// 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) {
+  return findMarkedBlock(text, "surface");
+}
+
+// Shared locator for the CLI-owned marker blocks (surface, changed).
+// Returns { start, end, inner } as string offsets, or null when either
+// marker is missing.
+function findMarkedBlock(text, name) {
+  // Note the doubled backslashes: these are TEMPLATE literals, so `\s`
+  // would collapse to a bare "s" before the RegExp ever sees it.
+  const begin = text.match(new RegExp(`<!--\\s*doctrina:${name}:begin[\\s\\S]*?-->`));
+  if (!begin) return null;
+  const endRe = new RegExp(`<!--\\s*doctrina:${name}: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
@@ -116,3 +374,56 @@ export function referencedCommands(markdown) {
   }
   return out;
 }
+
+// ---------------------------------------------------------------------------
+// The agent-facing changelog (M2, part 3).
+//
+// Reported from real use: when a new command shipped, the LLM driving
+// Doctrina had no idea the capability existed. It only found out by running
+// `doctrina --help` — which it had no reason to run, because nothing told
+// it anything had changed.
+//
+// CHANGELOG.md is 46 KB of human prose and far too large to carry into a
+// context window. This is three to six lines stating only what alters
+// AGENT behaviour: a new capability, a changed trigger, a removed command.
+// `upgrade --write` refreshes it, so an agent reading AGENTS.md after an
+// upgrade learns what is new without being told to look.
+
+export const AGENT_CHANGELOG_BEGIN =
+  "<!-- doctrina:changed:begin — CLI-owned. Regenerated by `doctrina upgrade --write`. -->";
+export const AGENT_CHANGELOG_END = "<!-- doctrina:changed:end -->";
+
+// What changed for an AGENT, per version. Keyed by the version that
+// introduced it. Only entries that alter what an agent should DO belong
+// here — a bug fix nobody's behaviour depends on does not.
+export const AGENT_CHANGELOG = {
+  "0.14.0": [
+    "`doctrina adapter add|remove|list` — add an agent without re-scaffolding; `init --force` no longer overwrites authored AGENTS.md/product.md.",
+    "`doctrina change apply` now refuses what `analyze` refuses; `change check` previews a close, `change tick` checks boxes in bulk.",
+    "Exit codes are a 5-class contract: 1 gate, 2 usage, 3 precondition, 4 environment. Branch on the code, not the prose.",
+    "A change that alters a documented surface must carry its docs — `close` refuses otherwise (`--force` records the gap).",
+    "Project templates under `.doctrina/templates/` now override the bundled ones, per file.",
+  ],
+};
+
+// The block written into AGENTS.md for a given version. Empty string when
+// that version has no agent-visible changes.
+export function agentChangelogMarkdown(version) {
+  const entries = AGENT_CHANGELOG[version];
+  if (!entries || entries.length === 0) return "";
+  return [
+    `## What changed in ${version}`,
+    "",
+    ...entries.map((e) => `- ${e}`),
+  ].join("\n");
+}
+
+export function agentChangelogBlock(version) {
+  const md = agentChangelogMarkdown(version);
+  if (!md) return "";
+  return `${AGENT_CHANGELOG_BEGIN}\n${md}\n${AGENT_CHANGELOG_END}`;
+}
+
+export function findAgentChangelogBlock(text) {
+  return findMarkedBlock(text, "changed");
+}

package/src/lib/criteria.js

@@ -1,3 +1,4 @@
+// @ts-check
 // Shared parser for the "## Acceptance criteria" section of a spec.
 //
 // A criterion is a numbered item that MAY span several lines (continuation

package/src/lib/dates.js

@@ -1,3 +1,4 @@
+// @ts-check
 // Date helpers. Single source so the CLI emits consistent YYYY-MM-DD strings.
 
 export function today(now = new Date()) {

package/src/lib/diff.js

@@ -1,3 +1,4 @@
+// @ts-check
 // Minimal line diff (LCS-based) for `change diff`. Specs are capped at a
 // few hundred lines, so the O(n*m) table is fine and keeps us at zero deps.