doctrina-cli 0.12.0 → 0.14.0

package/src/commands/upgrade.js

@@ -1,3 +1,4 @@
+// @ts-check
 import path from "node:path";
 import process from "node:process";
 import { exists } from "../lib/fs-ops.js";
@@ -7,6 +8,7 @@ import { cliVersion } from "../lib/version.js";
 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 * as templates from "./templates.js";
 import * as validate from "./validate.js";
 
@@ -20,10 +22,15 @@ import * as validate from "./validate.js";
 // step. Preview by default; --write applies. Never rewrites user content
 // (the same additive-only bound as `templates update`).
 
+// 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", "write"], string: [] };
+
 export async function run(_positional, flags) {
   const projectRoot = process.cwd();
   if (!exists(path.join(projectRoot, ".doctrina"))) {
-    throw new Error("not a Doctrina project (no .doctrina/ in cwd). Run `doctrina init` first.");
+    throw notADoctrinaProject();
   }
   const writeMode = flagBool(flags, "write", false);
   const running = cliVersion();
@@ -82,10 +89,12 @@ export async function run(_positional, flags) {
     }
   }
 
-  // 4. Full structural check — surfaces what an automatic, additive upgrade
-  //    cannot fix: an AGENTS.md documenting a stale command surface, new
-  //    validate checks the old scaffold fails, and so on. --fix under --write
-  //    so the mechanical part self-heals.
+  // 4. Full structural check — surfaces what the upgrade cannot fix by
+  //    itself (new validate checks the old scaffold fails, hand-authored
+  //    drift). The command surface in AGENTS.md is NOT in this bucket any
+  //    more: step 1 regenerates the doctrina:surface block from the
+  //    installed catalog (ADR 0015). --fix under --write so the mechanical
+  //    part self-heals.
   console.log("");
   console.log(c.gray("──── 3/3 validate" + (writeMode ? " --fix" : "")));
   const vFlags = writeMode ? new Map([["fix", true]]) : new Map();
@@ -102,7 +111,7 @@ export async function run(_positional, flags) {
   }
   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("If AGENTS.md lists the command surface, refresh that section so agents see the new commands."));
+    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."));
   } else {
     console.log(c.yellow("upgraded with findings") + " — resolve the validate errors above (they predate or exceed what an additive upgrade can fix).");
   }
@@ -116,14 +125,16 @@ 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   — append missing recommended sections to AGENTS.md
-                          / product.md and missing index.json fields
-                          (additive-only; never rewrites your content)
+  1. templates update   — 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
+                          append missing recommended sections / index.json
+                          fields (additive-only outside the block)
   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 additive upgrade cannot fix
