doctrina-cli 0.15.1 → 0.16.0

package/src/lib/agent-changelog.js

@@ -0,0 +1,133 @@
+// @ts-check
+// Drafting the agent-facing changelog from what actually shipped.
+//
+// `AGENT_CHANGELOG` in lib/commands.js is the block `upgrade --write` writes
+// into AGENTS.md: at most five bullets telling an arriving agent what it must
+// now DO differently. It is an object literal somebody edits by hand at every
+// release, in parallel with a 57 KB prose CHANGELOG describing the same
+// changes for people — and the comment above it already admits the approach
+// "worked once and does not scale" (audit finding F22).
+//
+// This module does not write it. It DRAFTS candidates, from the signals the
+// docs gate already extracts per archived change — the commands, flags and
+// exit codes that change said it touched. Authorship stays human, because
+// what an agent must do differently is a judgement about behaviour, and the
+// CLI does not make those (ADR 0005). What it removes is the remembering.
+import path from "node:path";
+import { isDir } from "./fs-ops.js";
+import { readLedger } from "./ledger.js";
+import { documentedSurfaceSignals } from "./docs-impact.js";
+import { AGENT_CHANGELOG_MAX_BULLETS } from "./commands.js";
+import { lastTagDate, windowCutoff } from "./git.js";
+
+/**
+ * Which window a draft covers, and why that window.
+ *
+ * "Since the last tag" is the honest default: the block describes the
+ * release being cut, and the last tag is where the previous one ended. With
+ * no tags (a young project, a shallow clone) it falls back to a day window
+ * and SAYS which it used — a draft that quietly covered the wrong period
+ * would be worse than one that names its edges.
+ *
+ * @param {string} projectRoot
+ * @param {{days?: number|null}} [options]
+ * @returns {{since: string, basis: string}}
+ */
+export function draftWindow(projectRoot, { days = null } = {}) {
+  if (days !== null) return { since: windowCutoff(days), basis: `the last ${days} days` };
+  const tag = lastTagDate(projectRoot);
+  if (tag) return { since: tag, basis: "changes archived since the last tag" };
+  return { since: windowCutoff(30), basis: "the last 30 days (no tag to measure from)" };
+}
+
+/**
+ * Candidate bullets for the agent changelog, newest first.
+ *
+ * One candidate per archived change in the window that touched a documented
+ * surface. A change that touched none produces nothing — the block is for
+ * what an agent must do differently, and a change no agent can observe is
+ * not that.
+ *
+ * @param {string} projectRoot
+ * @param {{days?: number|null, max?: number}} [options]
+ * @returns {{
+ *   since: string, basis: string, max: number,
+ *   candidates: {id: string, date: string, title: string, signals: string[], bullet: string}[],
+ *   silent: {id: string, date: string, title: string}[],
+ *   truncated: number
+ * }}
+ */
+export function draftAgentChangelog(projectRoot, { days = null, max = AGENT_CHANGELOG_MAX_BULLETS } = {}) {
+  const { since, basis } = draftWindow(projectRoot, { days });
+  const archiveDir = path.join(projectRoot, ".doctrina", "changes", "archive");
+
+  const candidates = [];
+  const silent = [];
+  // The ledger is the record of what landed and when (change 0046); the
+  // archived folder is where the change's own artifacts still are.
+  const landed = readLedger(projectRoot).entries
+    .filter((e) => e.kind === "archived" && e.date >= since)
+    .sort((a, b) => b.date.localeCompare(a.date) || b.id.localeCompare(a.id));
+
+  for (const entry of landed) {
+    const dir = path.join(archiveDir, `${entry.date}-${entry.id}`);
+    const signals = isDir(dir) ? documentedSurfaceSignals(dir, projectRoot) : [];
+    if (signals.length === 0) {
+      silent.push({ id: entry.id, date: entry.date, title: entry.title });
+      continue;
+    }
+    candidates.push({
+      id: entry.id,
+      date: entry.date,
+      title: entry.title,
+      signals,
+      bullet: `${entry.title} (${signals.join("; ")}).`,
+    });
+  }
+
+  const truncated = Math.max(0, candidates.length - max);
+  return { since, basis, max, candidates: candidates.slice(0, max), silent, truncated };
+}
+
+/**
+ * The draft, rendered as the block a human edits into lib/commands.js.
+ *
+ * Deliberately shaped as the literal it will become, so the step is "cut and
+ * reword", not "translate". The bullets are drafts of the SHAPE — a title and
+ * the surface it touched — and every one of them is expected to be rewritten
+ * into what an agent must now do.
+ *
+ * @param {ReturnType<typeof draftAgentChangelog>} draft
+ * @param {string} version
+ * @returns {string[]} lines
+ */
+export function renderDraft(draft, version) {
+  const out = [];
+  out.push(`# Agent changelog draft for ${version} — ${draft.basis} (since ${draft.since})`);
+  out.push("");
+  if (draft.candidates.length === 0) {
+    out.push("No archived change in this window touched a documented surface.");
+    out.push("Nothing to tell an arriving agent — which is a valid answer, not an empty one.");
+    return out;
+  }
+  out.push("Proposed, newest first. REWRITE each into what an agent must now DO;");
+  out.push("this draft only knows what surface the change touched.");
+  out.push("");
+  out.push(`  "${version}": [`);
+  for (const cand of draft.candidates) {
+    out.push(`    // ${cand.date} ${cand.id}`);
+    out.push(`    ${JSON.stringify(cand.bullet)},`);
+  }
+  out.push("  ],");
+  if (draft.truncated > 0) {
+    out.push("");
+    out.push(`${draft.truncated} further candidate${draft.truncated === 1 ? "" : "s"} did not fit the ${draft.max}-bullet cap.`);
+    out.push("The cap is AGENTS.md's line budget, not a preference: choose, do not raise it.");
+  }
+  if (draft.silent.length > 0) {
+    out.push("");
+    out.push(`${draft.silent.length} change${draft.silent.length === 1 ? "" : "s"} touched no documented surface and are not proposed:`);
+    for (const s of draft.silent) out.push(`  ${s.date} ${s.id}`);
+  }
+  return out;
+}

