doctrina-cli 0.13.0 → 0.14.0

package/README.md

@@ -3,7 +3,7 @@
 > CLI for the Doctrina framework. The package is published as
 > `doctrina-cli`; the executable it installs is `doctrina`.
 
-**Status:** v0.11.0 — current release. Zero runtime dependencies
+**Status:** v0.14.0 — current release. Zero runtime dependencies
 (Node.js standard library only).
 
 ## Install

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "doctrina-cli",
-  "version": "0.13.0",
+  "version": "0.14.0",
   "description": "Doctrina CLI — spec-driven, AGENTS.md-native framework for multi-agent AI development.",
   "license": "MIT",
   "keywords": [
@@ -19,7 +19,8 @@
   },
   "scripts": {
     "test": "node --test",
-    "prepack": "node scripts/copy-templates.js"
+    "prepack": "node scripts/copy-templates.js",
+    "test:e2e": "node ../../scripts/e2e-packed.mjs"
   },
   "files": [
     "src",

package/src/commands/adapter.js

@@ -0,0 +1,205 @@
+// @ts-check
+import path from "node:path";
+import process from "node:process";
+import { exists, isFile, mkdirp, read, relPath, remove, write } from "../lib/fs-ops.js";
+import {
+  ADAPTER_STATES, adapterFiles, describeAdapter, listAdapterNames, renderAdapterFile,
+} from "../lib/adapters.js";
+import { flagBool } from "../lib/args.js";
+import { today } from "../lib/dates.js";
+import { c } from "../lib/colors.js";
+import { suggest } from "../lib/suggest.js";
+import { notADoctrinaProject } from "../lib/exit-codes.js";
+
+// `doctrina adapter` — add, remove, and inventory agent adapters (audit
+// item C1).
+//
+// Before this command the only way to add an adapter to an existing project
+// was `doctrina init --agent <name> --force`, because `init` refuses to run
+// twice. That path regenerated AGENTS.md and .doctrina/product.md from
+// blank templates, silently destroying every hand-authored rule and the
+// product definition. `adapter add` is strictly additive: it writes that
+// adapter's own files and never reads or writes AGENTS.md, product.md, or
+// any other project artifact.
+
+const SUBCOMMANDS = ["list", "add", "remove"];
+
+export const flags = { boolean: ["json", "force"], string: [] };
+
+export async function run(positional, cmdFlags) {
+  const sub = positional[0];
+  if (!SUBCOMMANDS.includes(sub)) {
+    console.error(c.red("error:") + ` unknown adapter subcommand "${sub ?? ""}"`);
+    const guess = suggest(sub, SUBCOMMANDS);
+    console.error(c.gray("hint: ") + (guess
+      ? `did you mean \`doctrina adapter ${guess}\`?`
+      : `available: ${SUBCOMMANDS.join(", ")}`));
+    return 2;
+  }
+  const projectRoot = process.cwd();
+  ensureDoctrinaProject(projectRoot);
+  if (sub === "list") return adapterList(projectRoot);
+  if (sub === "add") return adapterAdd(projectRoot, positional[1], cmdFlags);
+  return adapterRemove(projectRoot, positional[1], cmdFlags);
+}
+
+function adapterList(projectRoot) {
+  const names = listAdapterNames(projectRoot);
+  if (names.length === 0) {
+    console.log(c.gray("no adapters available (no templates/adapters directory found)"));
+    return 0;
+  }
+  const rows = names.map((n) => describeAdapter(projectRoot, n));
+  const label = {
+    [ADAPTER_STATES.INSTALLED]: c.green("installed"),
+    [ADAPTER_STATES.AVAILABLE]: c.gray("available"),
+    [ADAPTER_STATES.NATIVE]: c.cyan("native   "),
+  };
+
+  console.log(c.bold("Agent adapters:"));
+  console.log("");
+  for (const r of rows) {
+    const suffix = r.state === ADAPTER_STATES.NATIVE
+      ? c.gray("reads AGENTS.md directly — no file needed")
+      : c.gray(`${r.installed.length}/${r.files.length} file${r.files.length === 1 ? "" : "s"}` +
+        (r.source === "project" ? " · project template" : ""));
+    console.log(`  ${label[r.state]}  ${c.cyan(r.name.padEnd(10))}  ${suffix}`);
+  }
+  console.log("");
+  const installed = rows.filter((r) => r.state === ADAPTER_STATES.INSTALLED).length;
+  const native = rows.filter((r) => r.state === ADAPTER_STATES.NATIVE).length;
+  console.log(c.gray(
+    `${installed} installed · ${rows.length - installed - native} available · ${native} native. ` +
+    "Add one: ") + c.cyan("doctrina adapter add <name>"));
+  return 0;
+}
+
+function adapterAdd(projectRoot, name, cmdFlags) {
+  if (!name) {
+    console.error(c.red("error:") + " adapter add requires a name (see `doctrina adapter list`)");
+    return 2;
+  }
+  const spec = adapterFiles(projectRoot, name);
+  if (!spec) {
+    console.error(c.red("error:") + ` unknown adapter "${name}"`);
+    const guess = suggest(name, listAdapterNames(projectRoot));
+    console.error(c.gray("hint: ") + (guess
+      ? `did you mean \`doctrina adapter add ${guess}\`?`
+      : "run `doctrina adapter list` for the available adapters"));
+    return 2;
+  }
+  if (spec.files.length === 0) {
+    console.log(c.cyan("native  ") + ` ${name} reads AGENTS.md directly — nothing to install`);
+    console.log(c.gray("Its rules already reach the agent through the hub at AGENTS.md."));
+    return 0;
+  }
+
+  const force = flagBool(cmdFlags, "force", false);
+  const tokens = {
+    PROJECT_NAME: path.basename(projectRoot),
+    PROJECT_DESCRIPTION: "",
+    DATE: today(),
+  };
+
+  // Additive by construction: only this adapter's own files are touched,
+  // and an existing one is left alone unless --force is given. AGENTS.md
+  // and product.md are never read or written here.
+  let written = 0;
+  let skipped = 0;
+  for (const file of spec.files) {
+    const dest = path.join(projectRoot, file.relativePath);
+    if (exists(dest) && !force) {
+      console.log(c.yellow("skip   ") + ` ${file.relativePath} (already present; --force overwrites)`);
+      skipped += 1;
+      continue;
+    }
+    mkdirp(path.dirname(dest));
+    write(dest, renderAdapterFile(file, tokens), { force: true });
+    console.log(c.green("created") + ` ${relPath(projectRoot, dest)}`);
+    written += 1;
+  }
+
+  console.log("");
+  console.log(`${c.bold("Adapter " + name)} — ${written} file${written === 1 ? "" : "s"} written` +
+    (skipped > 0 ? `, ${skipped} left alone` : "") +
+    (spec.source === "project" ? c.gray(" (from .doctrina/templates/adapters/)") : ""));
+  console.log(c.gray("Additive only: AGENTS.md and .doctrina/product.md were not touched."));
+  return 0;
+}
+
+function adapterRemove(projectRoot, name, cmdFlags) {
+  if (!name) {
+    console.error(c.red("error:") + " adapter remove requires a name (see `doctrina adapter list`)");
+    return 2;
+  }
+  const spec = adapterFiles(projectRoot, name);
+  if (!spec) {
+    console.error(c.red("error:") + ` unknown adapter "${name}"`);
+    return 2;
+  }
+  if (spec.files.length === 0) {
+    console.log(c.cyan("native  ") + ` ${name} installs no files — nothing to remove`);
+    return 0;
+  }
+
+  // Only delete files this adapter created AND that still match what it
+  // would write. A file the user edited is theirs now; --force overrides.
+  const force = flagBool(cmdFlags, "force", false);
+  const tokens = { PROJECT_NAME: path.basename(projectRoot), PROJECT_DESCRIPTION: "", DATE: today() };
+  let removed = 0;
+  let kept = 0;
+  for (const file of spec.files) {
+    const dest = path.join(projectRoot, file.relativePath);
+    if (!isFile(dest)) continue;
+    const pristine = normalise(read(dest)) === normalise(renderAdapterFile(file, tokens));
+    if (!pristine && !force) {
+      console.log(c.yellow("kept   ") + ` ${file.relativePath} (edited since install; --force removes it)`);
+      kept += 1;
+      continue;
+    }
+    remove(dest);
+    console.log(c.green("removed") + ` ${file.relativePath}`);
+    removed += 1;
+  }
+  console.log("");
+  console.log(`${c.bold("Adapter " + name)} — ${removed} file${removed === 1 ? "" : "s"} removed` +
+    (kept > 0 ? `, ${kept} kept (edited)` : ""));
+  return 0;
+}
+
+function normalise(text) {
+  return text.replace(/\r\n/g, "\n").trim();
+}
+
+function ensureDoctrinaProject(projectRoot) {
+  if (!exists(path.join(projectRoot, ".doctrina"))) {
+    throw notADoctrinaProject();
+  }
+}
+
+export const help = `
+Usage: doctrina adapter <list|add|remove> [name] [--force]
+
+Add, remove, and inventory the per-agent adapter files that point at
+AGENTS.md. Adding an adapter is strictly additive: only that adapter's own
+files are written, and AGENTS.md / .doctrina/product.md are never touched.
+
+Subcommands:
+  list             Every adapter with its state:
+                     installed — its files are present
+                     available — it ships files and none are installed
+                     native    — the agent reads AGENTS.md directly and
+                                 needs no file at all
+  add <name>       Install one adapter's files. An existing file is left
+                   alone unless --force is given.
+  remove <name>    Delete the files this adapter created. A file edited
+                   since install is kept unless --force is given.
+
+Custom adapters: a directory at .doctrina/templates/adapters/<name>/ is
+installable by name and takes precedence over a bundled adapter of the
+same name.
+
+Options:
+  --force          With add, overwrite an existing file; with remove,
+                   delete a file that was edited after install.
+`;

package/src/commands/analyze.js

@@ -1,9 +1,15 @@
+// @ts-check
 import path from "node:path";
 import process from "node:process";
 import { exists, isDir, isFile, read, relPath, walk } from "../lib/fs-ops.js";
 import { c } from "../lib/colors.js";
 import { isUntouchedScaffold } from "./change.js";
 
+// Flags this command accepts. Declared HERE, with the command, so
+// adding a command never requires editing the entrypoint — the gap that
+// let six flags ship undeclared and silently swallow a positional (C3).
+export const flags = { boolean: ["json"], string: [] };
+
 export async function run(positional, _flags) {
   const id = positional[0];
   if (!id) {
@@ -21,6 +27,25 @@ export async function run(positional, _flags) {
   console.log(`analyzing ${relPath(projectRoot, changeDir)}/`);
   console.log("");
 
+  const results = collectAnalysis(projectRoot, changeDir);
+  for (const r of results) console.log(r.line);
+  console.log("");
+
+  const failed = results.filter((r) => r.kind === "fail").length;
+  if (failed === 0) {
+    console.log(c.green("ok") + ` ready to apply`);
+  } else {
+    console.log(c.red("fail") + ` ${failed} issue${failed === 1 ? "" : "s"}`);
+  }
+  return failed === 0 ? 0 : 1;
+}
+
+// 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
@@ -32,6 +57,37 @@ export async function run(positional, _flags) {
     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
@@ -75,11 +131,11 @@ export async function run(positional, _flags) {
       const cap = capMatch ? capMatch[1] : path.basename(path.dirname(deltaPath));
 
       if (!op) {
-        results.push(fail(`  ${rel}: Operation header missing or malformed`, "  "));
+        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`, "  "));
+        results.push(fail(`  ${rel}: Operation "${op}" is not one of ADDED|MODIFIED|REMOVED`));
         continue;
       }
       const targetSpec = path.join(projectRoot, ".doctrina", "specs", cap, "spec.md");
@@ -89,38 +145,29 @@ export async function run(positional, _flags) {
         // 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`, "  "));
+          results.push(fail(`  ${cap} (ADDED) but target ${targetRel} has real content — use MODIFIED or remove it first`));
         } else if (exists(targetSpec)) {
-          results.push(pass(`  ${cap} (ADDED) → ${targetRel} (replaces the untouched scaffold)`, "  "));
+          results.push(pass(`  ${cap} (ADDED) → ${targetRel} (replaces the untouched scaffold)`));
         } else {
-          results.push(pass(`  ${cap} (ADDED) → ${targetRel} (new)`, "  "));
+          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`, "  "));
+          results.push(fail(`  ${cap} (MODIFIED) but target ${targetRel} does not exist`));
         } else {
-          results.push(pass(`  ${cap} (MODIFIED) → ${targetRel}`, "  "));
+          results.push(pass(`  ${cap} (MODIFIED) → ${targetRel}`));
         }
       } else {
         if (!exists(targetSpec)) {
-          results.push(fail(`  ${cap} (REMOVED) but target ${targetRel} does not exist`, "  "));
+          results.push(fail(`  ${cap} (REMOVED) but target ${targetRel} does not exist`));
         } else {
-          results.push(pass(`  ${cap} (REMOVED) → ${targetRel}`, "  "));
+          results.push(pass(`  ${cap} (REMOVED) → ${targetRel}`));
         }
       }
     }
   }
 
-  for (const r of results) console.log(r.line);
-  console.log("");
-
-  const failed = results.filter((r) => r.kind === "fail").length;
-  if (failed === 0) {
-    console.log(c.green("ok") + ` ready to apply`);
-  } else {
-    console.log(c.red("fail") + ` ${failed} issue${failed === 1 ? "" : "s"}`);
-  }
-  return failed === 0 ? 0 : 1;
+  return results;
 }
 
 function pass(msg) {

package/src/commands/change.js

@@ -1,3 +1,5 @@
+// @ts-check
+import { getSection, getHeader } from "../lib/doc-model.js";
 import path from "node:path";
 import process from "node:process";
 import { exists, isDir, isFile, lineCount, mkdirp, move, read, relPath, remove, walk, write } from "../lib/fs-ops.js";
@@ -7,13 +9,22 @@ 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 { GATES, TRANSITIONS, checkTransition, recordForcedGap } from "../lib/gates.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";
+import { confirm, isInteractive } from "../lib/prompt.js";
+import { EXIT } from "../lib/exit-codes.js";
+import { notADoctrinaProject } from "../lib/exit-codes.js";
 
 const SUBCOMMANDS = ["new", "apply", "archive", "check", "tick", "diff", "abandon"];
 
+// Flags this command accepts. Declared HERE, with the command, so
+// adding a command never requires editing the entrypoint — the gap that
+// let six flags ship undeclared and silently swallow a positional (C3).
+export const flags = { boolean: ["json", "all", "chore", "design", "force", "no-spec"], string: ["reason"] };
+
 export async function run(positional, flags) {
   const sub = positional[0];
   switch (sub) {
@@ -30,7 +41,7 @@ export async function run(positional, flags) {
     case "diff":
       return changeDiff(positional.slice(1), flags);
     case "abandon":
-      return changeAbandon(positional.slice(1), flags);
+      return await changeAbandon(positional.slice(1), flags);
     default:
       console.error(c.red("error:") + ` unknown change subcommand "${sub ?? ""}"`);
       const guess = suggest(sub, SUBCOMMANDS);
@@ -41,6 +52,29 @@ export async function run(positional, flags) {
   }
 }
 
+// Enforce a lifecycle transition's preconditions from the shared gate map.
+// Returns true when the transition may proceed. One implementation, so
+// every driver of a transition refuses — and explains, and forces —
+// identically (C6).
+function enforceTransition(projectRoot, id, changeDir, transition, flags) {
+  const force = flagBool(flags, "force", false);
+  const { ok, blockers } = checkTransition(projectRoot, changeDir, transition);
+  if (ok) return true;
+
+  const label = TRANSITIONS[transition].label;
+  if (!force) {
+    console.error(c.red("error:") + ` refusing to ${transition} "${id}" — ${blockers.length} blocker${blockers.length === 1 ? "" : "s"}:`);
+    for (const b of blockers) console.error(`  - [${b.gate}] ${b.message}`);
+    const reruns = [...new Set(blockers.map((b) => GATES[b.gate].rerun(id)))];
+    console.error(c.gray("hint: ") + `fix them (${reruns.join(" · ")}), or pass --force to ${transition} anyway (records the gap)`);
+    return false;
+  }
+  console.log(c.yellow("warn:") + ` ${label} "${id}" with ${blockers.length} blocker${blockers.length === 1 ? "" : "s"} (--force):`);
+  for (const b of blockers) console.log(c.yellow("  - ") + `[${b.gate}] ${b.message}`);
+  recordForcedGap(projectRoot, id, transition, blockers);
+  return true;
+}
+
 // 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
@@ -146,7 +180,7 @@ function changeNew(args, flags) {
   return 0;
 }
 
-function changeApply(args, _flags) {
+function changeApply(args, flags) {
   const id = args[0];
   if (!id) {
     console.error(c.red("error:") + " change apply requires <id>");
@@ -161,6 +195,30 @@ function changeApply(args, _flags) {
     return 1;
   }
 
+  // Gate parity (C6). `apply` used to mutate specs with no preconditions,
+  // so `analyze` could exit 1 on a change and `apply` would write it anyway
+  // and exit 0 — through the very analyze → apply path the docs prescribe.
+  // The preconditions now come from the shared map, so what guards a
+  // transition does not depend on which command drove it.
+  if (!enforceTransition(projectRoot, id, changeDir, "apply", flags)) return 1;
+
+  // Applying twice is silent corruption. The ops verbs are ADDITIVE —
+  // `append-requirement` appends, `bump-version` bumps — so a second pass
+  // duplicates every requirement and criterion the delta carries and bumps
+  // the version again. `apply` stamps the proposal `applied` on success, so
+  // that stamp is the guard. (Found by `close` re-running apply on an
+  // already-applied change and doubling 15 requirements on this repo.)
+  const proposalPath = path.join(changeDir, "proposal.md");
+  const alreadyApplied = isFile(proposalPath)
+    && (getHeader(read(proposalPath), "Status") ?? "").trim().toLowerCase() === "applied";
+  if (alreadyApplied && !flagBool(flags, "force", false)) {
+    console.log(c.gray("skip ") + `change "${id}" is already applied — nothing to do`);
+    console.log(c.gray("The ops verbs are additive: applying twice duplicates every"));
+    console.log(c.gray("requirement this delta carries. Re-apply anyway with --force"));
+    console.log(c.gray("only after reverting the specs to their pre-apply state."));
+    return 0;
+  }
+
   const deltaFiles = walk(path.join(changeDir, "specs")).filter((p) => p.endsWith("delta.md"));
   const date = today();
   let errors = 0;
@@ -342,12 +400,14 @@ async function changeCheck(id) {
 
   // 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)");
+  // Preview through the SAME map the transitions enforce, so `check` can
+  // never disagree with what `apply` / `archive` will actually do (C6).
+  const archiveGate = checkTransition(projectRoot, changeDir, "archive");
+  if (archiveGate.ok) {
+    console.log(c.green("✓ ") + `archive gate clear (${archiveGate.gates.join(" + ")})`);
   } else {
     failures += 1;
-    for (const b of blockers) console.log(c.red("✗ ") + b);
+    for (const b of archiveGate.blockers) console.log(c.red("✗ ") + `[${b.gate}] ${b.message}`);
     console.log(c.gray("    check them off as they land, or in bulk: ") + c.cyan(`doctrina change tick ${id} --all`));
   }
 
@@ -490,22 +550,12 @@ function changeArchive(args, flags) {
   // task (including closing steps) or any declared verification item is
   // still unchecked. This is the difference between "boxes marked" and
   // "verification passed" the framework was faulted for collapsing.
-  // --force is the escape hatch: it archives anyway and records the gap.
-  const force = flagBool(flags, "force", false);
-  const blockers = collectArchiveBlockers(changeDir);
-  if (blockers.length > 0) {
-    if (!force) {
-      console.error(c.red("error:") + ` refusing to archive "${id}" — verification incomplete:`);
-      for (const b of blockers) console.error(`  - ${b}`);
-      console.error(
-        c.gray("hint: ") +
-          "finish and check the items, or pass --force to archive anyway (records the gap)",
-      );
-      return 1;
-    }
-    console.log(c.yellow("warn:") + ` archiving "${id}" with verification incomplete (--force):`);
-    for (const b of blockers) console.log(c.yellow("  - ") + b);
-  }
+  // Preconditions from the shared map (C6): structure AND verification.
+  // Reaching archive directly used to skip the structural check that the
+  // `close` path always ran first, so the same state was guarded
+  // differently depending on the route taken. --force is the escape hatch
+  // for both, and records the gap.
+  if (!enforceTransition(projectRoot, id, changeDir, "archive", flags)) return 1;
 
   const date = today();
   const archiveName = `${date}-${id}`;
@@ -593,7 +643,7 @@ function changeArchive(args, flags) {
 // and record the abandonment in the ledger so the history shows the dead end
 // instead of a silent gap. This is the missing inverse of `change new` — the
 // review had to delete a stray folder and hand-edit index.json (G6).
-function changeAbandon(args, flags) {
+async function changeAbandon(args, flags) {
   const id = args[0];
   if (!id) {
     console.error(c.red("error:") + " change abandon requires <id>");
@@ -608,6 +658,31 @@ function changeAbandon(args, flags) {
     return 1;
   }
 
+  // Consent before destruction (audit item C9). This deletes work with no
+  // undo — the ledger line is good practice and is not a substitute for
+  // being asked. Off a terminal there is nobody to ask, so `--force` is
+  // required: silence is not consent.
+  const force = flagBool(flags, "force", false);
+  if (!force) {
+    const doomed = walk(changeDir);
+    console.log(c.yellow("About to delete") + ` ${relPath(projectRoot, changeDir)} — ${doomed.length} file${doomed.length === 1 ? "" : "s"}:`);
+    for (const f of doomed.slice(0, 10)) console.log(`    ${c.gray(relPath(changeDir, f))}`);
+    if (doomed.length > 10) console.log(c.gray(`    … and ${doomed.length - 10} more`));
+    console.log(c.gray("This cannot be undone (the change is deleted, not archived)."));
+
+    if (!isInteractive()) {
+      console.error("");
+      console.error(c.red("error:") + " refusing to delete without confirmation");
+      console.error(c.gray("hint: ") + `re-run with ${c.cyan("--force")} to abandon non-interactively`);
+      return EXIT.USAGE;
+    }
+    const ok = await confirm(`Abandon "${id}"?`, { defaultYes: false, whenNonInteractive: false });
+    if (!ok) {
+      console.log(c.gray("aborted — nothing was deleted"));
+      return EXIT.OK;
+    }
+  }
+
   const reason = flagString(flags, "reason") ?? "";
   const date = today();
 
@@ -776,32 +851,15 @@ function collectArchiveBlockers(changeDir) {
 
   const proposalPath = path.join(changeDir, "proposal.md");
   if (exists(proposalPath)) {
-    const n = countUnchecked(extractSection(read(proposalPath), "Verification"));
+    const n = countUnchecked(getSection(read(proposalPath), "Verification"));
     if (n > 0) blockers.push(`${n} unmet verification item${n === 1 ? "" : "s"} in proposal.md (## Verification)`);
   }
   return blockers;
 }
 
-// Return the body of a "## <name>" section (lines after the heading up to
-// the next "## " heading). Empty string when the section is absent.
-function extractSection(text, name) {
-  const lines = text.split(/\r?\n/);
-  const head = new RegExp(`^##\\s+${name}\\b`, "i");
-  let inSection = false;
-  const out = [];
-  for (const line of lines) {
-    if (/^##\s+/.test(line)) {
-      inSection = head.test(line);
-      continue;
-    }
-    if (inSection) out.push(line);
-  }
-  return out.join("\n");
-}
-
 function ensureDoctrinaProject(projectRoot) {
   if (!exists(path.join(projectRoot, ".doctrina"))) {
-    throw new Error("not a Doctrina project (no .doctrina/ in cwd). Run `doctrina init` first.");
+    throw notADoctrinaProject();
   }
 }
 

package/src/commands/clarify.js

@@ -1,9 +1,11 @@
+// @ts-check
 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, flagString } from "../lib/args.js";
 import { c } from "../lib/colors.js";
+import { notADoctrinaProject } from "../lib/exit-codes.js";
 
 // Two lexicons, one linter (0.11.0 field review item 3: an English-only
 // clarify is permanently red on a PT-BR project — "some" is the verb *sumir*,
@@ -98,6 +100,11 @@ function forcedLang(flags) {
   return null;
 }
 
+// Flags this command accepts. Declared HERE, with the command, so
+// adding a command never requires editing the entrypoint — the gap that
+// let six flags ship undeclared and silently swallow a positional (C3).
+export const flags = { boolean: ["json", "all"], string: ["lang"] };
+
 export async function run(positional, flags) {
   const projectRoot = process.cwd();
 
@@ -138,7 +145,7 @@ export async function run(positional, flags) {
 // register from prose specs.
 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.");
+    throw notADoctrinaProject();
   }
   const files = [];
   const productPath = path.join(projectRoot, ".doctrina", "product.md");