doctrina-cli 0.11.0 → 0.13.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
@@ -40,8 +40,10 @@ export const OPERATIONS = [
   ["spec list", "List specs with version, status, and size"],
   ["spec set", "Edit spec headers / a criterion mark and resync the index"],
   ["change new", "Open a change proposal"],
-  ["change apply", "Apply spec deltas (ADDED/REMOVED auto, MODIFIED manual)"],
-  ["change archive", "Archive an applied change"],
+  ["change apply", "Apply spec deltas (ops blocks mechanically; batch ids ok)"],
+  ["change archive", "Archive an applied change (batch ids ok)"],
+  ["change check", "Pre-close dry-run: everything close would refuse, listed first"],
+  ["change tick", "List/tick the unchecked boxes (tasks + verification; --all)"],
   ["change diff", "Preview spec deltas (line diff for MODIFIED)"],
   ["change abandon", "Discard an open change cleanly (recorded in the ledger)"],
   ["contract new", "Own the integration surface (ports, env, interfaces)"],
@@ -56,6 +58,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 +87,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
@@ -91,6 +96,102 @@ export function surfaceHelp() {
   return OPERATIONS.map(([op, summary]) => `  ${op.padEnd(21)}${summary}`).join("\n");
 }
 
+// ---------------------------------------------------------------------------
+// The CLI-owned AGENTS.md command-surface block (operator review 2026-07-19,
+// meta-conclusion): for an agent, AGENTS.md IS the discovery interface — it
+// never runs `--help` spontaneously — so every command absent from the hub
+// was invisible for ~35 changes (`prime`, `handoff`, `doctor`, `show`, ...).
+// The fix is a marker-delimited section GENERATED from OPERATIONS, so the
+// hub's catalog is the CLI's catalog by construction: `init` scaffolds it,
+// `templates check` flags it stale, and `templates update --write` (hence
+// `doctrina upgrade --write`) regenerates exactly the marked span and
+// nothing else. Content between the markers is CLI-owned; everything
+// outside remains the adopter's, under the additive-only guarantee.
+
+export const SURFACE_BEGIN =
+  "<!-- doctrina:surface:begin — CLI-owned block, generated from the installed command catalog. Refreshed by `doctrina upgrade --write`; edits inside are overwritten. -->";
+export const SURFACE_END = "<!-- doctrina:surface:end -->";
+
+// Workflow grouping for the generated block. A test asserts the flattened
+// names equal COMMAND_NAMES, so a new command cannot ship ungrouped (and
+// therefore cannot ship invisible to AGENTS.md).
+export const SURFACE_GROUPS = [
+  ["Start", ["init", "intake", "work"]],
+  ["Author", ["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"]],
+  ["Maintain", ["templates", "hooks", "index", "watch", "metrics", "report", "completion", "upgrade"]],
+];
+
+// Per-command usage hints appended to the generated reference — arguments and
+// the flags an agent reaches for daily. Cosmetic only; the operation list
+// itself always comes from OPERATIONS.
+const SURFACE_HINTS = {
+  work: '"<prompt>" (--capability · --chore · --from-diff · --quiet)',
+  context: "[<cap>] --concat",
+  validate: "(--fix)",
+  coverage: "--strict",
+  trace: "--strict",
+  clarify: "--all (--lang pt|en)",
+  close: "<id...>",
+  upgrade: "--write",
+  prime: "(session start)",
+  handoff: "(before compaction/handover)",
+};
+
+// The full managed section, heading included, between the markers.
+export function surfaceMarkdown() {
+  const subsByCmd = new Map();
+  for (const [op] of OPERATIONS) {
+    const [cmd, sub] = op.split(" ");
+    if (!subsByCmd.has(cmd)) subsByCmd.set(cmd, []);
+    if (sub) subsByCmd.get(cmd).push(sub);
+  }
+  const renderCmd = (cmd) => {
+    const subs = subsByCmd.get(cmd) ?? [];
+    const hint = SURFACE_HINTS[cmd] ? ` ${SURFACE_HINTS[cmd]}` : "";
+    return subs.length > 0 ? `\`doctrina ${cmd} ${subs.join("|")}\`` : `\`doctrina ${cmd}${hint}\``;
+  };
+  const lines = [
+    "## Doctrina command surface (generated — reach for these, don't hand-author)",
+    "",
+    "Every operation of the installed CLI, grouped by workflow. The CLI",
+    "scaffolds from canonical templates and keeps `index.json` in sync, so",
+    "prefer it over writing artifacts by hand. Details: `doctrina --help`.",
+    "",
+  ];
+  for (const [label, cmds] of SURFACE_GROUPS) {
+    lines.push(`- **${label}:** ${cmds.map(renderCmd).join(" · ")}`);
+  }
+  lines.push("");
+  lines.push("Session bookends: `doctrina prime` to orient at session start;");
+  lines.push("`doctrina handoff` before compaction or handover. Continuous:");
+  lines.push("`doctrina watch`. Capture lessons: `doctrina skill suggest`.");
+  return lines.join("\n");
+}
+
+// The block as written to AGENTS.md: markers wrapping the generated section.
+export function surfaceBlock() {
+  return `${SURFACE_BEGIN}\n${surfaceMarkdown()}\n${SURFACE_END}`;
+}
+
+// Locate the managed block in an AGENTS.md text. Returns
+// { start, end, inner } (string offsets; inner excludes the marker lines)
+// or null when either marker is absent.
+export function findSurfaceBlock(text) {
+  const begin = text.match(/<!--\s*doctrina:surface:begin[\s\S]*?-->/);
+  if (!begin) return null;
+  const endRe = /<!--\s*doctrina:surface:end\s*-->/;
+  const end = endRe.exec(text.slice(begin.index + begin[0].length));
+  if (!end) return null;
+  const innerStart = begin.index + begin[0].length;
+  return {
+    start: begin.index,
+    end: innerStart + end.index + end[0].length,
+    inner: text.slice(innerStart, innerStart + end.index).replace(/^\r?\n|\r?\n$/g, ""),
+  };
+}
+
 // Extract the set of top-level `doctrina <command>` references that appear in
 // CODE context (fenced blocks or inline backtick spans) of a Markdown file —
 // AGENTS.md, typically. Restricting to code context avoids matching prose like

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/src/lib/spec-ops.js

@@ -17,8 +17,17 @@
 //   set-criterion 1: verified
 //   replace-criterion 2: [verified] new text — verified by `test/x.test.ts`
 //   append-criterion [unverified] new signal — verified by `test/y.test.ts`
+//   append-requirement event: When X occurs, the system shall do Y.
+//   replace-requirement ubiquitous 2: The system shall do Z.
 //   ```
 //
+// The requirement verbs (operator review 2026-07-19 §4.1) cover the dominant
+// MODIFIED case — inserting or rewording EARS bullets in a `## Requirements
+// (EARS)` subsection — so a typical delta no longer falls back to a manual
+// merge. Because append-* verbs resolve their position/number at APPLY time,
+// concurrent open changes appending to the same spec cannot collide on
+// numbering: order of application decides, mechanically.
+//
 // A `# comment` or blank line inside the block is ignored. When a delta has
 // no ops block, apply falls back to the manual-merge pointer (backward
 // compatible).
@@ -48,9 +57,13 @@ export function extractOps(deltaText) {
 
 // Find the body of the first ```ops fenced block, or null if absent. The
 // info string must be exactly "ops" (case-insensitive) so a normal code
-// fence in the prose is never mistaken for operations.
+// fence in the prose is never mistaken for operations. HTML comments are
+// stripped first: the scaffolded delta template carries an EXAMPLE ops block
+// inside its instructional comment, and executing an example against a real
+// spec is exactly the surprise this guard removes.
 function matchOpsBlock(text) {
-  const m = text.match(/^[ \t]*```[ \t]*ops[ \t]*\r?\n([\s\S]*?)^[ \t]*```[ \t]*$/m);
+  const visible = text.replace(/<!--[\s\S]*?-->/g, "");
+  const m = visible.match(/^[ \t]*```[ \t]*ops[ \t]*\r?\n([\s\S]*?)^[ \t]*```[ \t]*$/m);
   return m ? m[1] : null;
 }
 
@@ -92,11 +105,50 @@ function parseOpLine(line) {
       if (!rest) return { verb, error: "append-criterion is missing its text" };
       return { verb, value: rest };
     }
+    case "append-requirement": {
+      // append-requirement <section>: <text>
+      const colon = rest.indexOf(":");
+      if (colon < 0) return { verb, error: `append-requirement needs "<section>: <text>" (got "${rest}")` };
+      const section = normalizeSection(rest.slice(0, colon).trim());
+      const value = rest.slice(colon + 1).trim();
+      if (!section) return { verb, error: `append-requirement: unknown section "${rest.slice(0, colon).trim()}" (use ${SECTION_TOKENS})` };
+      if (!value) return { verb, error: "append-requirement is missing the requirement text" };
+      return { verb, section, value };
+    }
+    case "replace-requirement": {
+      // replace-requirement <section> <n>: <text>
+      const colon = rest.indexOf(":");
+      if (colon < 0) return { verb, error: `replace-requirement needs "<section> <n>: <text>" (got "${rest}")` };
+      const head = rest.slice(0, colon).trim().split(/\s+/);
+      const value = rest.slice(colon + 1).trim();
+      const n = Number(head[head.length - 1]);
+      const section = normalizeSection(head.slice(0, -1).join(" "));
+      if (!section) return { verb, error: `replace-requirement: unknown section "${head.slice(0, -1).join(" ")}" (use ${SECTION_TOKENS})` };
+      if (!Number.isInteger(n) || n < 1) return { verb, error: `replace-requirement needs a positive bullet number (got "${rest}")` };
+      if (!value) return { verb, error: `replace-requirement ${n} is missing the requirement text` };
+      return { verb, section, n, value };
+    }
     default:
       return { verb: null, error: `unknown operation "${verb}"` };
   }
 }
 
