doctrina-cli 0.11.0 → 0.13.0

package/src/commands/validate.js

@@ -254,7 +254,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 +272,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`,
+          );
+        }
+      }
     }
   }
 
@@ -451,8 +485,15 @@ export async function run(_positional, flags) {
   if (index?.artifacts && isFile(ledgerPath)) {
     const ledgerIds = new Set();
     for (const line of read(ledgerPath).split(/\r?\n/)) {
-      const m = line.match(/^-\s+\d{4}-\d{2}-\d{2}\s+[—-]\s+(\S+)\s+[—-]\s+/);
-      if (m) ledgerIds.add(m[1]);
+      const m = line.match(/^-\s+\d{4}-\d{2}-\d{2}\s+[—-]\s+(\S+)\s+[—-]\s+(.*)$/);
+      if (!m) continue;
+      // An abandoned change is ledger-only BY DESIGN: `change abandon`
+      // records the discard in history but deletes the folder, so there is
+      // deliberately no archive entry to cross-check. Requiring one made
+      // every abandonment turn validate permanently red (found dogfooding
+      // change 0001-review-followups).
+      if (/^abandoned\b/i.test(m[2].trim())) continue;
+      ledgerIds.add(m[1]);
     }
     const archiveIds = new Set((index.artifacts.changes_archive ?? []).map((ch) => ch.id));
     for (const id of archiveIds) {
@@ -523,6 +564,14 @@ export async function run(_positional, flags) {
     }
   }
 
+  // Project rules — permanent, lintable constraints (.doctrina/rules.json;
+  // 0.11.0 field review item 12: "never reference company X" lived only in
+  // agent memory, and the remaining mentions sailed through every gate). Each
+  // rule is a forbid-regex over glob-scoped paths; a match is an ERROR with
+  // the rule's own message. Deterministic, zero-deps, and the instruction
+  // survives sessions because it is an artifact, not a memory.
+  for (const line of checkProjectRules(projectRoot)) errors.push(line);
+
   // Output
   if (flagBool(flags, "json", false)) {
     console.log(JSON.stringify({ ok: errors.length === 0, errors, warnings }, null, 2));
@@ -541,6 +590,106 @@ export async function run(_positional, flags) {
   return errors.length === 0 ? 0 : 1;
 }
 
+// Enforce .doctrina/rules.json — permanent project constraints as
+// forbid-regexes over glob-scoped paths:
+//   { "rules": [ { "id": "white-label", "forbid": "\\bAcmeCorp\\b",
+//                  "paths": ["src/**", ".doctrina/specs/**"],
+//                  "message": "white-label product; use a generic placeholder" } ] }
+// Returns error strings (one per offending file+rule, capped per rule so a
+// mass violation stays readable). Missing/invalid file → no rules (an
+// invalid JSON is reported once). Binary-ish and vendored dirs are skipped
+// by the same bounded walk validate already uses elsewhere.
+const RULES_SKIP_DIRS = new Set([
+  ".git", "node_modules", "vendor", "dist", "build", "out", "target",
+  ".venv", "venv", "__pycache__", ".next", "coverage",
+]);
+const RULES_MAX_HITS_PER_RULE = 10;
+
+function checkProjectRules(projectRoot) {
+  const rulesPath = path.join(projectRoot, ".doctrina", "rules.json");
+  if (!isFile(rulesPath)) return [];
+  let cfg;
+  try {
+    cfg = JSON.parse(read(rulesPath));
+  } catch (err) {
+    return [`.doctrina/rules.json is not valid JSON: ${err.message}`];
+  }
+  const rules = Array.isArray(cfg?.rules) ? cfg.rules : [];
+  const out = [];
+  const compiled = [];
+  for (const r of rules) {
+    if (!r || typeof r.forbid !== "string" || !r.forbid) {
+      out.push(`.doctrina/rules.json: rule "${r?.id ?? "?"}" needs a non-empty "forbid" regex`);
+      continue;
+    }
+    let re;
+    try {
+      re = new RegExp(r.forbid, "m");
+    } catch (err) {
+      out.push(`.doctrina/rules.json: rule "${r.id ?? r.forbid}" has an invalid regex: ${err.message}`);
+      continue;
+    }
+    const paths = Array.isArray(r.paths) && r.paths.length ? r.paths : ["**"];
+    compiled.push({ id: r.id ?? r.forbid, re, matchers: paths.map(globToRegExp), message: r.message ?? "", hits: 0 });
+  }
+  if (compiled.length === 0) return out;
+
+  // One bounded walk; each text file is read at most once.
+  const stack = [projectRoot];
+  while (stack.length) {
+    const dir = stack.pop();
+    let entries;
+    try {
+      entries = readdirSync(dir, { withFileTypes: true });
+    } catch {
+      continue;
+    }
+    for (const entry of entries) {
+      const full = path.join(dir, entry.name);
+      if (entry.isDirectory()) {
+        if (!RULES_SKIP_DIRS.has(entry.name)) stack.push(full);
+        continue;
+      }
+      const rel = relPath(projectRoot, full).replace(/\\/g, "/");
+      if (rel === ".doctrina/rules.json") continue; // the rule text itself always matches
+      const applicable = compiled.filter((cr) => cr.hits < RULES_MAX_HITS_PER_RULE && cr.matchers.some((m) => m.test(rel)));
+      if (applicable.length === 0) continue;
+      let text;
+      try {
+        text = read(full);
+      } catch {
+        continue;
+      }
+      for (const cr of applicable) {
+        const m = cr.re.exec(text);
+        if (m) {
+          cr.hits += 1;
+          const lineNo = text.slice(0, m.index).split("\n").length;
+          out.push(`rule "${cr.id}": ${rel}:${lineNo} matches forbidden pattern${cr.message ? ` — ${cr.message}` : ""}`);
+        }
+      }
+    }
+  }
+  for (const cr of compiled) {
+    if (cr.hits >= RULES_MAX_HITS_PER_RULE) {
+      out.push(`rule "${cr.id}": more matches suppressed after ${RULES_MAX_HITS_PER_RULE} files`);
+    }
+  }
+  return out;
+}
+
+// Minimal glob → RegExp: ** crosses directories, * stays within a segment.
+// Anchored to the whole repo-relative POSIX path.
+function globToRegExp(glob) {
+  const esc = String(glob).replace(/[.+^${}()|[\]\\]/g, "\\$&");
+  const body = esc
+    .replace(/\*\*\//g, "(?:.*/)?")
+    .replace(/\*\*/g, ".*")
+    .replace(/\*/g, "[^/]*")
+    .replace(/\?/g, "[^/]");
+  return new RegExp(`^${body}$`);
+}
+
 // Per-entry metadata drift between the on-disk index and the tree-derived
 // one, for entries present in BOTH. Presence drift (an artifact on disk but
 // not indexed, or indexed but missing) is left to the orphan warning and the

package/src/commands/why.js

@@ -2,7 +2,7 @@ import path from "node:path";
 import process from "node:process";
 import { readdirSync } from "node:fs";
 import { exists, isDir, isFile, read } from "../lib/fs-ops.js";
-import { specHeader, listHeader } from "../lib/scan.js";
+import { specHeader, listHeader, parseDependsOn } from "../lib/scan.js";
 import { parseAcceptanceCriteria, isVerified } from "../lib/criteria.js";
 import * as idx from "../lib/index-json.js";
 import { c } from "../lib/colors.js";
@@ -75,6 +75,16 @@ export async function run(positional, _flags) {
   const purpose = sectionParagraph(text, "Purpose");
   if (purpose) console.log("    " + purpose.replace(/\s+/g, " ").trim());
 
+  // Dependency graph, both directions (the machine-readable **Depends on:**
+  // header — specs used to cite each other only in prose, invisible here).
+  const deps = parseDependsOn(text);
+  const dependents = known
+    .filter((other) => other !== cap)
+    .filter((other) => parseDependsOn(read(path.join(specsDir, other, "spec.md"))).includes(cap))
+    .sort();
+  if (deps.length > 0) console.log(`    ${c.gray("depends on:")} ${deps.map((d) => c.cyan(d)).join(", ")}`);
+  if (dependents.length > 0) console.log(`    ${c.gray("depended on by:")} ${dependents.map((d) => c.cyan(d)).join(", ")}`);
+
   // 3. The proof (acceptance criteria with cited evidence). Read through the
   //    shared multi-line parser so the marks here agree with `doctrina
   //    coverage` — a criterion that cites its proof on a continuation line is