package/src/lib/analysis.js

@@ -0,0 +1,264 @@
+// @ts-check
+import path from "node:path";
+import { exists, isDir, isFile, read, relPath, walk } from "./fs-ops.js";
+import { c } from "./colors.js";
+import { checklistProgress, isUntouchedScaffold } from "./doc-model.js";
+import { collectBudgets } from "./runtime.js";
+import { extractOps, applyOps } from "./spec-ops.js";
+
+// The structural ANALYSIS of a change folder, as data.
+//
+// `lib/gates.js` enforces these findings on every lifecycle transition, so
+// the library depended on a command module to compute them — a lib->command
+// edge that made the dependency graph a cycle waiting to happen (audit
+// finding F7). The findings are what the gate map is built on; they belong
+// here, and `commands/analyze.js` is the renderer that prints them.
+
+// The structural findings for a change, as data. Exported so the shared
+// gate map (`lib/gates.js`) can enforce the SAME checks on every
+// transition that needs them, instead of each command deciding for itself
+// — `change apply` used to mutate a change that `analyze` had just
+// refused (audit item C6).
+export function collectAnalysis(projectRoot, changeDir) {
+  const results = [];
+
+  // proposal.md
+  const proposalPath = path.join(changeDir, "proposal.md");
+  if (!isFile(proposalPath)) {
+    results.push(fail("proposal.md missing"));
+  } else {
+    results.push(pass("proposal.md present"));
+    const text = read(proposalPath);
+    if (/^##\s+Why\b/m.test(text)) results.push(pass(`proposal.md has a "## Why" section`));
+    else results.push(fail(`proposal.md missing "## Why" section`));
+
+    // A section that still holds only its scaffold comment was never
+    // written. The check above only proved the HEADING survived, which is
+    // why six changes closed in one session with every rationale section
+    // empty: the planning step wrote to the file with a pattern that did
+    // not match its line endings, and nothing downstream looked inside.
+    // For a framework whose whole premise is recoverable provenance, an
+    // archived change that cannot say why it happened is the defect.
+    // Only `Why` and `What` are required. They are what makes a change
+    // recoverable a year later — the reason it exists and the shape it
+    // took. `Scope boundaries` and `Open questions` are legitimately empty
+    // on a change that has neither, and demanding the word "None." there
+    // is friction that buys nothing.
+    const hollow = [];
+    for (const m of text.matchAll(/^##\s+(.+?)[ \t]*\r?$/gm)) {
+      const heading = m[1].trim();
+      if (!/^(Why|What)$/i.test(heading)) continue;
+      const start = m.index + m[0].length;
+      const next = text.slice(start).search(/^##\s+/m);
+      const body = (next < 0 ? text.slice(start) : text.slice(start, start + next));
+      // Strip comments; anything left that is not whitespace is real prose.
+      if (body.replace(/<!--[\s\S]*?-->/g, "").trim() === "") hollow.push(heading);
+    }
+    if (hollow.length > 0) {
+      results.push(fail(
+        `proposal.md has ${hollow.length} unwritten section${hollow.length === 1 ? "" : "s"} ` +
+        `(${hollow.join(", ")}) — a heading that survived is not a section that was written`,
+      ));
+    } else {
+      results.push(pass("proposal.md states why and what"));
+    }
+  }
+
+  // tasks.md
+  const tasksPath = path.join(changeDir, "tasks.md");
+  if (!isFile(tasksPath)) {
+    results.push(fail("tasks.md missing"));
+  } 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 = checklistProgress(text).placeholders;
+    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?)"));
+  }
+
+  // design.md (optional)
+  const designPath = path.join(changeDir, "design.md");
+  if (isFile(designPath)) results.push(info("design.md present"));
+  else results.push(info("design.md absent (optional)"));
+
+  // Spec deltas
+  const deltaFiles = walk(path.join(changeDir, "specs")).filter((p) => p.endsWith("delta.md"));
+  if (deltaFiles.length === 0) {
+    results.push(info("0 spec deltas (metadata-only change)"));
+  } else {
+    results.push(pass(`${deltaFiles.length} spec delta${deltaFiles.length === 1 ? "" : "s"}:`));
+    for (const deltaPath of deltaFiles) {
+      const rel = relPath(projectRoot, deltaPath);
+      const text = read(deltaPath);
+      const opMatch = text.match(/^\*\*Operation:\*\*\s*([A-Z]+)/m);
+      const op = opMatch ? opMatch[1] : null;
+      const capMatch = text.match(/^#\s+Spec Delta\s*[—-]\s*capability:\s*([a-z][a-z0-9-]*)/m);
+      const cap = capMatch ? capMatch[1] : path.basename(path.dirname(deltaPath));
+
+      if (!op) {
+        results.push(fail(`  ${rel}: Operation header missing or malformed`));
+        continue;
+      }
+      if (!["ADDED", "MODIFIED", "REMOVED"].includes(op)) {
+        results.push(fail(`  ${rel}: Operation "${op}" is not one of ADDED|MODIFIED|REMOVED`));
+        continue;
+      }
+      const targetSpec = path.join(projectRoot, ".doctrina", "specs", cap, "spec.md");
+      const targetRel = relPath(projectRoot, targetSpec);
+      if (op === "ADDED") {
+        // Mirrors `change apply`: an existing target that is still the
+        // untouched `spec new` scaffold is the canonical flow (spec new →
+        // ADDED delta), so it passes as a replacement; only real content fails.
+        if (exists(targetSpec) && !isUntouchedScaffold(read(targetSpec), cap)) {
+          results.push(fail(`  ${cap} (ADDED) but target ${targetRel} has real content — use MODIFIED or remove it first`, "pre-apply"));
+        } else if (exists(targetSpec)) {
+          results.push(pass(`  ${cap} (ADDED) → ${targetRel} (replaces the untouched scaffold)`));
+        } else {
+          results.push(pass(`  ${cap} (ADDED) → ${targetRel} (new)`));
+        }
+      } else if (op === "MODIFIED") {
+        if (!exists(targetSpec)) {
+          results.push(fail(`  ${cap} (MODIFIED) but target ${targetRel} does not exist`, "pre-apply"));
+        } else {
+          results.push(pass(`  ${cap} (MODIFIED) → ${targetRel}`));
+          // THE OPS, EXECUTED (third audit, finding 2). Until now this said
+          // "ready to apply" for a delta whose ops block `apply` then refused:
+          // the pre-flight inspected everything about the delta except the one
+          // part that does the work. `change check` already ran this dry-run,
+          // so the answer existed — the gate `close` and `apply` consult was
+          // simply not the one asking.
+          //
+          // Scoped pre-apply: after a successful apply the target holds what
+          // these ops just wrote, and re-running them against it is a question
+          // with no meaning. `archive`'s integrity gate excludes this scope for
+          // exactly that reason.
+          for (const line of opsFindings(read(targetSpec), text, rel)) results.push(line);
+        }
+      } else {
+        if (!exists(targetSpec)) {
+          results.push(fail(`  ${cap} (REMOVED) but target ${targetRel} does not exist`, "pre-apply"));
+        } else {
+          results.push(pass(`  ${cap} (REMOVED) → ${targetRel}`));
+        }
+      }
+    }
+  }
+
+  // BUDGET DISCIPLINE (change 0029). A declared ceiling is a contract, not
+  // a preference — and the tempting fix for "the output blew the limit" is
+  // to raise the limit. That buys headroom by truncating what mattered
+  // instead of sending less, and it is the discussion that comes back every
+  // quarter because nothing ever recorded that it had been settled. Raising
+  // an INPUT ceiling is a normal trade-off; raising an OUTPUT ceiling to
+  // resolve an overflow is the move this refuses.
+  for (const r of checkBudgetRaises(projectRoot, changeDir)) results.push(r);
+
+  return results;
+}
+
+// Compare the ceilings a change's proposal/deltas propose against the ones
+// the contracts declare today. Text-scanned: a change states a new value in
+// prose long before any code moves, which is exactly when it should be
+// argued about.
+function checkBudgetRaises(projectRoot, changeDir) {
+  const results = [];
+  let declared;
+  try {
+    declared = collectBudgets(projectRoot);
+  } catch {
+    return results;
+  }
+  if (declared.size === 0) return results;
+
+  const texts = [];
+  for (const f of walk(changeDir)) {
+    if (f.endsWith(".md")) texts.push({ rel: relPath(projectRoot, f), text: read(f) });
+  }
+
+  for (const [name, budget] of declared) {
+    if (budget.direction !== "output") continue;
+    for (const { rel, text } of texts) {
+      // "<limit> ... <number>" on one line: the shape a proposal uses when
+      // it restates a ceiling ("raise ai-summary to 2000").
+      const re = new RegExp(`${escapeRe(name)}[^\\n]{0,60}?(\\d{2,})`, "gi");
+      for (const m of text.matchAll(re)) {
+        const proposed = Number.parseInt(m[1], 10);
+        if (!Number.isFinite(proposed) || proposed <= budget.value) continue;
+        results.push(fail(
+          `${rel} raises the OUTPUT ceiling "${name}" from ${budget.value} to ${proposed} ` +
+          `(declared in ${budget.contract}) — raising an output budget buys headroom by ` +
+          `truncating what mattered. Send less, or supersede the budget deliberately in the contract`,
+        ));
+        break;
+      }
+    }
+  }
+  return results;
+}
+
+// A limit name comes from a contract table cell, so it is user text and
+// must not be spliced into a pattern unescaped.
+function escapeRe(s) {
+  return String(s).replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+/**
+ * Run a MODIFIED delta's ops block against its target spec IN MEMORY and
+ * report what `apply` would report.
+ *
+ * The whole finding behind this: `apply` executes these ops all-or-none and
+ * refuses on the first error, so an unappliable block is knowable before
+ * anything is touched — and the pre-flight was not looking. A delta with no
+ * ops block is not a failure: `apply` prints a manual-merge pointer for it,
+ * and saying so here is what lets a close be planned around it rather than
+ * surprised by it.
+ *
+ * @returns {Array<{kind: string, line: string, scope?: string}>}
+ */
+function opsFindings(specText, deltaText, rel) {
+  const ops = extractOps(deltaText);
+  if (ops.length === 0) {
+    return [info(`  ${rel}: no ops block — apply will print a manual-merge pointer`)];
+  }
+  const result = applyOps(specText, ops);
+  if (result.errors.length === 0) {
+    const n = result.applied.length;
+    return [pass(`  ${rel}: ${n} op${n === 1 ? "" : "s"} would apply cleanly`)];
+  }
+  return [
+    fail(`  ${rel}: ${result.errors.length} op error${result.errors.length === 1 ? "" : "s"} ` +
+      `(apply would refuse): ${result.errors.join("; ")}`, "pre-apply"),
+  ];
+}
+
+function pass(msg) {
+  return { kind: "pass", line: c.green("✓ ") + msg };
+}
+// `scope` says WHEN a failure is a real answer.
+//
+// Most of these questions are true at every point in a change's life: a
+// proposal with an unwritten `## What` is hollow before an apply and just as
+// hollow after one. A few are only meaningful BEFORE the apply — "an ADDED
+// delta's target must not already hold real content" is proof of a problem
+// beforehand and proof the apply WORKED afterwards.
+//
+// The gate map used to exclude the whole structure gate from `archive` to
+// dodge that handful, which also dropped the hollow-proposal check — the
+// exact defect this repository's own history records as having "shipped six
+// hollow proposals past every gate". Tagging the pre-apply ones lets
+// `archive` keep the rest.
+function fail(msg, scope = "always") {
+  return { kind: "fail", scope, line: c.red("✗ ") + msg };
+}
+function info(msg) {
+  return { kind: "info", line: c.gray("- ") + msg };
+}

package/src/lib/change-ops.js

@@ -0,0 +1,131 @@
+// @ts-check
+// Scaffolding a change folder.
+//
+// `work` opens a change as its first act and called into `commands/change.js`
+// to do it (audit finding F7). Creating the folder is an OPERATION over the
+// tree, not a rendering of the `change` command, so both entry points perform
+// it from here.
+import path from "node:path";
+import process from "node:process";
+import { exists, isDir, isFile, lineCount, mkdirp, move, read, relPath, remove, walk, write } from "./fs-ops.js";
+import { locateTemplatesDir, loadTemplateTree, materialiseEntry } from "./templates.js";
+import * as idx from "./index-json.js";
+import { today } from "./dates.js";
+import { flagBool, flagString } from "./args.js";
+import { c } from "./colors.js";
+import { ensureDoctrinaProject, isChangeId, resolveWithinProject } from "./project.js";
+import { changeEntry } from "./scan.js";
+export function changeNew(args, flags) {
+  const id = args[0];
+  const title = args.slice(1).join(" ").trim();
+  if (!id) {
+    console.error(c.red("error:") + " change new requires <id> and \"<title>\"");
+    return 2;
+  }
+  if (!title) {
+    console.error(c.red("error:") + " change new requires a title (quote it if it contains spaces)");
+    return 2;
+  }
+  // The id names a DIRECTORY, so it obeys the same grammar every other
+  // authoring command enforces on its argument (third audit, finding 1).
+  // Without this `change new ../../../elsewhere/evil` scaffolded outside the
+  // project, and `0003-com espaco` was accepted here and then carried by
+  // `validate`, `index rebuild` and `next` as a legitimate id.
+  if (!isChangeId(id)) {
+    console.error(c.red("error:") + ` invalid change id "${id}" (lowercase letters, digits, hyphens)`);
+    console.error(c.gray("hint: ") + "ids look like `0042-short-slug`; `doctrina work \"<prompt>\"` derives one for you");
+    return 2;
+  }
+
+  const force = flagBool(flags, "force", false);
+  // A chore is a spec-less change (infra / docs / build / migration) — review
+  // G9. It runs the full proposal → apply → archive → ledger lifecycle (so the
+  // history shows it) without forcing a fake spec delta. The empty specs/ dir
+  // is kept so `change apply`'s zero-delta path flips it to applied unchanged.
+  const chore = flagBool(flags, "chore", false) || flagBool(flags, "no-spec", false);
+  const projectRoot = process.cwd();
+  ensureDoctrinaProject(projectRoot);
+
+  // Belt and braces: the grammar above already refuses a traversing id, and
+  // this holds if a future caller reaches this line another way.
+  const changeDir = resolveWithinProject(projectRoot, ".doctrina", "changes", id);
+  if (exists(changeDir) && !force) {
+    console.error(c.red("error:") + ` change "${id}" already exists at ${relPath(projectRoot, changeDir)}`);
+    return 1;
+  }
+
+  const templatesDir = locateTemplatesDir();
+  const date = today();
+  const tokens = { CHANGE_ID: id, CHANGE_TITLE: title, DATE: date, CAPABILITY: "" };
+
+  // design.md is opt-in (--design): in practice it scaffolded on every change
+  // and stayed empty — nine changes out of nine in the 0.11.0 field review. A
+  // change that needs a design doc asks for one; the rest stop carrying a
+  // blank file through apply/archive/ledger.
+  const wantDesign = flagBool(flags, "design", false);
+  const tree = loadTemplateTree(templatesDir, "change");
+  for (const entry of tree) {
+    if (entry.relativePath === "spec-delta.md.template") continue;
+    if (entry.relativePath === "design.md.template" && !wantDesign) continue;
+    const written = materialiseEntry(entry, changeDir, tokens, { force });
+    console.log(c.green("created") + ` ${relPath(projectRoot, written)}`);
+  }
+  // No empty `specs/` here (change 0081). The directory used to be created
+  // unconditionally as somewhere "ready" for deltas, and when the CLI could
+  // not name a capability — a new prompt, a project whose specs do not match
+  // — nothing was ever written into it. An empty directory is not an absence:
+  // it says deltas live here, or lived here, and the next reader spends
+  // attention checking. The delta writer creates its own path when there is
+  // a delta to put in it.
+
+  // Stamp the proposal so a chore is honest in the artifact, not just the CLI.
+  if (chore) {
+    const proposalPath = path.join(changeDir, "proposal.md");
+    if (exists(proposalPath)) {
+      const txt = read(proposalPath);
+      const updated = txt.replace(/^(-\s+\*\*Affects specs:\*\*).*$/m, "$1 (none — chore)");
+      if (updated !== txt) write(proposalPath, updated, { force: true });
+    }
+  }
+
+  // Derive the entry from the proposal on disk rather than assembling one
+  // here: a field the deriver knows about and this writer does not is index
+  // drift the moment the change is opened (change 0076 — that is exactly what
+  // `lane` did). One constructor, in `scan.js`, for one record shape.
+  reindexChange(projectRoot, id, date);
+
+  console.log("");
+  if (chore) {
+    console.log(c.bold("Chore opened.") + " No spec deltas expected — implement, check the tasks, then " +
+      c.cyan(`doctrina change apply ${id}`) + " and " + c.cyan(`doctrina change archive ${id}`) + ".");
+  } else {
+    console.log(c.bold("Change opened.") + " Add spec deltas under " +
+      c.cyan(`.doctrina/changes/${id}/specs/<capability>/delta.md`));
+  }
+  return 0;
+}
+
+/**
+ * Register — or re-derive — one open change's index entry from its proposal.
+ *
+ * `work` writes the proposal in two passes: `changeNew` scaffolds it, then the
+ * command stamps the lane it classified and the specs it pinned. Indexing at
+ * the end of the FIRST pass reads a proposal that is not finished yet, which
+ * is why every `doctrina work` used to be followed by a `validate` error and
+ * an `index rebuild` nobody asked for. Calling this again after the stamping
+ * costs one file write and makes the tree honest on the next command.
+ *
+ * @param {string} projectRoot
+ * @param {string} id    The change id (its directory name).
+ * @param {string} [date] Fallback for a proposal carrying no Date header.
+ */
+export function reindexChange(projectRoot, id, date = today()) {
+  const proposalPath = path.join(projectRoot, ".doctrina", "changes", id, "proposal.md");
+  const proposal = isFile(proposalPath) ? read(proposalPath) : "";
+  const index = idx.load(projectRoot);
+  const prev = index.artifacts.changes.find((ch) => ch.id === id) ?? null;
+  index.artifacts.changes = index.artifacts.changes.filter((ch) => ch.id !== id);
+  index.artifacts.changes.push(changeEntry(proposal, id, prev, date));
+  idx.touch(index, date);
+  idx.save(projectRoot, index);
+}

package/src/lib/commands.js

@@ -20,7 +20,7 @@ export const COMMAND_NAMES = [
   // gates
   "analyze", "clarify", "validate", "coverage", "trace", "review", "verify", "close", "doctor",
   // maintenance
-  "templates", "hooks", "index", "watch", "metrics", "report", "completion", "upgrade",
+  "templates", "hooks", "index", "watch", "metrics", "report", "completion", "upgrade", "ci",
 ];
 
 // The full operation surface — every `doctrina <command> [<subcommand>]` a
@@ -93,6 +93,7 @@ export const OPERATIONS = [
   ["metrics", "Local git-derived adoption metrics (no network)"],
   ["report", "Markdown digest for a period: changes, gates, git summary"],
   ["completion", "Print bash/zsh/pwsh completions (generated from the catalog)"],
+  ["ci", "Emit the CI pipeline for the declared gate sequence (--emit github)"],
   ["upgrade", "Bring an existing project up to the installed CLI (--write applies)"],
 ];
 
@@ -118,7 +119,7 @@ export const COMMAND_META = {
   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" },
+  prime:        { moment: "Orient",     when: "at the START of every session", purpose: "gates, open work and next steps in one read (--rules for the full standing rules)" },
   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" },
@@ -131,7 +132,7 @@ export const COMMAND_META = {
   triage:       { moment: "Change",     when: "a request arrives — BEFORE scaffolding, especially if it smells like an incident", purpose: "classify the lane (product/runtime/chore) and check the declared runtime surface" },
   work:         { moment: "Change",     when: "a request arrives that changes behaviour (triage says PRODUCT)", 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" },
+  change:       { moment: "Change",     when: "driving a change through its lifecycle by hand", purpose: "new / apply / archive / check (--verbose) / tick / 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" },
@@ -155,6 +156,7 @@ export const COMMAND_META = {
   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" },
+  ci:           { moment: "Maintain",   when: "the declared gate sequence changed and CI must follow", purpose: "emit the CI pipeline from the gate declaration" },
 };
 
 // The order moments appear in the generated block.
@@ -195,10 +197,48 @@ const SURFACE_HINTS = {
   clarify: "--all (--lang pt|en)",
   close: "<id...>",
   upgrade: "--write",
+  ci: "--emit github",
   prime: "(session start)",
   handoff: "(before compaction/handover)",
 };
 
+// ---------------------------------------------------------------------------
+// Deprecations (change 0049).
+//
+// The surface has a hard 40-line budget precisely so that adding a command
+// forces the question "what comes off?" — and for two releases the answer was
+// "nothing", while the budget was met by compressing a whole moment onto one
+// line (audit finding F23). These are the first two removals, and both are
+// MERGES: the surviving command already does everything the retired one did,
+// which is why they can go without waiting for usage evidence. Usage counts
+// can tell you a command is unloved; only redundancy can tell you it is
+// unnecessary, and an unloved command that does something nothing else does
+// has to stay.
+//
+// A deprecated operation keeps working, warns once on the way through, and
+// leaves the surface block — an agent should not reach for it, and the block
+// is the list of things to reach for. Removal is a later, separate change.
+export const DEPRECATED = Object.freeze({
+  "constitution": {
+    since: "0.16.0",
+    use: "doctrina prime --rules",
+    why: "prime renders the same standing-rules view, from the same collection",
+  },
+  "change diff": {
+    since: "0.16.0",
+    use: "doctrina change check --verbose",
+    why: "check runs every ops block against the target spec and now prints the same per-delta preview",
+  },
+});
+
+/** The deprecation record for an invocation, or null. */
+export function deprecationFor(argv) {
+  const words = argv.filter((a) => !a.startsWith("-"));
+  const two = words.slice(0, 2).join(" ");
+  const one = words[0] ?? "";
+  return DEPRECATED[two] ?? DEPRECATED[one] ?? null;
+}
+
 // 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.
@@ -219,8 +259,13 @@ const COMPACT_MOMENTS = new Set(["Maintain"]);
 // a name index never told it. Same shape `context` prints for skills —
 // description plus `when:`, body on demand.
 export function surfaceMarkdown() {
+  // A deprecated operation stays in the catalog — `--help` and the shell
+  // completions must still know the name someone types — but leaves this
+  // block: it is the list of commands to REACH FOR, and pointing an agent at
+  // a name that warns when used is worse than not listing it.
   const subsByCmd = new Map();
   for (const [op] of OPERATIONS) {
+    if (DEPRECATED[op]) continue;
     const [cmd, sub] = op.split(" ");
     if (!subsByCmd.has(cmd)) subsByCmd.set(cmd, []);
     if (sub) subsByCmd.get(cmd).push(sub);
@@ -242,7 +287,7 @@ export function surfaceMarkdown() {
     "canonical templates and syncs `index.json`. Flags: `doctrina <cmd> --help`.",
   ];
   for (const moment of MOMENTS) {
-    const cmds = COMMAND_NAMES.filter((n) => COMMAND_META[n]?.moment === moment);
+    const cmds = COMMAND_NAMES.filter((n) => COMMAND_META[n]?.moment === moment && !DEPRECATED[n]);
     if (cmds.length === 0) continue;
     if (COMPACT_MOMENTS.has(moment)) {
       // Each name still carries the `doctrina ` prefix: the compact line is
@@ -405,6 +450,13 @@ export const AGENT_CHANGELOG = {
   // Each entry lists only ITS OWN delta. The series carries the rest
   // forward (see agentChangelogEntries), so a patch never has to restate
   // the minor that introduced the commands, and never silently erases it.
+  "0.16.0": [
+    "A reference or path that does not resolve now answers exit 2 (USAGE) everywhere — `clarify`, `show`, `why`, `analyze`, `context`, `change check`, `spec set`, `decision accept|scope`. Correct the invocation; retrying it unchanged never succeeds.",
+    "The `--json` envelope names the OPERATION in `command` and carries arguments in `args` — branch on those two, not on a joined string. An undeclared flag now answers with `{ok: false, exit_code: 2}` instead of an empty stdout.",
+    "`analyze` executes a MODIFIED delta's `ops` block, so `analyze`, `change apply` and `close` all refuse the same unappliable block. Fix the ops before closing; a delta with no ops block is still a legitimate manual merge.",
+    "`validate` refuses more: an active spec declaring no acceptance criteria, an empty artifact, a scaffold section left unwritten, a reference that resolves to nothing. Write the criteria before flipping a spec to `active`.",
+    "`change new <id>` requires the `NNNN-slug` shape (lowercase letters, digits, hyphens) and writes nothing otherwise — `doctrina work \"<prompt>\"` derives one for you.",
+  ],
   "0.15.1": [
     "Exporting a variable under a name that is not its source's is routine — declare it in the Wiring row's Origin cell as `<origin>:<source>` (e.g. `secrets:NPM_TOKEN`) and RT02 stays silent until either side moves.",
   ],