+// EARS subsection aliases -> the canonical token used to match the spec's
+// `### ` heading under `## Requirements (EARS)`. Deterministic: first word of
+// the heading, folded ("Unwanted-behavior (must-not)" -> "unwanted").
+const SECTIONS = {
+  ubiquitous: "ubiquitous",
+  event: "event", "event-driven": "event",
+  state: "state", "state-driven": "state",
+  unwanted: "unwanted", "unwanted-behavior": "unwanted", "must-not": "unwanted",
+  optional: "optional",
+};
+const SECTION_TOKENS = "ubiquitous|event|state|unwanted|optional";
+
+function normalizeSection(raw) {
+  return SECTIONS[raw.toLowerCase()] ?? null;
+}
+
 // Apply a parsed op list to a spec's Markdown text. Pure: returns
 // { text, applied: string[], errors: string[] } and never throws. A failed
 // op is recorded in `errors` and leaves the text unchanged for that op, so
@@ -132,6 +184,10 @@ function applyOne(text, op) {
       return replaceCriterion(text, op.n, op.value);
     case "append-criterion":
       return appendCriterion(text, op.value);
+    case "append-requirement":
+      return appendRequirement(text, op.section, op.value);
+    case "replace-requirement":
+      return replaceRequirement(text, op.section, op.n, op.value);
     default:
       return { error: `unknown operation "${op.verb}"` };
   }