package/src/commands/work.js

@@ -2,11 +2,12 @@ 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 { changeNew } from "./change.js";
 
 // `work` is the second half of the no-ceremony path (ADR 0005): a brief
@@ -71,14 +72,18 @@ export async function run(positional, flags) {
   }
 
   const effPrompt = prompt || `backfill specs from ${files.length} changed file${files.length === 1 ? "" : "s"}`;
-  const slug = prompt ? slugify(prompt) : "backfill";
+  // --title separates the short display name from the full brief: the title
+  // drives the slug and the proposal H1; the whole prompt still lands, intact,
+  // under ## Why. Without it a long prompt used to become a 900-char H1.
+  const title = flagString(flags, "title") ?? effPrompt;
+  const slug = prompt || flags.has("title") ? slugify(title) : "backfill";
   const id = flagString(flags, "id") ?? `${nextChangeNumber(projectRoot)}-${slug}`;
   if (!/^[a-z0-9][a-z0-9-]*$/.test(id)) {
     console.error(c.red("error:") + ` invalid change id "${id}" (lowercase letters, digits, hyphens)`);
     return 2;
   }
 
-  const code = changeNew([id, effPrompt], flags);
+  const code = changeNew([id, title], flags);
   if (code !== 0) return code;
 
   // Record the prompt verbatim as the change's Why — the raw intent has
