doctrina-cli 0.16.0 → 0.18.0

package/src/commands/templates.js

@@ -19,6 +19,7 @@ import { collectFindings, agentsSectionCost, AGENTS_SECTIONS, PRODUCT_SECTIONS,
 // too (audit finding F7); this command renders and fixes them.
 export { collectFindings } from "../lib/templates-model.js";
 import { suggest } from "../lib/suggest.js";
+import { ensureDoctrinaProject } from "../lib/project.js";
 
 const SUBCOMMANDS = ["list", "check", "update"];
 
@@ -50,10 +51,7 @@ export async function run(positional, flags) {
 function updateTemplates(flags) {
   const writeMode = flagBool(flags, "write", false);
   const projectRoot = process.cwd();
-  if (!isDir(path.join(projectRoot, ".doctrina"))) {
-    console.error(c.red("error:") + " not a Doctrina project (no .doctrina/ in cwd)");
-    return 1;
-  }
+  ensureDoctrinaProject(projectRoot);
 
   const plan = [];
   // Updates this run declines to make, each with the reason and the number.
@@ -176,7 +174,7 @@ function updateTemplates(flags) {
           let updated = read(filePath);
           if (!updated.endsWith("\n")) updated += "\n";
           for (const h of missing) {
-            updated += `\n${h}\n\n<!-- added by doctrina templates update — fill in -->\n`;
+            updated += `\n${h}\n\n<!-- added by doctrina upgrade — fill in -->\n`;
           }
           write(filePath, updated, { force: true });
         },
@@ -287,11 +285,7 @@ function listTemplates() {
 
 function checkTemplates() {
   const projectRoot = process.cwd();
-  if (!isDir(path.join(projectRoot, ".doctrina"))) {
-    console.error(c.red("error:") + " not a Doctrina project (no .doctrina/ in cwd)");
-    console.error(c.gray("hint: ") + "run `doctrina init` first");
-    return 1;
-  }
+  ensureDoctrinaProject(projectRoot);
   const { findings, ok } = collectFindings(projectRoot);
 
   return report(findings, ok);

package/src/commands/upgrade.js

@@ -9,6 +9,7 @@ import { flagBool } from "../lib/args.js";
 import { c } from "../lib/colors.js";
 import { today } from "../lib/dates.js";
 import { notADoctrinaProject } from "../lib/exit-codes.js";
+import { collectFindings } from "../lib/templates-model.js";
 import * as templates from "./templates.js";
 import * as validate from "./validate.js";
 
@@ -56,11 +57,23 @@ export async function run(_positional, flags) {
   // 2. Additive template updates (missing recommended sections in AGENTS.md /
   //    product.md, missing index.json fields). Reuses `templates update`
   //    verbatim: preview without --write, apply with it.
-  console.log(c.gray("──── 1/3 scaffold shape (templates update)"));
+  console.log(c.gray("──── 1/3 scaffold shape"));
   const tplFlags = writeMode ? new Map([["write", true]]) : new Map();
   const tplCode = await templates.run(["update"], tplFlags);
   if (tplCode !== 0 && !writeMode) pending += 1; // preview exits 1 when updates are pending
 
+  // What the additive update cannot fix — a drifted adapter, a broken
+  // playbook, an index schema it does not know — used to be visible only to
+  // `templates check`. Printed here, each with its own remedy, so the one
+  // command that brings a project up to date also says what is left for a
+  // person (change 0178: the check and the update became this step).
+  const manual = collectFindings(projectRoot).findings
+    .filter((f) => !/upgrade --write|index rebuild/.test(f.remedy ?? ""));
+  for (const f of manual) {
+    console.log(c.yellow("✗ ") + f.message);
+    console.log(c.gray("    fix: ") + (f.remedy ? c.cyan(f.remedy) : c.gray("manual repair — no command can fix this")));
+  }
+
   // 3. Index: rebuild from the tree, which also migrates the framework stamp.
   console.log("");
   console.log(c.gray("──── 2/3 index + framework stamp"));
@@ -101,14 +114,22 @@ export async function run(_positional, flags) {
   const vCode = await validate.run([], vFlags);
 
   console.log("");
+  if (manual.length > 0) {
+    console.log(c.yellow("manual") + ` ${manual.length} finding${manual.length === 1 ? "" : "s"} the upgrade cannot repair — see step 1`);
+  }
   if (!writeMode) {
-    if (pending > 0) {
+    if (pending > 0 || manual.length > 0) {
+      if (pending === 0) return 1;
       console.log(c.yellow("pending") + ` upgrade steps found — apply them: ${c.cyan("doctrina upgrade --write")}`);
       return 1;
     }
     console.log(c.green("ok") + " nothing to upgrade — the project matches the installed CLI");
     return vCode;
   }
+  if (vCode === 0 && manual.length > 0) {
+    console.log(c.yellow(`upgraded to ${running} with manual repairs left`) + " — each finding in step 1 names its fix.");
+    return 1;
+  }
   if (vCode === 0) {
     console.log(c.green(`✓ project upgraded to ${running}`) + c.gray(" — review any warnings above; new commands: `doctrina --help`."));
     console.log(c.gray("AGENTS.md's doctrina:surface block was regenerated from the installed catalog, so agents reading the hub now discover the current commands."));
@@ -125,16 +146,20 @@ Bring an existing project up to the installed CLI after an npm update.
 The project keeps the scaffold of the version that init-ed it; this is
 the one command that closes the gap, orchestrating the existing pieces:
 
-  1. templates update   — regenerate the AGENTS.md doctrina:surface block
+  1. scaffold shape     — regenerate the AGENTS.md doctrina:surface block
                           from the installed command catalog (the block is
                           CLI-owned, ADR 0015 — this is how agents reading
-                          the hub discover commands added since init), and
+                          the hub discover commands added since init),
                           append missing recommended sections / index.json
-                          fields (additive-only outside the block)
+                          fields (additive-only outside the block), and
+                          list what no command can repair (a drifted
+                          adapter, a broken playbook), each with its fix
   2. index rebuild      — regenerate index.json from the tree and migrate
                           the framework_version stamp to the running CLI
   3. validate (--fix)   — surface anything the upgrade cannot fix
                           (hand-authored drift, new validate checks)
 
-Preview by default (exits 1 when steps are pending); --write applies.
+Preview by default (exits 1 when steps are pending or a manual repair is
+left); --write applies. The preview is what \`templates check\` reported
+and --write what \`templates update --write\` did — both deprecated.
 `;

package/src/commands/validate.js

@@ -20,7 +20,7 @@ import { collectValidation } from "../lib/validation-model.js";
 // wrap it in the generic envelope.
 export const jsonNative = true;
 
-export const flags = { boolean: ["fix", "json", "runtime"], string: [] };
+export const flags = { boolean: ["fix", "json", "runtime", "strict"], string: [] };
 
 export async function run(_positional, flags) {
   const projectRoot = process.cwd();
@@ -34,10 +34,26 @@ export async function run(_positional, flags) {
     runtime: flagBool(flags, "runtime", false),
   });
 
+  // --strict makes a warning count against the exit code, matching what
+  // `--strict` already means on `coverage` and `trace`: fail on any gap.
+  //
+  // The default has to stay lenient — a warning is advice, and advice that
+  // blocks a commit stops being read. But that leniency left a gate that
+  // COULD NOT REPROVE: the CI step that validates the shipped examples runs
+  // this command, both examples had drifted to warnings, and the step passed
+  // green through every run. The EARS defect the retrofit example exists to
+  // teach against was reintroduced and sat there, twice, because nothing
+  // downstream of `validate` could say no.
+  //
+  // So the choice belongs to the caller. A human at a terminal wants the
+  // advice; a gate wants a verdict.
+  const strict = flagBool(flags, "strict", false);
+  const failed = errors.length > 0 || (strict && warnings.length > 0);
+
   // Output
   if (flagBool(flags, "json", false)) {
-    emitJson("validate", { errors, warnings });
-    return errors.length === 0 ? 0 : 1;
+    emitJson("validate", { errors, warnings, strict });
+    return failed ? 1 : 0;
   }
   // The repairs print first and in the order they were made: --fix changes
   // the tree, and what it changed must be visible before what it then found.
@@ -50,17 +66,21 @@ export async function run(_positional, flags) {
     console.log(c.green("ok") + " all validation checks passed");
   } else {
     const summary = `${errors.length} error${errors.length === 1 ? "" : "s"}, ${warnings.length} warning${warnings.length === 1 ? "" : "s"}`;
-    console.log((errors.length === 0 ? c.green("ok") : c.red("fail")) + " " + summary);
+    console.log((failed ? c.red("fail") : c.green("ok")) + " " + summary);
+    // Say WHY a run with no errors is failing, or the exit code reads as a bug.
+    if (strict && errors.length === 0 && warnings.length > 0) {
+      console.log(c.gray("       --strict: warnings count against the exit code"));
+    }
   }
-  return errors.length === 0 ? 0 : 1;
+  return failed ? 1 : 0;
 }
 
 export const help = `
-Usage: doctrina validate [--fix] [--runtime] [--json]
+Usage: doctrina validate [--fix] [--runtime] [--strict] [--json]
 
 Run schema, artifact-existence, and structural checks against the
 .doctrina/ tree in the current working directory. Exits 0 if no errors
-(warnings allowed), 1 otherwise.
+(warnings allowed), 1 otherwise. With --strict, a warning fails it too.
 
 Two structural checks worth naming:
 
@@ -84,5 +104,9 @@ Flags:
               selectors checked against the workflows and code that are
               supposed to honour them (the same checks as \`contract check\`).
               Opt-in because it reads files outside .doctrina/.
-  --json      Emit { ok, errors, warnings } as JSON (stable shape for agents/CI).
+  --strict    Treat warnings as failures, the way \`coverage --strict\` and
+              \`trace --strict\` already do. The default stays lenient because
+              a warning is advice; a GATE wants a verdict, so anything that
+              must be able to reprove passes this.
+  --json      Emit { ok, errors, warnings, strict } as JSON (stable shape for agents/CI).
 `;

package/src/commands/verify.js

@@ -8,9 +8,10 @@ import { exists, isDir, isFile, read, write, relPath } from "../lib/fs-ops.js";
 import { flagBool, flagString } from "../lib/args.js";
 import { today } from "../lib/dates.js";
 import { c } from "../lib/colors.js";
-import { loadSignoffs, saveSignoffs, recordSignoff, signoffState, short, SIGNOFF_REL } from "../lib/signoff.js";
+import { loadSignoffs, saveSignoffs, recordSignoff, signoffState, short, SIGNOFF_REL, declaredPaths, workingChanges } from "../lib/signoff.js";
 import { EXIT, notADoctrinaProject } from "../lib/exit-codes.js";
 import { collectReproducibility } from "../lib/reproducibility.js";
+import { verifyFingerprint, recordGreen, reusableGreen } from "../lib/verify-cache.js";
 
 // The build/verify gate `validate` is not. `validate` checks the shape of
 // the artifact tree; it never runs the project, so a repo that does not
@@ -40,7 +41,7 @@ const STARTER = {
 // 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", "clean", "force", "init", "list", "strict"], string: ["signoff"] };
+export const flags = { boolean: ["json", "clean", "force", "init", "list", "strict", "reuse", "affected"], string: ["signoff"] };
 
 export async function run(_positional, flags) {
   const projectRoot = process.cwd();
@@ -182,6 +183,22 @@ export async function run(_positional, flags) {
   }
 
   const strict = flagBool(flags, "strict", false);
+  const affected = flagBool(flags, "affected", false);
+  // The fingerprint of the code these checks are about to run on, taken
+  // BEFORE they run (change 0203): what a green run proves is the tree it
+  // started from. Null outside git — then nothing is remembered or reused.
+  const fingerprint = verifyFingerprint(projectRoot, read(configPath));
+  if (flagBool(flags, "reuse", false) && fingerprint !== null) {
+    const green = reusableGreen(projectRoot, fingerprint);
+    if (green) {
+      console.log(c.bold("doctrina verify") + c.gray(` — ${checks.length} check${checks.length === 1 ? "" : "s"} from ${CONFIG_REL}`));
+      console.log("");
+      console.log(c.green("ok") + ` reused the green run of ${green.at.replace("T", " ").slice(0, 16)} UTC — ` +
+        `the code and ${CONFIG_REL} are byte-identical to what it ran on (${green.checks.join(", ")})`);
+      console.log(c.gray("   `doctrina verify` runs the checks again"));
+      return 0;
+    }
+  }
   console.log(c.bold("doctrina verify") + c.gray(` — ${checks.length} check${checks.length === 1 ? "" : "s"} from ${CONFIG_REL}`));
   const results = [];
   for (const ch of checks) {
@@ -220,6 +237,20 @@ export async function run(_positional, flags) {
       continue;
     }
 
+    // --affected (change 0204): a check that declares the "paths" it covers
+    // runs only when the uncommitted work touches one of them. The inner
+    // loop of a change — not the close, which always runs every check. A
+    // check that declares no paths covers everything and always runs; a
+    // question git cannot answer runs the check.
+    if (affected && declaredPaths(ch).length > 0) {
+      const touched = workingChanges(projectRoot, declaredPaths(ch));
+      if (touched !== null && touched.length === 0) {
+        console.log(c.gray(`──── ${name}: `) + c.gray(`skip — the uncommitted work touches none of ${declaredPaths(ch).join(", ")}`));
+        results.push({ name, ok: true, kind: "command", skipped: true });
+        continue;
+      }
+    }
+
     const where = ch.cwd ? c.gray(` [${ch.cwd}]`) : "";
     console.log(c.gray(`──── ${name}: `) + ch.run + where);
     // Run through the shell so declared commands can use pipes, &&, env,
@@ -287,9 +318,18 @@ export async function run(_positional, flags) {
   // manual check still awaiting sign-off. Pending manual checks are otherwise
   // a non-blocking report.
   const failGate = cmdFailed.length > 0 || (strict && pending.length > 0);
-  const pendNote = pending.length > 0 ? c.gray(` (${pending.length} manual pending)`) : "";
+  const skipped = results.filter((r) => r.skipped);
+  const pendNote = (pending.length > 0 ? c.gray(` (${pending.length} manual pending)`) : "") +
+    (skipped.length > 0 ? c.gray(` (${skipped.length} skipped by --affected: ${skipped.map((r) => r.name).join(", ")})`) : "");
   if (!failGate) {
-    console.log(c.green("ok") + ` ${passed}/${results.length} checks passed${pendNote}`);
+    const ran = passed - skipped.length;
+    console.log(c.green("ok") + ` ${ran}/${results.length - skipped.length} checks passed${pendNote}`);
+    // Remembered only when EVERY check passed — a run green with a manual
+    // check still pending is a report, not something a close may stand on,
+    // and neither is a run --affected cut short.
+    if (fingerprint !== null && pending.length === 0 && skipped.length === 0) {
+      recordGreen(projectRoot, fingerprint, results.map((r) => r.name));
+    }
     return 0;
   }
   const reasons = [];
@@ -403,7 +443,7 @@ function renderReproducibility(projectRoot) {
 }
 
 export const help = `
-Usage: doctrina verify [--list] [--init] [--clean] [--strict] [--signoff "<name>=<note>"] [--force]
+Usage: doctrina verify [--list] [--init] [--clean] [--strict] [--reuse] [--affected] [--signoff "<name>=<note>"] [--force]
 
 Run the project-declared build/verify checks from ${CONFIG_REL} in order,
 streaming their output, and exit non-zero if any check fails. This is the
@@ -414,13 +454,18 @@ root, targets a sub-package in a monorepo; a "manual" check is the
 qualitative gate — judged by a human/eval, recorded as a sign-off, not run):
   {
     "checks": [
-      { "name": "typecheck", "run": "tsc --noEmit", "cwd": "packages/api" },
+      { "name": "typecheck", "run": "tsc --noEmit", "cwd": "packages/api",
+        "paths": ["packages/api"] },
       { "name": "test",      "run": "npm test" },
       { "name": "build",     "run": "npm run build" },
       { "name": "chronicle", "type": "manual", "rubric": "is the chronicle enjoyable to read?" }
     ]
   }
 
+"paths" (git pathspecs, relative to the project root) says what a check
+covers: --affected runs it only when the uncommitted work touches one, and a
+manual check's sign-off expires when one changes.
+
 A manual check passes when it has been signed off and is otherwise reported
 as "pending" — non-blocking by default, failing only under --strict (so CI
 can require the sign-off). Sign-offs are stored in ${SIGNOFF_REL}.
@@ -450,6 +495,14 @@ Flags:
              prepare/prepack; a Prisma dep with no generate on install) so
              "verify green" can't hide a clean checkout that won't build.
   --strict   Fail the gate when a manual check is still pending sign-off
+  --reuse    Skip the checks when the last fully green run covered this exact
+             code: the working tree (tracked, untracked, edits) minus
+             .doctrina/, plus ${CONFIG_REL}, are byte-identical. \`close\` runs
+             verify this way; a plain \`doctrina verify\` always runs them.
+  --affected Run a check that declares "paths" only when the uncommitted work
+             (edits against HEAD, untracked files) touches one of them —
+             the inner loop of a change. Checks with no "paths" always run;
+             \`close\` always runs every check. Never remembered by --reuse.
   --signoff "<name>=<note>"
              Record today's sign-off for a manual check, then exit
   --force    With --init, overwrite an existing config

package/src/commands/work.js

@@ -9,13 +9,14 @@ import { c } from "../lib/colors.js";
 import { assessBrief } from "../lib/clarity.js";
 import { locateTemplatesDir, substitute } from "../lib/templates.js";
 import { EXIT, notADoctrinaProject } from "../lib/exit-codes.js";
-import { changeNew, reindexChange } from "../lib/change-ops.js";
+import { changeNew, reindexChange, addAffectedSpec } from "../lib/change-ops.js";
 import { classify } from "../lib/triage-model.js";
 import { printPlaybookTemplate } from "../lib/playbook.js";
+import { specShape } from "../lib/spec-ops.js";
 import { changedFiles } from "../lib/git.js";
 import { slugFromPrompt, fold, CONFIDENT_MARGIN } from "../lib/lexicon.js";
 import { rankCapabilities, rankCapabilitiesByDiff } from "../lib/work-model.js";
-import { isChangeId } from "../lib/project.js";
+import { isChangeId, refuseChangeRef } from "../lib/project.js";
 export { rankCapabilities, rankCapabilitiesByDiff } from "../lib/work-model.js";
 
 // `work` is the second half of the no-ceremony path (ADR 0005): a brief
@@ -29,14 +30,36 @@ export { rankCapabilities, rankCapabilitiesByDiff } from "../lib/work-model.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", "chore", "force", "from-diff", "no-spec", "quiet"], string: ["capability", "id", "resume", "title"] };
+export const flags = { boolean: ["json", "chore", "design", "force", "from-diff", "no-spec", "quiet"], string: ["capability", "consolidate", "id", "resume", "title"] };
 
 export async function run(positional, flags) {
-  const prompt = positional.join(" ").trim();
   const projectRoot = process.cwd();
   if (!exists(path.join(projectRoot, ".doctrina"))) {
     throw notADoctrinaProject();
   }
+  // --consolidate <cap> (change 0206): a spec only ever grew — every change
+  // appended, nothing took a requirement out — and a field review of 0.17
+  // asked for "a command to consolidate a spec from time to time". It is an
+  // ordinary change pinned to the capability, with its own playbook: the
+  // agent decides what is redundant or superseded (ADR 0005), and the ops
+  // take it out.
+  const consolidate = flags.has("consolidate") ? flagString(flags, "consolidate") : null;
+  if (consolidate !== null) {
+    if (!consolidate || /** @type {unknown} */ (consolidate) === true || !/^[a-z][a-z0-9-]*$/.test(consolidate)) {
+      console.error(c.red("error:") + " --consolidate needs the capability whose spec to consolidate");
+      return EXIT.USAGE;
+    }
+    if (!isFile(path.join(projectRoot, ".doctrina", "specs", consolidate, "spec.md"))) {
+      console.error(c.red("error:") + ` capability "${consolidate}" has no spec at .doctrina/specs/${consolidate}/spec.md`);
+      return EXIT.USAGE;
+    }
+    flags.set("capability", consolidate);
+    flags.set("force", true);
+    if (!flags.has("title")) flags.set("title", `consolidate ${consolidate}`);
+  }
+  const prompt = consolidate
+    ? `Consolidate the ${consolidate} spec: merge requirements and criteria that say the same thing, drop what a later one superseded — no behaviour changes.`
+    : positional.join(" ").trim();
 
   // --resume <id>: reprint the playbook for an existing open change rather than
   // open a new one (review G1 — `work "continue"` used to slug the word and
@@ -205,6 +228,12 @@ export async function run(positional, flags) {
     ? null
     : scaffoldDelta(projectRoot, { id, capability, guess, runnerUp: promptMatches[1] ?? null });
 
+  // A guessed delta names the capability as surely as a pinned one: the
+  // header says what the folder says (change 0207). It stayed empty for
+  // every unpinned `work`, so the proposal claimed no spec while its delta
+  // targeted one.
+  if (scaffolded) addAffectedSpec(projectRoot, id, scaffolded.capability);
+
   // The proposal is written in two passes — `changeNew` scaffolds it, the
   // lines above stamp the lane and the pinned specs — so its index entry is
   // re-derived HERE, from the finished file. Indexing at the end of the first
@@ -223,7 +252,9 @@ export async function run(positional, flags) {
   }
 
   console.log("");
-  if (chore) {
+  if (consolidate) {
+    printConsolidatePlaybook(projectRoot, { id, capability: consolidate });
+  } else if (chore) {
     printChorePlaybook(projectRoot, { id, prompt: effPrompt });
   } else {
     printPlaybook(projectRoot, {
@@ -387,6 +418,8 @@ function resumeChange(projectRoot, resumeId) {
     if (open.length) console.error(c.gray("open: ") + open.map((ch) => ch.id).join(", "));
     return 2;
   }
+  const refused = refuseChangeRef(resumeId);
+  if (refused !== null) return refused;
   const entry = open.find((ch) => ch.id === resumeId);
   if (!entry && !isDir(path.join(projectRoot, ".doctrina", "changes", resumeId))) {
     console.error(c.red("error:") + ` no open change "${resumeId}"`);
@@ -438,6 +471,21 @@ export function slugify(text) {
 // part that is not prose: computing the variable blocks. Each is PRE-RENDERED
 // into a token, so `substitute` stays a plain string map and the template
 // stays a document rather than a language with conditionals in it.
+// The consolidation playbook: the spec's shape, measured, then the steps.
+// Measuring is the CLI's part; deciding which requirement is redundant is
+// the agent's (ADR 0005).
+function printConsolidatePlaybook(projectRoot, { id, capability }) {
+  const text = read(path.join(projectRoot, ".doctrina", "specs", capability, "spec.md"));
+  const shape = specShape(text);
+  const sections = Object.entries(shape.sections).map(([k, n]) => `${k} ${n}`).join(" · ");
+  printPlaybookTemplate(projectRoot, "consolidate", {
+    CHANGE_ID: id,
+    CAPABILITY: capability,
+    SHAPE: `${shape.lines} lines · ${shape.requirements} requirements (${sections || "none"}) · ` +
+      `${shape.criteria} acceptance criteria`,
+  });
+}
+
 function printChorePlaybook(projectRoot, { id, prompt }) {
   printPlaybookTemplate(projectRoot, "chore", { CHANGE_ID: id, PROMPT: prompt });
 }
@@ -515,9 +563,10 @@ change id (NNNN-<slug>) from the prompt, opens the change folder,
 records the prompt under the proposal's "## Why", ranks existing specs
 by term overlap as a capability hint, flags a thin/under-specified prompt
 so you clarify before writing deltas (advisory), and prints the steps:
-context → spec delta → tasks → implement → analyze → apply → verify
-(verify + coverage) → archive → validate. No natural-language
-interpretation happens in the CLI.
+context, spec delta, tasks, implement, then \`doctrina change check <id>\`
+to preview the close and \`doctrina close <id>\` to finish, which runs the
+whole closing sequence in one pass. No natural-language interpretation
+happens in the CLI.
 
 The change's spec delta is scaffolded with **Operation:** prefilled
 whenever the CLI can name the capability: from --capability, or from the
@@ -540,8 +589,14 @@ Options:
   --resume <id>        Reprint the playbook for an open change; create nothing
   --from-diff          Backfill: scaffold from the working-tree changes (no
                        prompt needed) and print a code-first playbook (F8)
+  --consolidate <cap>  Open a change that consolidates <cap>'s spec — merge
+                       what says the same thing, remove what was superseded
+                       (remove-requirement / remove-criterion) — with its own
+                       playbook; no prompt needed, no behaviour changes
   --chore, --no-spec   Open a spec-less chore change (infra/docs/build) with a
                        playbook that skips the spec-delta steps (F9)
+  --design             Also scaffold design.md, for a change with non-trivial
+                       choices (opt-in, as with \`change new --design\`)
   --force              Open a new change even when one is open, overwrite an
                        existing change folder, and proceed past the lane hold
                        below

package/src/index.js

@@ -5,7 +5,7 @@ import { parseArgs } from "./lib/args.js";
 import { c } from "./lib/colors.js";
 import { suggest } from "./lib/suggest.js";
 import { cliVersion } from "./lib/version.js";
-import { surfaceHelp, OPERATIONS, deprecationFor } from "./lib/commands.js";
+import { surfaceHelp, OPERATIONS, deprecationFor, removalFor } from "./lib/commands.js";
 import { GLOBAL_FLAGS } from "./lib/flag-catalog.js";
 import { EXIT, exitCodeHelp } from "./lib/exit-codes.js";
 import { recordUsage, operationOf } from "./lib/usage.js";
@@ -37,7 +37,6 @@ import * as close from "./commands/close.js";
 import * as review from "./commands/review.js";
 import * as watch from "./commands/watch.js";
 import * as why from "./commands/why.js";
-import * as constitution from "./commands/constitution.js";
 import * as prime from "./commands/prime.js";
 import * as handoff from "./commands/handoff.js";
 import * as show from "./commands/show.js";
@@ -54,15 +53,14 @@ const COMMANDS = {
   init, spec, change, decision, validate, hooks, analyze, clarify,
   templates, skill, index: indexCmd, next, metrics, context, search,
   intake, work, coverage, verify, contract, trace,
-  status, close, review, watch, why, constitution,
+  status, close, review, watch, why,
   prime, handoff, show, doctor, report, completion,
   intent, upgrade, adapter, triage, ci,
 };
 
 const TOP_HELP = `
-Usage: doctrina <command> [options]
+Usage: doctrina <command> [options]      (\`doctrina <command> --help\` for its flags)
 
-Commands:
 ${surfaceHelp()}
 
 Global flags:
@@ -112,6 +110,17 @@ async function main(argv) {
 
   const commandName = positional[0];
   const command = COMMANDS[commandName];
+  const removed = removalFor(positional);
+  if (removed) {
+    const name = removed === removalFor([commandName]) ? commandName : positional.slice(0, 2).join(" ");
+    console.error(c.red("error:") + ` \`doctrina ${name}\` was removed in ${removed.since}`);
+    console.error(c.gray("hint: ") + `use \`${removed.use}\` — it prints what the removed command printed`);
+    if (wantsJson(flags)) {
+      emitJson(operationName(positional), { stderr: [`error: \`doctrina ${name}\` was removed in ${removed.since}`, `hint: use \`${removed.use}\``] },
+        { ok: false, exitCode: EXIT.USAGE, args: positional.slice(1) });
+    }
+    return EXIT.USAGE;
+  }
   if (!command) {
     console.error(c.red("error:") + ` unknown command "${commandName}"`);
     const guess = suggest(commandName, Object.keys(COMMANDS));
@@ -265,5 +274,24 @@ main(process.argv.slice(2)).then((code) => {
     code,
     new Set(OPERATIONS.map((o) => o[0])),
   );
-  process.exit(code ?? 0);
+  // SET THE CODE; DO NOT CALL process.exit().
+  //
+  // When stdout is a PIPE — every `doctrina ... | less`, every agent reading
+  // this CLI, every `spawnSync` in the suite — Node may not have handed the
+  // bytes to the OS yet when this callback runs. `process.exit()` tears the
+  // process down immediately and whatever is still buffered is simply lost.
+  // Setting `exitCode` lets Node exit on its own once the work is done, and
+  // flushing stdout is part of that work.
+  //
+  // This is not theoretical. Four tests failed on macOS with Node 20.12 and
+  // on no other leg of the matrix, all of them `--concat` runs looking for
+  // content near the END of a long output. The decisive one printed exactly
+  // one section: `product.md` was on disk and in the pack listing, and the
+  // concat output stopped before reaching it. Pipe buffer sizes differ per
+  // platform, which is precisely why a truncation bug picks one and hides on
+  // the others.
+  //
+  // `--concat` even carries the comment "Keep the pack pipeable". Losing the
+  // tail of a pipe is the one way to break that promise.
+  process.exitCode = code ?? 0;
 });

package/src/lib/actions.js

@@ -155,6 +155,34 @@ export function computeActions(projectRoot, gates = {}) {
     }));
   }
 
+  // Index drift comes right after the intake (change 0193). It used to be
+  // surfaced LAST as "silent rot" — but `validate` reports it as an error,
+  // the close's index-drift step blocks on it, the fix is one runnable
+  // command, and the actions below read the very index that drifted. Ranked
+  // fifth, under advisory nudges, it told the agent to polish product.md
+  // before running the one command that unblocked everything.
+  try {
+    const current = idx.load(projectRoot);
+    if (!indexesMatch(deriveIndex(projectRoot, current), current)) {
+      actions.push(action({
+        id: "index-drift",
+        command: "index rebuild",
+        gate: "index",
+        runnable: true,
+        why: "index.json has drifted from the tree",
+      }));
+    }
+  } catch {
+    actions.push(action({
+      id: "index-unreadable",
+      command: "index rebuild",
+      gate: "index",
+      runnable: true,
+      why: "index.json is missing or unreadable",
+    }));
+  }
+
+
   // Open changes drive the loop: finish what is started before opening more.
   const changesDir = path.join(projectRoot, ".doctrina", "changes");
   if (isDir(changesDir)) {
@@ -171,9 +199,13 @@ export function computeActions(projectRoot, gates = {}) {
       }
       const status = listHeader(read(proposalPath), "Status") ?? "proposed";
       if (status === "applied") {
+        // The close, not the archive (change 0201). 0.17 retired the
+        // hand-driven tail — `close` skips the apply it already did and
+        // still runs verify, coverage and the docs gate — but this line kept
+        // teaching `change archive`, the one path past every one of them.
         actions.push(action({
           id: "change-archive-pending",
-          command: "change archive",
+          command: "close",
           args: [id],
           gate: "archive",
           runnable: true,
@@ -200,22 +232,22 @@ export function computeActions(projectRoot, gates = {}) {
       if (deltas.length > 0) {
         actions.push(action({
           id: "change-apply-ready",
-          command: "analyze",
+          command: "change check",
           args: [id],
           gate: "structure",
           runnable: true,
           why: `tasks done, ${deltas.length} delta${deltas.length === 1 ? "" : "s"} ready`,
-          text: `doctrina analyze ${id}, then doctrina change apply ${id} — ` +
+          text: `doctrina change check ${id}, then doctrina close ${id} — ` +
             `tasks done, ${deltas.length} delta${deltas.length === 1 ? "" : "s"} ready`,
         }));
       } else {
         actions.push(action({
           id: "change-deltas-missing",
-          command: "change apply",
+          command: "close",
           args: [id],
-          why: `add spec deltas under .doctrina/changes/${id}/specs/, or apply as metadata-only`,
+          why: `add spec deltas under .doctrina/changes/${id}/specs/, or close it as metadata-only`,
           text: `add spec deltas under .doctrina/changes/${id}/specs/, ` +
-            `or apply as metadata-only: doctrina change apply ${id}`,
+            `or close it as metadata-only: doctrina close ${id}`,
         }));
       }
     }
@@ -377,28 +409,6 @@ export function computeActions(projectRoot, gates = {}) {
     }));
   }
 
-  // Index drift is silent rot; surface it last.
-  try {
-    const current = idx.load(projectRoot);
-    if (!indexesMatch(deriveIndex(projectRoot, current), current)) {
-      actions.push(action({
-        id: "index-drift",
-        command: "index rebuild",
-        gate: "index",
-        runnable: true,
-        why: "index.json has drifted from the tree",
-      }));
-    }
-  } catch {
-    actions.push(action({
-      id: "index-unreadable",
-      command: "index rebuild",
-      gate: "index",
-      runnable: true,
-      why: "index.json is missing or unreadable",
-    }));
-  }
-
   return actions;
 }