@@ -221,6 +277,90 @@ export function replaceCriterion(text, n, value) {
   return { text: loc.lines.join("\n"), summary: `replace-criterion ${n}` };
 }
 
+// The `### <Section>` blocks under `## Requirements (EARS)`. Returns
+// { lines, sections: { <token>: { headingIndex, endIndex, bullets: [lineIndex] } } }
+// or null when the Requirements section is absent. A section's token is the
+// first word of its heading, folded through SECTIONS ("Unwanted-behavior
+// (must-not)" -> "unwanted"). endIndex is exclusive: the line index of the
+// next heading (### or ##) after the section, or lines.length.
+function locateRequirements(text) {
+  const lines = text.split(/\r?\n/);
+  let inRequirements = false;
+  let current = null;
+  const sections = {};
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    if (/^##\s+/.test(line) && !/^###/.test(line)) {
+      if (current) { current.endIndex = i; current = null; }
+      inRequirements = /^##\s+Requirements\b/i.test(line);
+      continue;
+    }
+    if (!inRequirements) continue;
+    const h = line.match(/^###\s+(\S+)/);
+    if (h) {
+      if (current) current.endIndex = i;
+      const token = SECTIONS[h[1].toLowerCase().replace(/[^a-z-]/g, "")] ?? null;
+      current = { headingIndex: i, endIndex: lines.length, bullets: [] };
+      if (token) sections[token] = current;
+      continue;
+    }
+    if (current && /^\s*-(\s|$)/.test(line)) current.bullets.push(i);
+  }
+  return Object.keys(sections).length > 0 || /^##\s+Requirements\b/im.test(text)
+    ? { lines, sections }
+    : null;
+}
+
+// A list item may wrap over indented continuation lines ("- When X,\n
+// the system shall ..."). Inserting right after the item's FIRST line
+// splits it from its continuation — the bug the 0.13.0 dogfood close
+// caught on this very repo's cli spec. From the item's first line, the
+// item ends after every following line that is indented content.
+function endOfItem(lines, startIndex) {
+  let i = startIndex;
+  while (i + 1 < lines.length && /^\s+\S/.test(lines[i + 1])) i += 1;
+  return i;
+}
+
+// append-requirement <section>: <text> — add "- <text>" at the end of the
+// EARS subsection. A lone "-" placeholder bullet (the untouched scaffold) is
+// replaced instead of appended after, so the first real requirement does not
+// land under an empty stub.
+export function appendRequirement(text, section, value) {
+  const loc = locateRequirements(text);
+  if (!loc) return { error: "append-requirement: spec has no '## Requirements (EARS)' section" };
+  const sec = loc.sections[section];
+  if (!sec) return { error: `append-requirement: no '### ${section}...' subsection found under Requirements` };
+  const placeholder = sec.bullets.length === 1 && /^\s*-\s*$/.test(loc.lines[sec.bullets[0]]);
+  if (placeholder) {
+    loc.lines[sec.bullets[0]] = `- ${value}`;
+  } else if (sec.bullets.length > 0) {
+    loc.lines.splice(endOfItem(loc.lines, sec.bullets[sec.bullets.length - 1]) + 1, 0, `- ${value}`);
+  } else {
+    // Empty section: insert after the heading (skipping one blank line if present).
+    let at = sec.headingIndex + 1;
+    while (at < sec.endIndex && loc.lines[at].trim() === "") at += 1;
+    loc.lines.splice(at, 0, `- ${value}`);
+  }
+  return { text: loc.lines.join("\n"), summary: `append-requirement ${section}: ${value.slice(0, 60)}` };
+}
+
+// replace-requirement <section> <n>: <text> — replace the nth bullet (1-based)
+// of the EARS subsection.
+export function replaceRequirement(text, section, n, value) {
+  const loc = locateRequirements(text);
+  if (!loc) return { error: "replace-requirement: spec has no '## Requirements (EARS)' section" };
+  const sec = loc.sections[section];
+  if (!sec) return { error: `replace-requirement: no '### ${section}...' subsection found under Requirements` };
+  const real = sec.bullets.filter((i) => !/^\s*-\s*$/.test(loc.lines[i]));
+  if (n > real.length) {
+    return { error: `replace-requirement: section "${section}" has ${real.length} requirement${real.length === 1 ? "" : "s"}, no #${n}` };
+  }
+  const indent = loc.lines[real[n - 1]].match(/^(\s*)/)[1];
+  loc.lines[real[n - 1]] = `${indent}- ${value}`;
+  return { text: loc.lines.join("\n"), summary: `replace-requirement ${section} ${n}` };
+}
+
 // append-criterion <text> — add a new numbered criterion after the last one
 // in the section.
 export function appendCriterion(text, value) {
@@ -231,6 +371,6 @@ export function appendCriterion(text, value) {
   }
   const last = loc.items[loc.items.length - 1];
   const nextN = Math.max(...loc.items.map((it) => it.n)) + 1;
-  loc.lines.splice(last.lineIndex + 1, 0, `${last.indent}${nextN}. ${value}`);
+  loc.lines.splice(endOfItem(loc.lines, last.lineIndex) + 1, 0, `${last.indent}${nextN}. ${value}`);
   return { text: loc.lines.join("\n"), summary: `append-criterion ${nextN}` };
 }

