doctrina-cli 0.11.0 → 0.12.0

package/src/commands/spec.js

@@ -134,9 +134,10 @@ function specSet(args, flags) {
   const impl = flagString(flags, "implementation");
   const status = flagString(flags, "status");
   const bump = flagString(flags, "bump");
+  const versionExplicit = flagString(flags, "version");
   const criterion = flagString(flags, "criterion");
-  if (impl === undefined && status === undefined && bump === undefined && criterion === undefined) {
-    console.error(c.red("error:") + " spec set needs at least one of --implementation, --status, --bump, --criterion");
+  if (impl === undefined && status === undefined && bump === undefined && versionExplicit === undefined && criterion === undefined) {
+    console.error(c.red("error:") + " spec set needs at least one of --implementation, --status, --bump, --version, --criterion");
     console.error(c.gray("hint: ") + `example: doctrina spec set ${capability} --implementation "verified — \`src/x.js\`" --bump minor`);
     return 2;
   }
@@ -156,6 +157,10 @@ function specSet(args, flags) {
     if (!["major", "minor", "patch"].includes(bump)) errors.push(`--bump needs major|minor|patch (got "${bump}")`);
     else apply(bumpVersion(text, bump));
   }
+  if (versionExplicit !== undefined) {
+    if (!/^\d+\.\d+\.\d+$/.test(versionExplicit)) errors.push(`--version needs semver X.Y.Z (got "${versionExplicit}")`);
+    else apply(setHeader(text, "Version", versionExplicit));
+  }
   if (criterion !== undefined) {
     const m = String(criterion).match(/^(\d+)\s*:\s*(.+)$/);
     if (!m) errors.push(`--criterion needs "<n>:<mark>" (got "${criterion}")`);
@@ -183,7 +188,10 @@ function specSet(args, flags) {
   const derived = deriveIndex(projectRoot, index);
   derived.last_updated = date;
   idx.save(projectRoot, derived);
-  console.log(c.green("indexed") + ` spec "${capability}" synced`);
+  // Echo the SPEC's resulting version, not the framework's — the two look
+  // identical in output and the ambiguity was a field-review papercut.
+  const specVersion = specHeader(text, "Version") ?? "—";
+  console.log(c.green("indexed") + ` spec "${capability}" synced (spec version ${specVersion})`);
   return 0;
 }
 
@@ -214,6 +222,8 @@ Options:
   --implementation "..." With \`set\`: set the Implementation header.
   --status "..."         With \`set\`: set the Status header.
   --bump major|minor|patch  With \`set\`: bump the spec Version.
+  --version X.Y.Z        With \`set\`: set the spec Version explicitly
+                         (the output echoes the SPEC version, not the CLI's).
   --criterion "<n>:<mark>"  With \`set\`: set criterion n's [mark]
                          (e.g. --criterion "2:verified").
 `;

package/src/commands/upgrade.js

@@ -0,0 +1,129 @@
+import path from "node:path";
+import process from "node:process";
+import { exists } from "../lib/fs-ops.js";
+import * as idx from "../lib/index-json.js";
+import { deriveIndex, indexesMatch } from "../lib/scan.js";
+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 * as templates from "./templates.js";
+import * as validate from "./validate.js";
+
+// Bring an existing project up to the installed CLI (user-reported gap: you
+// `npm update doctrina-cli`, but the project you once `doctrina init`-ed
+// keeps its old scaffold — stale framework stamp, an AGENTS.md that predates
+// new commands, missing recommended sections). `upgrade` is the one command
+// that closes that window, and it is an ORCHESTRATOR over the pieces that
+// already exist — templates update (additive-only), index rebuild (stamp
+// migration), validate --fix — so there is exactly one definition of each
+// step. Preview by default; --write applies. Never rewrites user content
+// (the same additive-only bound as `templates update`).
+
+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.");
+  }
+  const writeMode = flagBool(flags, "write", false);
+  const running = cliVersion();
+
+  // 1. Version gap: what the tree was last managed by vs what is installed.
+  let index = null;
+  let stamped = null;
+  try {
+    index = idx.load(projectRoot);
+    stamped = index.framework_version ?? null;
+  } catch {
+    index = null;
+  }
+  console.log(c.bold("doctrina upgrade") + c.gray(` — project ${stamped ?? "unstamped"} → CLI ${running}${writeMode ? "" : " (preview; --write applies)"}`));
+  console.log("");
+  if (stamped === running) {
+    console.log(c.gray("The framework stamp already matches the installed CLI — checking the scaffold anyway."));
+    console.log("");
+  }
+
+  let pending = 0;
+
+  // 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)"));
+  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
+
+  // 3. Index: rebuild from the tree, which also migrates the framework stamp.
+  console.log("");
+  console.log(c.gray("──── 2/3 index + framework stamp"));
+  try {
+    const current = idx.load(projectRoot);
+    const drifted = !indexesMatch(deriveIndex(projectRoot, current), current);
+    const staleStamp = (current.framework_version ?? null) !== running;
+    if (!drifted && !staleStamp) {
+      console.log(c.green("ok") + " index.json matches the tree and the stamp is current");
+    } else if (writeMode) {
+      const derived = deriveIndex(projectRoot, current);
+      derived.last_updated = today();
+      idx.save(projectRoot, derived); // save() stamps framework_version
+      console.log(c.green("rebuilt") + ` index.json${staleStamp ? ` — stamp ${current.framework_version ?? "unstamped"} → ${running}` : ""}`);
+    } else {
+      if (drifted) console.log(c.yellow("would  ") + "rebuild index.json from the tree (drifted)");
+      if (staleStamp) console.log(c.yellow("would  ") + `migrate framework stamp ${current.framework_version ?? "unstamped"} → ${running}`);
+      pending += 1;
+    }
+  } catch {
+    if (writeMode) {
+      console.log(c.red("error: ") + "index.json is missing or unreadable — run `doctrina index rebuild` manually");
+    } else {
+      console.log(c.yellow("would  ") + "rebuild index.json (missing or unreadable)");
+      pending += 1;
+    }
+  }
+
+  // 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.
+  console.log("");
+  console.log(c.gray("──── 3/3 validate" + (writeMode ? " --fix" : "")));
+  const vFlags = writeMode ? new Map([["fix", true]]) : new Map();
+  const vCode = await validate.run([], vFlags);
+
+  console.log("");
+  if (!writeMode) {
+    if (pending > 0) {
+      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) {
+    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."));
+  } else {
+    console.log(c.yellow("upgraded with findings") + " — resolve the validate errors above (they predate or exceed what an additive upgrade can fix).");
+  }
+  return vCode;
+}
+
+export const help = `
+Usage: doctrina upgrade [--write]
+
+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)
+  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)
+
+Preview by default (exits 1 when steps are pending); --write applies.
+`;

package/src/commands/validate.js

@@ -451,8 +451,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 +530,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 +556,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

@@ -71,14 +71,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
@@ -228,6 +232,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 +242,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 +303,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 +321,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
@@ -401,6 +415,16 @@ 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("       ```"));
+  console.log(c.gray("   Only prose rewrites 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"));
@@ -414,19 +438,22 @@ function printPlaybook(projectRoot, { id, prompt, pinned, matches, capability, c
   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("");
+  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,6 +474,8 @@ 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:
+  --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
   --id <id>            Override the derived change id
   --resume <id>        Reprint the playbook for an open change; create nothing

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/commands.js

@@ -13,13 +13,13 @@ export const COMMAND_NAMES = [
   // bootstrap / day-to-day
   "init", "intake", "work",
   // authoring
-  "spec", "change", "contract", "decision", "skill",
+  "spec", "change", "contract", "decision", "skill", "intent",
   // read / orient
   "prime", "context", "show", "search", "status", "next", "why", "handoff", "constitution",
   // gates
   "analyze", "clarify", "validate", "coverage", "trace", "review", "verify", "close", "doctor",
   // maintenance
-  "templates", "hooks", "index", "watch", "metrics", "report", "completion",
+  "templates", "hooks", "index", "watch", "metrics", "report", "completion", "upgrade",
 ];
 
 // The full operation surface — every `doctrina <command> [<subcommand>]` a
@@ -56,6 +56,8 @@ export const OPERATIONS = [
   ["skill list", "List skills with their descriptions"],
   ["skill sync", "Mirror skill frontmatter descriptions into index.json"],
   ["skill suggest", "Surface fix-shaped lessons worth a skill (--write scaffolds)"],
+  ["intent add", "Append a new product intent anchor post-intake (- [SC5] ...)"],
+  ["intent list", "List product.md intent anchors in document order"],
   ["analyze", "Inspect a change folder before applying"],
   ["clarify", "Smell-test a Markdown file for ambiguity (--all for the tree)"],
   ["prime", "Session primer: gates, rules, open work, next steps in one read"],
@@ -83,6 +85,7 @@ export const OPERATIONS = [
   ["metrics", "Local git-derived adoption metrics (no network)"],
   ["report", "Markdown digest for a period: changes, gates, git summary"],
   ["completion", "Print bash/zsh/pwsh completions (generated from the catalog)"],
+  ["upgrade", "Bring an existing project up to the installed CLI (--write applies)"],
 ];
 
 // The Commands block of `doctrina --help`, generated from OPERATIONS so the

package/src/lib/scan.js

@@ -25,6 +25,15 @@ export function listHeader(text, name) {
   return m ? m[1].trim() : null;
 }
 
+// The machine-readable "**Depends on:** defects, decisions" spec header: the
+// sibling capabilities this spec builds on. Returns [] when absent, "n/a", or
+// empty. One parser so index, why, context, and review agree.
+export function parseDependsOn(text) {
+  const raw = specHeader(text, "Depends on");
+  if (!raw || /^n\/a\b/i.test(raw.trim()) || raw.trim() === "—") return [];
+  return raw.match(/[a-z][a-z0-9][a-z0-9-]*/g) ?? [];
+}
+
 function dirEntries(dir) {
   if (!isDir(dir)) return [];
   return readdirSync(dir).filter((e) => !e.startsWith(".")).sort();
@@ -87,6 +96,13 @@ export function deriveIndex(projectRoot, current) {
     const realizesRaw = specHeader(text, "Realizes");
     const realizes = realizesRaw ? (realizesRaw.match(/[A-Z]+\d+/g) ?? []) : prev?.realizes;
     if (realizes && realizes.length) entry.realizes = realizes;
+    // Depends on: sibling capabilities this spec builds on (0.11.0 field
+    // review — specs cited each other only in prose, unreadable by machine).
+    // Stored as a capability-id list so `why` can show the graph, `context`
+    // can pull dependencies into the read pack, and `review` can flag
+    // dependents of a touched capability.
+    const depends = specHeader(text, "Depends on") !== null ? parseDependsOn(text) : prev?.depends_on;
+    if (depends && depends.length) entry.depends_on = depends;
     out.artifacts.specs.push(entry);
   }
 

package/templates/AGENTS.md.template

@@ -42,17 +42,21 @@ so prefer it over writing artifacts by hand. Full list: `doctrina --help`.
   existing code) · `--chore` (no-spec infra/docs/build)
 - **Scaffold (manual creation stays available):** `doctrina spec new <cap>`
   (`--bug`) · `doctrina decision new "<title>"` · `doctrina change new <id>`
-  · `doctrina contract new <id>` · `doctrina skill new <slug>`
+  · `doctrina contract new <id>` · `doctrina skill new <slug>` · `doctrina
+  intent add "<text>"` (new product anchor post-intake)
 - **Advance / close:** `doctrina change apply|archive|diff <id>` · `doctrina
   decision accept|land|supersede <n>` · `doctrina spec set <cap> [...]` ·
-  `doctrina close <id>` (whole close in one pass)
+  `doctrina close <id>` (whole close in one pass, coverage scoped to the
+  change)
 - **Gates (ground truth, not guesses):** `doctrina validate` (`--fix`) ·
   `doctrina verify` · `doctrina review` (conformance vs specs/ADRs) ·
-  `doctrina coverage --strict` · `doctrina trace --strict` · `doctrina
-  contract check` · `doctrina clarify --all` · `doctrina analyze <id>`
+  `doctrina coverage --strict` (`--run` executes cited proof) ·
+  `doctrina trace --strict` · `doctrina contract check` ·
+  `doctrina clarify --all` · `doctrina analyze <id>`
 
 Continuous: `doctrina watch` re-syncs and re-orients on every save.
 Capture lessons: `doctrina skill suggest` surfaces skills worth writing.
+After a CLI update: `doctrina upgrade --write` brings this project up.
 
 ## Stack and tooling
 

package/templates/spec.md.template

@@ -24,7 +24,15 @@ ADR 0006). Tag product.md success-criteria bullets with an anchor —
 "- [SC1] ..." — and list the ones this spec delivers above. An "active"
 spec with no Realizes: header warns under `doctrina validate`; if the
 capability genuinely maps to no product anchor (internal tooling), keep
-the header and write "n/a — <why>" to record that on purpose.
+the header and write "n/a — <why>" to record that on purpose. Need a NEW
+anchor for intent born after the intake? `doctrina intent add "<text>"`.
+
+Optional: declare the sibling capabilities this spec builds on with a
+machine-readable header — "**Depends on:** defects, decisions". It feeds
+`doctrina why` (the dependency graph), `doctrina context <cap>` (the
+dependencies join the read pack), and `doctrina review` (dependents of a
+touched capability are flagged). Citing them only in prose keeps every
+tool blind to the link.
 -->
 
 ## Purpose