-                          (e.g. an AGENTS.md documenting a stale command
-                          surface — refresh it so agents see new commands)
+  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.
 `;

package/src/commands/validate.js

@@ -1,13 +1,17 @@
+// @ts-check
 import path from "node:path";
 import process from "node:process";
 import { readdirSync } from "node:fs";
-import { exists, isDir, isFile, lineCount, read, relPath, walk } from "../lib/fs-ops.js";
+import { exists, isDir, isFile, lineCount, read, relPath, walk , write} from "../lib/fs-ops.js";
 import * as idx from "../lib/index-json.js";
 import { SCHEMA_VERSION } from "../lib/index-json.js";
 import { cliVersion } from "../lib/version.js";
 import { today } from "../lib/dates.js";
 import { flagBool } from "../lib/args.js";
 import { c } from "../lib/colors.js";
+import { kindFromPath, nonConformingHeaders, repairHeaders } from "../lib/doc-model.js";
+import { emitJson } from "../lib/json-out.js";
+import { notADoctrinaProject } from "../lib/exit-codes.js";
 import { parseFrontmatter } from "./skill.js";
 import { checkEars, isEarsSpec } from "../lib/ears.js";
 import { specHeader, listHeader, deriveIndex, indexesMatch, stableStringify } from "../lib/scan.js";
@@ -19,8 +23,21 @@ import { parseAcceptanceCriteria, isVerified } from "../lib/criteria.js";
 // `doctrina --help` and is never nagged about omissions.
 const CATALOG_THRESHOLD = 8;
 
+// 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).
+// This command builds its own JSON payload; the entrypoint must not
+// wrap it in the generic envelope.
+export const jsonNative = true;
+
+export const flags = { boolean: ["fix", "json"], string: [] };
+
 export async function run(_positional, flags) {
   const projectRoot = process.cwd();
+  // Outside a Doctrina project this is a PRECONDITION, not a pile of
+  // gate failures about missing files: the remedy is `doctrina init`,
+  // not editing artifacts that do not exist yet (C7).
+  if (!isDir(path.join(projectRoot, ".doctrina"))) throw notADoctrinaProject();
   const errors = [];
   const warnings = [];
 
@@ -87,6 +104,45 @@ export async function run(_positional, flags) {
   const productMd = path.join(projectRoot, ".doctrina", "product.md");
   if (!isFile(productMd)) errors.push(".doctrina/product.md missing");
 
+  // Header repair (M3). One grammar means a non-canonical header can be
+  // REWRITTEN, not just reported: `- **Status**: x` becomes
+  // `- **Status:** x`, and a spec written with list-style headers is
+  // normalised to the bare-bold form its kind uses. Content is never
+  // touched — only the header's own punctuation and style.
+  const doFix = flagBool(flags, "fix", false);
+  {
+    const artifacts = [];
+    const dot = path.join(projectRoot, ".doctrina");
+    for (const f of walk(dot)) {
+      if (!f.endsWith(".md")) continue;
+      const rel = relPath(projectRoot, f).replace(/\\/g, "/");
+      if (rel.includes("/changes/archive/")) continue; // history is immutable
+      artifacts.push({ file: f, rel, kind: kindFromPath(rel) });
+    }
+    let repairedFiles = 0;
+    for (const a of artifacts) {
+      const text = read(a.file);
+      const bad = nonConformingHeaders(text, a.kind);
+      if (bad.length === 0) continue;
+      if (doFix) {
+        const { text: fixed, repaired } = repairHeaders(text, a.kind);
+        if (repaired > 0 && fixed !== text) {
+          write(a.file, fixed, { force: true });
+          repairedFiles += 1;
+        }
+      } else {
+        for (const h of bad) {
+          warnings.push(
+            `${a.rel}:${h.line} header "${h.name}" is ${h.wrongStyle ? `in ${h.style} style but a ${a.kind} uses ${h.expectedStyle} style` : "not in canonical form"} — run \`doctrina validate --fix\``,
+          );
+        }
+      }
+    }
+    if (doFix && repairedFiles > 0) {
+      console.log(c.green("fixed") + ` normalised headers in ${repairedFiles} artifact${repairedFiles === 1 ? "" : "s"}`);
+    }
+  }
+
   // 3. index.json
   let index = null;
   try {
@@ -254,7 +310,12 @@ export async function run(_positional, flags) {
     }
   }
 
-  // 7. Every open change has a proposal
+  // 7. Every open change has a proposal, and its delta files carry a
+  //    well-formed **Operation:** header. The delta used to be the one
+  //    100% hand-authored file with no early check: a missing header passed
+  //    silently at creation and exploded days later in the closing analyze
+  //    (operator review 2026-07-19 §3.2). Warning-level — the change is
+  //    still a draft — but now every `validate` run names it.
   const changesDir = path.join(projectRoot, ".doctrina", "changes");
   if (isDir(changesDir)) {
     const { readdirSync } = await import("node:fs");
@@ -267,6 +328,35 @@ export async function run(_positional, flags) {
             `(every dir under .doctrina/changes/ needs a proposal.md — that exact filename)`,
         );
       }
+      // A change whose tasks are still the scaffold placeholders was opened
+      // but never planned — the agent is (or will be) implementing with no
+      // recorded plan. Early, every-run signal; analyze/close hard-fail it.
+      const tasksPath = path.join(changesDir, entry, "tasks.md");
+      if (isFile(tasksPath)) {
+        const ph = (read(tasksPath).match(/^\s*-\s*\[[ xX]\]\s*$/gm) ?? []).length;
+        if (ph > 0) {
+          warnings.push(
+            `open change "${entry}" tasks.md still carries ${ph} scaffold placeholder task${ph === 1 ? "" : "s"} — ` +
+              `the change was opened but never planned (replace them with real tasks; analyze/close refuse them)`,
+          );
+        }
+      }
+      for (const deltaPath of walk(path.join(changesDir, entry, "specs"))) {
+        if (!deltaPath.endsWith("delta.md")) continue;
+        const text = read(deltaPath);
+        const m = text.match(/^\*\*Operation:\*\*\s*(\S+)/m);
+        if (!m) {
+          warnings.push(
+            `${relPath(projectRoot, deltaPath)} has no **Operation:** header — ` +
+              `analyze/apply will refuse it at close time (add "**Operation:** ADDED|MODIFIED|REMOVED")`,
+          );
+        } else if (!["ADDED", "MODIFIED", "REMOVED"].includes(m[1])) {
+          warnings.push(
+            `${relPath(projectRoot, deltaPath)} Operation "${m[1]}" is not ADDED|MODIFIED|REMOVED — ` +
+              `analyze/apply will refuse it at close time`,
+          );
+        }
+      }
     }
   }
 