package/templates/AGENTS.md.template

@@ -22,37 +22,31 @@ prompt and approves; do not make them run the CLI or hand-author artifacts.
   spec each, `doctrina clarify --all` + `doctrina validate`, then flip the
   intake to `Status: converted`). After conversion the specs are the only
   source of truth — never edit `intake.md` to change requirements.
-- **Day-to-day.** Turn any request into a change with `doctrina work
-  "<prompt>"` and follow the printed playbook (spec delta → tasks →
-  implement → analyze → apply → archive → validate). Unsure what to do
-  next? Run `doctrina next`. Need to read? Run `doctrina context`. Ask the
-  human only on genuine ambiguity.
-
-## Doctrina command surface (reach for these — don't hand-author)
-
-The CLI scaffolds from canonical templates and keeps `index.json` in sync,
-so prefer it over writing artifacts by hand. Full list: `doctrina --help`.
-
-- **Read / orient (any task, first & last):** `doctrina status` (health) ·
-  `doctrina context [<cap>] --concat` (read pack) · `doctrina next` (what's
-  next) · `doctrina why <cap>` (provenance) · `doctrina constitution`
-  (standing rules) · `doctrina spec list` · `doctrina decision list` ·
-  `doctrina search <query>`
-- **Start:** `doctrina work "<prompt>"` · `--from-diff` (backfill from
-  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>`
-- **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)
-- **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>`
-
-Continuous: `doctrina watch` re-syncs and re-orients on every save.
-Capture lessons: `doctrina skill suggest` surfaces skills worth writing.
+- **Day-to-day.** Start every session with `doctrina prime` (gates, rules,
+  open work in one read). Turn any request into a change with `doctrina
+  work "<prompt>"` and follow the printed playbook (spec delta → tasks →
+  implement → close). Preview a close with `doctrina change check <id>`;
+  close with `doctrina close <id>`. Unsure what's next? `doctrina next`.
+  Before compaction or handover: `doctrina handoff`. Ask the human only on
+  genuine ambiguity.
+
+<!-- doctrina:surface:begin — CLI-owned block, generated from the installed command catalog. Refreshed by `doctrina upgrade --write`; edits inside are overwritten. -->
+## Doctrina command surface (generated — reach for these, don't hand-author)
+
+Every operation of the installed CLI, grouped by workflow. The CLI
+scaffolds from canonical templates and keeps `index.json` in sync, so
+prefer it over writing artifacts by hand. Details: `doctrina --help`.
+
+- **Start:** `doctrina init` · `doctrina intake` · `doctrina work "<prompt>" (--capability · --chore · --from-diff · --quiet)`
+- **Author:** `doctrina spec new|list|set` · `doctrina change new|apply|archive|check|tick|diff|abandon` · `doctrina contract new|list|check` · `doctrina decision new|accept|land|supersede|list` · `doctrina skill new|list|sync|suggest` · `doctrina intent add|list`
+- **Read / orient:** `doctrina prime (session start)` · `doctrina context [<cap>] --concat` · `doctrina show` · `doctrina search` · `doctrina status` · `doctrina next` · `doctrina why` · `doctrina handoff (before compaction/handover)` · `doctrina constitution`
+- **Gates:** `doctrina analyze` · `doctrina clarify --all (--lang pt|en)` · `doctrina validate (--fix)` · `doctrina coverage --strict` · `doctrina trace --strict` · `doctrina review` · `doctrina verify` · `doctrina close <id...>` · `doctrina doctor`
+- **Maintain:** `doctrina templates list|check|update` · `doctrina hooks install` · `doctrina index rebuild` · `doctrina watch` · `doctrina metrics` · `doctrina report` · `doctrina completion` · `doctrina upgrade --write`
+
+Session bookends: `doctrina prime` to orient at session start;
+`doctrina handoff` before compaction or handover. Continuous:
+`doctrina watch`. Capture lessons: `doctrina skill suggest`.
+<!-- doctrina:surface:end -->
 
 ## Stack and tooling
 

package/templates/change/spec-delta.md.template

@@ -7,21 +7,27 @@
 For ADDED: include the full new spec body below. On apply, the body is
 written verbatim to the target path.
 
-For MODIFIED: include only the sections that change, with clear
-before/after markers. Bookkeeping edits (flip a criterion, bump the
-version, set a header) can be made mechanical by adding a fenced `ops`
-block — on apply the CLI executes it against the target spec, all ops or
-none (ADR 0007). Anything the ops verbs cannot express (rewriting prose)
-stays a by-hand merge; a MODIFIED delta with no `ops` block prints a
-manual-merge pointer.
+For MODIFIED: prefer a fenced `ops` block — on apply the CLI executes it
+against the target spec, all ops or none (ADR 0007). The verbs cover
+headers, acceptance criteria, AND the EARS requirement bullets, so a
+typical delta applies mechanically end to end; only free-prose rewrites
+(Purpose, Maturity, ...) stay a by-hand merge. A MODIFIED delta with no
+`ops` block prints a manual-merge pointer.
 
   ```ops
   set-header Implementation: verified — durable adapter (`src/db.ts`)
   bump-version minor
   set-criterion 1: verified
   append-criterion [unverified] new signal — verified by `test/x.test.ts`
+  append-requirement event: When <trigger>, the system shall <action>.
+  replace-requirement ubiquitous 2: The system shall <action>.
   ```
 
+Requirement sections: ubiquitous | event | state | unwanted | optional.
+append-* ops resolve numbering/position at APPLY time, so several open
+changes appending to the same spec never collide on numbers — order of
+application decides.
+
 For REMOVED: the body may be empty; on apply, the target spec file is
 deleted and the capability is recorded in the change archive only.
 -->

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