@@ -102,6 +107,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);
@@ -110,6 +135,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 });
@@ -228,6 +263,9 @@ function resumeChange(projectRoot, resumeId) {
 }
 
 // ASCII-folded kebab-case of the prompt ("Faça o login" -> "faca-o-login").
+// Over-long slugs are cut at a WORD boundary, not mid-token — a 900-char
+// prompt used to produce folder names ending in a half word ("...-scoped-c"),
+// which then leaks into every path, ledger line, and archive name.
 export function slugify(text) {
   let slug = text
     .normalize("NFD")
@@ -235,7 +273,11 @@ export function slugify(text) {
     .toLowerCase()
     .replace(/[^a-z0-9]+/g, "-")
     .replace(/^-+|-+$/g, "");
-  if (slug.length > 48) slug = slug.slice(0, 48).replace(/-+$/g, "");
+  if (slug.length > 48) {
+    const cut = slug.slice(0, 49); // one past the cap: a "-" here means 48 ends a word
+    const boundary = cut.lastIndexOf("-");
+    slug = (boundary > 0 ? cut.slice(0, boundary) : cut.slice(0, 48)).replace(/-+$/g, "");
+  }
   return slug.length > 0 ? slug : "task";
 }
 
@@ -292,7 +334,7 @@ export function rankCapabilities(projectRoot, prompt) {
 // file scores its capability when the file sits under a path segment named for
 // it, or when the spec cites the file as evidence. A deterministic overlap
 // hint for the agent — never a decision (ADR 0005).
-export function rankCapabilitiesByDiff(projectRoot, files) {
+export function rankCapabilitiesByDiff(projectRoot, files, { limit = 3 } = {}) {
   const specsDir = path.join(projectRoot, ".doctrina", "specs");
   if (!files || files.length === 0 || !isDir(specsDir)) return [];
   const norm = files.map((f) => f.replace(/\\/g, "/"));
@@ -310,7 +352,10 @@ export function rankCapabilitiesByDiff(projectRoot, files) {
     }
     if (score > 0) ranked.push({ id: cap, score, path: `.doctrina/specs/${cap}/spec.md` });
   }
-  return ranked.sort((a, b) => b.score - a.score || a.id.localeCompare(b.id)).slice(0, 3);
+  // `limit` keeps the work-playbook hint short (top 3); review passes
+  // Infinity — truncating there is how it missed 5 of 8 touched capabilities
+  // in the 0.11.0 field session.
+  return ranked.sort((a, b) => b.score - a.score || a.id.localeCompare(b.id)).slice(0, limit);
 }
 
 // A chore is a spec-less change (review F9): the playbook drops the spec-delta
@@ -325,6 +370,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`);
@@ -392,8 +439,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`"));
@@ -401,6 +454,20 @@ function printPlaybook(projectRoot, { id, prompt, pinned, matches, capability, c
   console.log(c.gray("       <EARS body. Keep the two axes honest (Status vs Implementation),"));
   console.log(c.gray("        keep aspiration under ## Maturity → Future, and cite the proof per"));
   console.log(c.gray("        criterion: \"1. [unverified] <signal> — verified by `path/to/test`\">"));
+  console.log(c.gray("   New capability? `spec new` then an ADDED delta with the FULL body — apply"));
+  console.log(c.gray("   replaces the untouched scaffold. Bookkeeping edits? MODIFIED with an ops"));
+  console.log(c.gray("   block, applied mechanically (all ops or none):"));
+  console.log(c.gray("       ```ops"));
+  console.log(c.gray("       set-header Implementation: verified — `src/x.js`"));
+  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("   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"));
@@ -408,25 +475,35 @@ 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.");
   console.log("   If the prompt is genuinely ambiguous, ask the user before assuming.");
   console.log("");
-  console.log(`6. ${c.cyan(`doctrina analyze ${id}`)} — fix every ✗ before applying.`);
-  console.log(`7. ${c.cyan(`doctrina change apply ${id}`)}   (MODIFIED with an ops block applies mechanically; prose merges by hand).`);
-  console.log("8. Prove it before declaring done (archive refuses unchecked boxes):");
-  console.log(`       ${c.cyan("doctrina verify")}     — the project's typecheck/test/build gate`);
-  console.log(`       ${c.cyan("doctrina coverage")}   — each acceptance criterion cites a real test`);
-  console.log(`       ${c.cyan("doctrina trace")}      — the capability traces to product intent`);
-  console.log("   Then check the proposal's ## Verification boxes and every task,");
+  console.log(`6. ADR checkpoint — does this change decide something structural`);
+  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):");
+  console.log(`       ${c.cyan(`doctrina close ${id}`)}`);
+  console.log(c.gray("   (equivalent, step by step: ") +
+    c.gray(`analyze → change apply → verify → coverage → trace → change archive → validate)`));
+  console.log("   Before it: check the proposal's ## Verification boxes and every task,");
   console.log("   closing steps included, and bump Implementation to verified.");
   console.log("");
-  console.log(`9. ${c.cyan(`doctrina change archive ${id}`)}`);
-  console.log(`10. ${c.cyan("doctrina validate")}, then ${c.cyan("doctrina next")} for the follow-up.`);
-  console.log(c.gray("    If this change taught a reusable lesson (a fix you'd hate to relearn,"));
-  console.log(c.gray("    a recurring convention), capture it: ") + c.cyan("doctrina skill new <slug>") + c.gray("."));
+  console.log(`8. ${c.cyan("doctrina next")} for the follow-up.`);
+  console.log(c.gray("   If this change taught a reusable lesson (a fix you'd hate to relearn,"));
+  console.log(c.gray("   a recurring convention), capture it: ") + c.cyan("doctrina skill new <slug>") + c.gray("."));
 }
 
 export const help = `
@@ -447,7 +524,14 @@ already open, work suggests resuming it instead of opening a junk change
 named after that word (review G1). Use --resume to do so directly.
 
 Options:
-  --capability <cap>   Pin the capability instead of ranking matches
+  --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. 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

@@ -39,6 +39,8 @@ import * as show from "./commands/show.js";
 import * as doctor from "./commands/doctor.js";
 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";
 
 const COMMANDS = {
   init, spec, change, decision, validate, hooks, analyze, clarify,
@@ -46,6 +48,7 @@ const COMMANDS = {
   intake, work, coverage, verify, contract, trace,
   status, close, review, watch, why, constitution,
   prime, handoff, show, doctor, report, completion,
+  intent, upgrade,
 };
 
 const TOP_HELP = `
@@ -60,11 +63,17 @@ Global flags:
 `;
 
 async function main(argv) {
+  // `--version` is only "print the CLI version" when NO command is given.
+  // With a command it is that command's flag to consume — the old global
+  // intercept made `doctrina spec set x --version 0.10.0` print the CLI
+  // 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;
   const { positional, flags } = parseArgs(argv, {
-    boolean: ["help", "h", "version", "v", "force", "non-interactive", "check", "save", "bug", "write", "all", "concat", "archive", "strict", "list", "init", "fix", "once", "clean", "json"],
+    boolean: ["help", "h", "v", "force", "non-interactive", "check", "save", "bug", "write", "all", "concat", "archive", "strict", "list", "init", "fix", "once", "clean", "json"],
   });
 
-  if (flags.get("version") || flags.get("v")) {
+  if (versionOnly || flags.get("v") === true) {
     console.log(cliVersion());
     return 0;
   }

package/src/lib/adr-guard.js

@@ -0,0 +1,46 @@
+import path from "node:path";
+import { isDir, read, walk } from "./fs-ops.js";
+import { listHeader } from "./scan.js";
+
+// Deterministic ADR checkpoint (operator review 2026-07-19 §4.6). The work
+// playbook's "record an ADR" step was ignorable in silence: a change that
+// flexibilised an accepted ADR closed with no amendment and nothing barked.
+// This helper names the accepted ADRs whose text cites any of the change's
+// touched capabilities, so `change check` and `close` can print a loud,
+// advisory reminder: if the change alters what the ADR decided, record it
+// (`decision supersede` / `decision new`) instead of drifting past it.
+// A word match on capability names — a hint, never a decision (ADR 0005),
+// and never a blocker (an ADR merely MENTIONING a capability is normal).
+export function adrAdvisories(projectRoot, capabilities) {
+  const adrDir = path.join(projectRoot, ".doctrina", "decisions");
+  if (!isDir(adrDir) || capabilities.length === 0) return [];
+  const out = [];
+  for (const f of walk(adrDir)) {
+    const base = path.basename(f);
+    const m = base.match(/^(\d{4})-.*\.md$/);
+    if (!m) continue;
+    const text = read(f);
+    if ((listHeader(text, "Status") ?? "").toLowerCase() !== "accepted") continue;
+    const caps = capabilities.filter((cap) =>
+      new RegExp(`(^|[^a-z0-9-])${cap.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}([^a-z0-9-]|$)`, "im").test(text),
+    );
+    if (caps.length === 0) continue;
+    const titleMatch = text.match(/^#\s+ADR\s+\d{4}\s*[—-]\s*(.+)$/m);
+    out.push({ id: m[1], title: titleMatch ? titleMatch[1].trim() : base, caps });
+  }
+  return out;
+}
+
+// Print the advisory block shared by `change check` and `close`. Returns the
+// number of ADRs flagged (informational; callers never gate on it).
+export function printAdrCheckpoint(projectRoot, capabilities, { c }) {
+  const hits = adrAdvisories(projectRoot, capabilities);
+  if (hits.length === 0) return 0;
+  console.log(c.yellow("ADR checkpoint") + c.gray(" — accepted ADRs cite the touched capabilities:"));
+  for (const h of hits) {
+    console.log(`    ADR ${c.cyan(h.id)}  ${h.title}  ${c.gray(`(cites: ${h.caps.join(", ")})`)}`);
+  }
+  console.log(c.gray("    If this change alters what an ADR decided, record it now:"));
+  console.log(c.gray("    ") + c.cyan("doctrina decision supersede <n>") + c.gray(" · ") + c.cyan("doctrina decision new \"<title>\""));
+  return hits.length;
+}