@@ -540,7 +630,7 @@ export async function run(_positional, flags) {
 
   // Output
   if (flagBool(flags, "json", false)) {
-    console.log(JSON.stringify({ ok: errors.length === 0, errors, warnings }, null, 2));
+    emitJson("validate", { ok: errors.length === 0, errors, warnings });
     return errors.length === 0 ? 0 : 1;
   }
   for (const w of warnings) console.log(c.yellow("warn:  ") + w);

package/src/commands/verify.js

@@ -1,3 +1,4 @@
+// @ts-check
 import path from "node:path";
 import process from "node:process";
 import { readdirSync } from "node:fs";
@@ -6,6 +7,7 @@ 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 { EXIT, notADoctrinaProject } from "../lib/exit-codes.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
@@ -29,10 +31,15 @@ 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 async function run(_positional, flags) {
   const projectRoot = process.cwd();
   if (!exists(path.join(projectRoot, ".doctrina"))) {
-    throw new Error("not a Doctrina project (no .doctrina/ in cwd). Run `doctrina init` first.");
+    throw notADoctrinaProject();
   }
 
   // --clean is the reproducibility lint (review G4): `verify` runs the
@@ -66,7 +73,10 @@ export async function run(_positional, flags) {
     // the false confidence this command exists to prevent. Fail loudly.
     console.error(c.red("error:") + ` no ${CONFIG_REL} — nothing to verify`);
     console.error(c.gray("hint: ") + "scaffold one with `doctrina verify --init`, then declare your typecheck/test/build commands");
-    return 1;
+    // PRECONDITION, not a gate failure: the work may be perfect; this
+    // project has simply never declared a build gate. An agent reading
+    // exit 1 would iterate on the code forever (C7).
+    return EXIT.PRECONDITION;
   }
 
   let config;

package/src/commands/watch.js

@@ -1,9 +1,11 @@
+// @ts-check
 import path from "node:path";
 import process from "node:process";
 import { watch as fsWatch } from "node:fs";
 import { exists } from "../lib/fs-ops.js";
 import { flagBool } from "../lib/args.js";
 import { c } from "../lib/colors.js";
+import { notADoctrinaProject } from "../lib/exit-codes.js";
 import * as validate from "./validate.js";
 import * as next from "./next.js";
 
@@ -15,11 +17,16 @@ import * as next from "./next.js";
 // makes) so it never loops on its own output. `--once` runs a single pass and
 // exits — the testable, scriptable form.
 
+// 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", "once"], string: [] };
+
 export async function run(_positional, flags) {
   const projectRoot = process.cwd();
   const dot = path.join(projectRoot, ".doctrina");
   if (!exists(dot)) {
-    throw new Error("not a Doctrina project (no .doctrina/ in cwd). Run `doctrina init` first.");
+    throw notADoctrinaProject();
   }
 
   if (flagBool(flags, "once", false)) {

package/src/commands/why.js

@@ -1,3 +1,5 @@
+// @ts-check
+import { getSectionParagraph } from "../lib/doc-model.js";
 import path from "node:path";
 import process from "node:process";
 import { readdirSync } from "node:fs";
@@ -7,6 +9,7 @@ import { parseAcceptanceCriteria, isVerified } from "../lib/criteria.js";
 import * as idx from "../lib/index-json.js";
 import { c } from "../lib/colors.js";
 import { suggest } from "../lib/suggest.js";
+import { notADoctrinaProject } from "../lib/exit-codes.js";
 
 // Provenance explainer (review 2026-06-27 passive-user feature #5): answer
 // "why does this capability exist / why was it built this way?" by assembling
@@ -16,11 +19,16 @@ import { suggest } from "../lib/suggest.js";
 // asks; the tool answers from the artifacts, instead of grepping by hand.
 // Read-only. Builds on the Realizes:/trace provenance (ADR 0006/0011).
 
+// 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 cap = positional[0];
   const projectRoot = process.cwd();
   if (!exists(path.join(projectRoot, ".doctrina"))) {
-    throw new Error("not a Doctrina project (no .doctrina/ in cwd). Run `doctrina init` first.");
+    throw notADoctrinaProject();
   }
   const specsDir = path.join(projectRoot, ".doctrina", "specs");
   const known = isDir(specsDir) ? readdirSync(specsDir).filter((e) => isFile(path.join(specsDir, e, "spec.md"))) : [];
@@ -72,7 +80,7 @@ export async function run(positional, _flags) {
   const status = specHeader(text, "Status") ?? "—";
   const impl = specHeader(text, "Implementation") ?? "—";
   console.log(`    ${c.gray("status:")} ${status}   ${c.gray("implementation:")} ${impl}`);
-  const purpose = sectionParagraph(text, "Purpose");
+  const purpose = getSectionParagraph(text, "Purpose");
   if (purpose) console.log("    " + purpose.replace(/\s+/g, " ").trim());
 
   // Dependency graph, both directions (the machine-readable **Depends on:**
@@ -229,28 +237,6 @@ function productAnchors(projectRoot) {
   return out;
 }
 
-// First non-comment paragraph under a "## <name>" heading.
-function sectionParagraph(text, name) {
-  const lines = text.split(/\r?\n/);
-  let inSection = false;
-  const buf = [];
-  for (const line of lines) {
-    if (/^##\s+/.test(line)) {
-      if (inSection) break;
-      if (new RegExp(`^##\\s+${name}\\b`, "i").test(line)) inSection = true;
-      continue;
-    }
-    if (!inSection) continue;
-    if (/^\s*<!--/.test(line) || /-->/.test(line)) continue;
-    if (line.trim() === "") {
-      if (buf.length) break;
-      continue;
-    }
-    buf.push(line.trim());
-  }
-  return buf.join(" ");
-}
-
 // Accepted ADRs whose body names the capability (word-ish boundary).
 function decisionsMentioning(projectRoot, cap) {
   const adrDir = path.join(projectRoot, ".doctrina", "decisions");

package/src/commands/work.js

@@ -1,12 +1,15 @@
+// @ts-check
 import path from "node:path";
 import process from "node:process";
 import { readdirSync } from "node:fs";
 import { spawnSync } from "node:child_process";
-import { exists, isDir, isFile, read, relPath, write } from "../lib/fs-ops.js";
+import { exists, isDir, isFile, mkdirp, read, relPath, write } from "../lib/fs-ops.js";
 import { flagString, flagBool } from "../lib/args.js";
 import * as idx from "../lib/index-json.js";
 import { c } from "../lib/colors.js";
 import { assessBrief } from "../lib/clarity.js";
+import { locateTemplatesDir, substitute } from "../lib/templates.js";
+import { notADoctrinaProject } from "../lib/exit-codes.js";
 import { changeNew } from "./change.js";
 
 // `work` is the second half of the no-ceremony path (ADR 0005): a brief
@@ -17,11 +20,16 @@ import { changeNew } from "./change.js";
 // unproven verification). The CLI's own language processing stops at
 // slugging and term counting; everything semantic is the agent's job.
 
+// 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 async function run(positional, flags) {
   const prompt = positional.join(" ").trim();
   const projectRoot = process.cwd();
   if (!exists(path.join(projectRoot, ".doctrina"))) {
-    throw new Error("not a Doctrina project (no .doctrina/ in cwd). Run `doctrina init` first.");
+    throw notADoctrinaProject();
   }
 
   // --resume <id>: reprint the playbook for an existing open change rather than
@@ -106,6 +114,26 @@ export async function run(positional, flags) {
     if (updated !== txt) write(proposalPath, updated, { force: true });
   }
 
+  // A pinned capability is an explicit statement of intent, so the delta —
+  // historically the only 100% hand-authored file in the flow, and the one
+  // whose missing **Operation:** header exploded days later at analyze
+  // (operator review 2026-07-19 §3.2) — is scaffolded from the template with
+  // the Operation prefilled: MODIFIED when the spec exists, ADDED when it
+  // does not. Never scaffolded from a ranked GUESS (that would put a wrong
+  // capability's delta in the change); only from --capability.
+  if (pinned && !chore) {
+    const deltaPath = path.join(projectRoot, ".doctrina", "changes", id, "specs", pinned, "delta.md");
+    if (!exists(deltaPath)) {
+      const tpl = read(path.join(locateTemplatesDir(), "change", "spec-delta.md.template"));
+      const op = isFile(path.join(projectRoot, ".doctrina", "specs", pinned, "spec.md")) ? "MODIFIED" : "ADDED";
+      const body = substitute(tpl, { CAPABILITY: pinned })
+        .replace(/^\*\*Operation:\*\*.*$/m, `**Operation:** ${op}`);
+      mkdirp(path.dirname(deltaPath));
+      write(deltaPath, body);
+      console.log(c.green("created") + ` ${relPath(projectRoot, deltaPath)}` + c.gray(` (Operation: ${op} prefilled)`));
+    }
+  }
+
   // Capability hint: term overlap for a prompt, changed-file overlap for a diff
   // (review F10 — rank by what the working tree touched, not just prompt words).
   const allChanged = fromDiff ? files : changedFiles(projectRoot);
@@ -114,6 +142,16 @@ export async function run(positional, flags) {
   const capability = pinned ?? matches[0]?.id ?? null;
   const clarity = assessBrief(effPrompt, { kind: "prompt" });
 
+  // --quiet: registering backlog, not starting now (operator review §3.7 — 19
+  // works printed 19 identical 50-line playbooks). One line per change; the
+  // playbook is reprintable on demand with --resume.
+  if (flagBool(flags, "quiet", false)) {
+    console.log("");
+    console.log(c.green("opened ") + c.cyan(id) +
+      c.gray(` — playbook on demand: doctrina work --resume ${id}`));
+    return 0;
+  }
+
   console.log("");
   if (chore) {
     printChorePlaybook(projectRoot, { id, prompt: effPrompt });
@@ -339,6 +377,8 @@ function printChorePlaybook(projectRoot, { id, prompt }) {
   console.log("");
   console.log(`1. Replace the placeholder tasks in .doctrina/changes/${id}/tasks.md`);
   console.log("   with small, checkable steps; implement them, checking each box.");
+  console.log(c.gray("   (Do it before implementing — analyze/close refuse leftover scaffold"));
+  console.log(c.gray("   placeholders, and `change tick` will not tick an empty box.)"));
   console.log("2. Prove it (archive refuses unchecked boxes):");
   console.log(`       ${c.cyan("doctrina verify")}     — the project's typecheck/test/build gate`);
   console.log(`       ${c.cyan("doctrina verify --clean")} — clean-checkout reproducibility lint`);
@@ -406,8 +446,14 @@ function printPlaybook(projectRoot, { id, prompt, pinned, matches, capability, c
   console.log(c.gray("   \"**Realizes:** SC1\" header (or \"n/a — <why>\"). `doctrina validate` warns"));
   console.log(c.gray("   on an active spec with no Realizes; `doctrina trace` reports the link."));
   console.log("");
-  console.log("3. Write one delta per affected capability at");
-  console.log(`   .doctrina/changes/${id}/specs/<capability>/delta.md:`);
+  if (pinned) {
+    console.log(`3. A delta is already scaffolded (Operation prefilled) at`);
+    console.log(`   .doctrina/changes/${id}/specs/${pinned}/delta.md — fill its body.`);
+    console.log("   Add one more delta per additional affected capability:");
+  } else {
+    console.log("3. Write one delta per affected capability at");
+    console.log(`   .doctrina/changes/${id}/specs/<capability>/delta.md:`);
+  }
   console.log(c.gray("       # Spec Delta — capability: <capability>"));
   console.log(c.gray("       **Operation:** ADDED | MODIFIED | REMOVED"));
   console.log(c.gray("       **Target spec on apply:** `.doctrina/specs/<capability>/spec.md`"));
@@ -423,8 +469,12 @@ function printPlaybook(projectRoot, { id, prompt, pinned, matches, capability, c
   console.log(c.gray("       bump-version minor"));
   console.log(c.gray("       set-criterion 1: verified"));
   console.log(c.gray("       append-criterion [unverified] new signal — verified by `test/y.test.js`"));
+  console.log(c.gray("       append-requirement event: When <trigger>, the system shall <action>."));
+  console.log(c.gray("       replace-requirement ubiquitous 2: The system shall <action>."));
   console.log(c.gray("       ```"));
-  console.log(c.gray("   Only prose rewrites stay a by-hand merge."));
+  console.log(c.gray("   append-* ops number/position at APPLY time, so concurrent changes"));
+  console.log(c.gray("   appending to the same spec never collide. Only free-prose rewrites"));
+  console.log(c.gray("   (Purpose, Maturity, ...) stay a by-hand merge."));
   if (fromDiff) {
     console.log(c.gray("   --from-diff: the code already exists — describe its CURRENT behaviour, and"));
     console.log(c.gray("   mark each criterion [unverified] until a test proves it (don't assume the"));
@@ -432,7 +482,10 @@ function printPlaybook(projectRoot, { id, prompt, pinned, matches, capability, c
   }
   console.log("");
   console.log(`4. Replace the placeholder tasks in .doctrina/changes/${id}/tasks.md`);
-  console.log("   with small, checkable implementation tasks (a few hours each, max).");
+  console.log("   with small, checkable implementation tasks (a few hours each, max),");
+  console.log("   and record the change's What/Scope in its proposal.md. Do this BEFORE");
+  console.log("   implementing — analyze and close refuse a change whose scaffold");
+  console.log("   placeholders were never replaced, and `change tick` will not tick them.");
   console.log("");
   console.log("5. Implement task by task, checking each box as it lands. Advance the");
   console.log("   spec's Implementation: planned → partial → implemented as code lands.");
@@ -442,6 +495,10 @@ function printPlaybook(projectRoot, { id, prompt, pinned, matches, capability, c
   console.log("   (an architecture, a boundary, a trade-off a future session must");
   console.log(`   not relitigate)? If yes: ${c.cyan("doctrina decision new \"<title>\"")} now,`);
   console.log("   before closing — the definition of done requires it recorded.");
+  console.log(c.gray("   (close re-checks this: it warns when the change touches capabilities"));
+  console.log(c.gray("   cited by an accepted ADR — amend via decision supersede, not silence.)"));
+  console.log("   Touching an integration surface (ports, env vars, public endpoints)?");
+  console.log(`   Own it in a contract: ${c.cyan("doctrina contract new <id>")} · ${c.cyan("doctrina contract check")}.`);
   console.log("");
   console.log(`7. Close in one attested pass (preferred — runs every gate and stops`);
   console.log("   at the first failure with the exact rerun command):");
@@ -476,7 +533,12 @@ named after that word (review G1). Use --resume to do so directly.
 Options:
   --title "<short>"    Short display title: drives the slug and the proposal
                        H1; the full prompt still lands under ## Why
-  --capability <cap>   Pin the capability instead of ranking matches
+  --capability <cap>   Pin the capability instead of ranking matches. Also
+                       scaffolds specs/<cap>/delta.md in the change with the
+                       Operation header prefilled (MODIFIED when the spec
+                       exists, ADDED when it does not)
+  --quiet              Register the change and print one line — no playbook
+                       (backlog entry; reprint later with --resume <id>)
   --id <id>            Override the derived change id
   --resume <id>        Reprint the playbook for an open change; create nothing
   --from-diff          Backfill: scaffold from the working-tree changes (no

package/src/index.js

@@ -1,10 +1,15 @@
 #!/usr/bin/env node
+// @ts-check
 import process from "node:process";
 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 } from "./lib/commands.js";
+import { surfaceHelp, OPERATIONS } from "./lib/commands.js";
+import { GLOBAL_FLAGS } from "./lib/flag-catalog.js";
+import { EXIT, exitCodeHelp } from "./lib/exit-codes.js";
+import { recordUsage } from "./lib/usage.js";
+import { wantsJson, emitJson, captureOutput, stripAnsi } from "./lib/json-out.js";
 
 import * as init from "./commands/init.js";
 import * as spec from "./commands/spec.js";
@@ -41,6 +46,7 @@ import * as report from "./commands/report.js";
 import * as completion from "./commands/completion.js";
 import * as intent from "./commands/intent.js";
 import * as upgrade from "./commands/upgrade.js";
+import * as adapter from "./commands/adapter.js";
 
 const COMMANDS = {
   init, spec, change, decision, validate, hooks, analyze, clarify,
@@ -48,7 +54,7 @@ const COMMANDS = {
   intake, work, coverage, verify, contract, trace,
   status, close, review, watch, why, constitution,
   prime, handoff, show, doctor, report, completion,
-  intent, upgrade,
+  intent, upgrade, adapter,
 };
 
 const TOP_HELP = `
@@ -60,6 +66,10 @@ ${surfaceHelp()}
 Global flags:
   --help, -h           Show this message (or per-command help if after a command)
   --version, -v        Print the version
+  --debug              On an unexpected error, also print the stack trace
+
+Exit codes (a contract — an agent reads these to decide what to do next):
+${exitCodeHelp()}
 `;
 
 async function main(argv) {
@@ -69,8 +79,23 @@ async function main(argv) {
   // version and exit, looking exactly like the spec's version had been set
   // (0.11.0 field-review papercut). `-v` stays global either way.
   const versionOnly = argv.every((t) => t === "--version" || t === "-v") && argv.length > 0;
+
+  // Two passes. The first resolves only the command name, using the global
+  // flags; the second re-parses with THAT command's declared flags merged in.
+  //
+  // One global boolean list used to serve every command, and six flags read
+  // via flagBool were missing from it. An undeclared flag whose next token
+  // does not start with "-" swallows that token as its value, so
+  // `change new --chore ajuste-ci "Ajustar CI"` lost the id AND silently
+  // ignored the flag, reporting "requires a title" for a quoted title (C3).
+  // Declarations now live with the command, so a new command cannot
+  // reintroduce the gap by forgetting to edit this file.
+  const bootstrap = parseArgs(argv, { boolean: [...GLOBAL_FLAGS.boolean] });
+  const commandModule = COMMANDS[bootstrap.positional[0]];
+  const spec = commandModule?.flags;
   const { positional, flags } = parseArgs(argv, {
-    boolean: ["help", "h", "v", "force", "non-interactive", "check", "save", "bug", "write", "all", "concat", "archive", "strict", "list", "init", "fix", "once", "clean", "json"],
+    boolean: [...GLOBAL_FLAGS.boolean, ...(spec?.boolean ?? [])],
+    string: [...GLOBAL_FLAGS.string, ...(spec?.string ?? [])],
   });
 
   if (versionOnly || flags.get("v") === true) {
@@ -93,7 +118,7 @@ async function main(argv) {
     } else {
       console.error(c.gray("hint: ") + "try `doctrina --help` for the command surface");
     }
-    return 2;
+    return EXIT.USAGE;
   }
 
   if (flags.get("help") || flags.get("h")) {
@@ -102,14 +127,43 @@ async function main(argv) {
   }
 
   try {
+    // --json on a command that builds no payload of its own still answers in
+    // JSON: its output is captured into a versioned envelope beside `ok` and
+    // `exit_code`. Branch on those; the lines are for completeness (M7).
+    if (wantsJson(flags) && !command.jsonNative) {
+      const { code, stdout, stderr } = await captureOutput(
+        () => command.run(positional.slice(1), flags),
+      );
+      emitJson([commandName, ...positional.slice(1)].join(" "), {
+        stdout: stdout.map(stripAnsi),
+        stderr: stderr.map(stripAnsi),
+      }, { ok: code === EXIT.OK, exitCode: code });
+      return code;
+    }
     return await command.run(positional.slice(1), flags);
   } catch (err) {
     console.error(c.red("error:") + ` ${err.message}`);
+    if (err.remedy) {
+      console.error(c.gray("hint: ") + `run ${c.cyan(err.remedy)} first, then retry`);
+    }
     if (flags.get("debug") && err.stack) {
       console.error(c.gray(err.stack));
     }
-    return 1;
+    // A typed error carries its own class (precondition vs environment).
+    // An untyped throw is an unexpected failure of the work itself, which
+    // is the GATE class: something is wrong here, fix it and retry (C7).
+    return err.exitCode ?? EXIT.GATE;
   }
 }
 
-main(process.argv.slice(2)).then((code) => process.exit(code ?? 0));
+main(process.argv.slice(2)).then((code) => {
+  // Record which operation ran, if and only if the operator asked for it
+  // by setting DOCTRINA_USAGE_LOG (M8). Off by default, local file only,
+  // no arguments captured, and never fatal. See lib/usage.js.
+  recordUsage(
+    process.argv.slice(2).filter((a) => !a.startsWith("-")),
+    code,
+    new Set(OPERATIONS.map((o) => o[0])),
+  );
+  process.exit(code ?? 0);
+});