doctrina-cli 0.4.0 → 0.8.0

package/src/commands/work.js

@@ -1,8 +1,10 @@
 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 { flagString } from "../lib/args.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 { changeNew } from "./change.js";
@@ -17,15 +19,49 @@ import { changeNew } from "./change.js";
 
 export async function run(positional, flags) {
   const prompt = positional.join(" ").trim();
-  if (!prompt) {
+  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.");
+  }
+
+  // --resume <id>: reprint the playbook for an existing open change rather than
+  // open a new one (review G1 — `work "continue"` used to slug the word and
+  // fabricate a junk `NNNN-continue` change the operator had to delete).
+  if (flags.has("resume")) {
+    return resumeChange(projectRoot, flagString(flags, "resume"));
+  }
+
+  // --from-diff backfills from code already written (review F8): the
+  // working-tree changes are the input, so no prompt is required.
+  const fromDiff = flagBool(flags, "from-diff", false);
+  const chore = flagBool(flags, "chore", false) || flagBool(flags, "no-spec", false);
+  let files = [];
+  if (fromDiff) {
+    files = changedFiles(projectRoot);
+    if (files.length === 0) {
+      console.error(c.red("error:") + " --from-diff found no working-tree changes to backfill from");
+      console.error(c.gray("hint: ") + "make (or stage) the code changes first, then run `doctrina work --from-diff`");
+      return 1;
+    }
+  }
+
+  if (!prompt && !fromDiff) {
     console.error(c.red("error:") + " work requires a prompt (quote it if it contains spaces)");
     console.error(c.gray("hint: ") + "example: doctrina work \"add login with email and password\"");
     return 2;
   }
 
-  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.");
+  // A thin, resume-shaped prompt ("continue", "prossiga", ...) while a change
+  // is open is almost certainly "finish what's open", not "start a change named
+  // after that word". Suggest resuming instead of creating noise; --force opens
+  // a new change anyway. The match is a deterministic stoplist, not language
+  // understanding (still ADR 0005).
+  if (!fromDiff && !flagBool(flags, "force", false) && isResumeIntent(prompt)) {
+    const open = openChanges(projectRoot);
+    if (open.length > 0) {
+      printResumeSuggestion(open);
+      return 0;
+    }
   }
 
   const pinned = flagString(flags, "capability");
@@ -34,38 +70,74 @@ export async function run(positional, flags) {
     return 2;
   }
 
-  const id = flagString(flags, "id") ?? `${nextChangeNumber(projectRoot)}-${slugify(prompt)}`;
+  const effPrompt = prompt || `backfill specs from ${files.length} changed file${files.length === 1 ? "" : "s"}`;
+  const slug = prompt ? slugify(prompt) : "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, prompt], flags);
+  const code = changeNew([id, effPrompt], flags);
   if (code !== 0) return code;
 
   // Record the prompt verbatim as the change's Why — the raw intent has
-  // one home, and it is the proposal, not the playbook output.
+  // one home, and it is the proposal, not the playbook output. For --from-diff,
+  // also record the changed files so the backfill's input is in the artifact.
   const proposalPath = path.join(projectRoot, ".doctrina", "changes", id, "proposal.md");
   if (isFile(proposalPath)) {
     const txt = read(proposalPath);
+    let why = effPrompt;
+    if (fromDiff) {
+      const list = files.slice(0, 30).map((f) => `- \`${f}\``).join("\n");
+      const more = files.length > 30 ? `\n- … and ${files.length - 30} more` : "";
+      why = `${effPrompt}\n\nBackfilled from working-tree changes:\n${list}${more}`;
+    }
     // CRLF-tolerant: templates may be checked out with \r\n on Windows.
-    let updated = txt.replace(/(## Why\r?\n\r?\n)<!--[\s\S]*?-->[ \t]*\r?\n?/, `$1${prompt}\n`);
-    if (updated === txt) updated = txt.replace(/(## Why\r?\n)/, `$1\n${prompt}\n`);
+    let updated = txt.replace(/(## Why\r?\n\r?\n)<!--[\s\S]*?-->[ \t]*\r?\n?/, `$1${why}\n`);
+    if (updated === txt) updated = txt.replace(/(## Why\r?\n)/, `$1\n${why}\n`);
     if (pinned) {
       updated = updated.replace(/^(-\s+\*\*Affects specs:\*\*).*$/m, `$1 ${pinned}`);
     }
     if (updated !== txt) write(proposalPath, updated, { force: true });
   }
 
-  const matches = pinned ? [] : rankCapabilities(projectRoot, prompt);
+  // 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);
+  const diffMatches = pinned ? [] : rankCapabilitiesByDiff(projectRoot, allChanged);
+  const matches = pinned ? [] : (fromDiff ? diffMatches : rankCapabilities(projectRoot, effPrompt));
   const capability = pinned ?? matches[0]?.id ?? null;
-  const clarity = assessBrief(prompt, { kind: "prompt" });
+  const clarity = assessBrief(effPrompt, { kind: "prompt" });
 
   console.log("");
-  printPlaybook(projectRoot, { id, prompt, pinned, matches, capability, clarity });
+  if (chore) {
+    printChorePlaybook(projectRoot, { id, prompt: effPrompt });
+  } else {
+    printPlaybook(projectRoot, {
+      id, prompt: effPrompt, pinned, matches, capability, clarity,
+      fromDiff, diffMatches: fromDiff ? [] : diffMatches,
+    });
+  }
   return 0;
 }
 
+// Changed files in the working tree (tracked + untracked), for the diff-based
+// capability hint and `--from-diff` backfill. Empty outside a git repo or with
+// no changes. Read-only: never invokes a mutating git command.
+function changedFiles(projectRoot) {
+  const run = (args) => {
+    const r = spawnSync("git", args, { cwd: projectRoot, encoding: "utf8" });
+    if (r.error || r.status !== 0) return [];
+    return r.stdout.split(/\r?\n/).map((s) => s.trim()).filter(Boolean);
+  };
+  const set = new Set([
+    ...run(["diff", "--name-only", "HEAD"]),                 // tracked, staged + unstaged
+    ...run(["ls-files", "--others", "--exclude-standard"]),  // untracked
+  ]);
+  return [...set];
+}
+
 // Next sequential NNNN across open changes and the archive, so work-driven
 // ids stay ordered no matter how earlier changes were named.
 function nextChangeNumber(projectRoot) {
@@ -91,6 +163,70 @@ function nextChangeNumber(projectRoot) {
   return String(max + 1).padStart(4, "0");
 }
 
+// Open (non-archived) changes from the index — the set `work --resume` and
+// the thin-prompt guard offer to continue.
+function openChanges(projectRoot) {
+  try {
+    return idx.load(projectRoot).artifacts?.changes ?? [];
+  } catch {
+    return [];
+  }
+}
+
+// A deterministic stoplist of "carry on" prompts (en + pt). Folded and
+// stripped to letters so "go on" / "keep going" / "continuação" all match.
+// Not language understanding — just the words that mean "resume", which is
+// exactly when slugging the prompt produces a junk change (G1).
+const RESUME_WORDS = new Set([
+  "continue", "continua", "continuar", "continuacao", "continuemos", "continuando",
+  "prossiga", "prosseguir", "prossegue", "proceed", "resume", "resumir",
+  "retomar", "retoma", "segue", "seguir", "go", "goon", "next", "keepgoing",
+  "vamos", "more", "mais",
+]);
+
+function isResumeIntent(prompt) {
+  return RESUME_WORDS.has(fold(prompt).replace(/[^a-z0-9]+/g, ""));
+}
+
+function printResumeSuggestion(open) {
+  console.log(c.yellow(`open change${open.length === 1 ? "" : "s"} detected`) +
+    " — did you mean to continue one of these?");
+  console.log("");
+  for (const ch of open) {
+    console.log(`    ${c.cyan(ch.id)}  ${c.gray((ch.title ?? "").slice(0, 60))}  ${c.gray(`[${ch.status ?? "open"}]`)}`);
+  }
+  console.log("");
+  console.log("Resume the existing change (reprints its playbook):");
+  console.log(`    ${c.cyan(`doctrina work --resume ${open[0].id}`)}`);
+  console.log("Or open a new change anyway:");
+  console.log(`    ${c.cyan(`doctrina work "<prompt>" --force`)}`);
+}
+
+// Reprint the work playbook for an already-open change, ranking capabilities
+// from its recorded title (the original prompt). Creates nothing.
+function resumeChange(projectRoot, resumeId) {
+  const open = openChanges(projectRoot);
+  if (!resumeId || resumeId === true) {
+    console.error(c.red("error:") + " --resume needs a change id");
+    if (open.length) console.error(c.gray("open: ") + open.map((ch) => ch.id).join(", "));
+    return 2;
+  }
+  const entry = open.find((ch) => ch.id === resumeId);
+  if (!entry && !isDir(path.join(projectRoot, ".doctrina", "changes", resumeId))) {
+    console.error(c.red("error:") + ` no open change "${resumeId}"`);
+    if (open.length) console.error(c.gray("open: ") + open.map((ch) => ch.id).join(", "));
+    return 1;
+  }
+  const prompt = entry?.title ?? resumeId;
+  const matches = rankCapabilities(projectRoot, prompt);
+  const capability = matches[0]?.id ?? null;
+  const clarity = assessBrief(prompt, { kind: "prompt" });
+  console.log(c.bold(`Resuming change ${resumeId}`) + c.gray(" — agent-executed (ADR 0005)."));
+  console.log("");
+  printPlaybook(projectRoot, { id: resumeId, prompt, pinned: null, matches, capability, clarity });
+  return 0;
+}
+
 // ASCII-folded kebab-case of the prompt ("Faça o login" -> "faca-o-login").
 export function slugify(text) {
   let slug = text
@@ -152,16 +288,69 @@ export function rankCapabilities(projectRoot, prompt) {
   return ranked.sort((a, b) => b.score - a.score || a.id.localeCompare(b.id)).slice(0, 3);
 }
 
-function printPlaybook(projectRoot, { id, prompt, pinned, matches, capability, clarity }) {
+// Rank capabilities by the working tree, not the prompt (review F10): a changed
+// 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) {
+  const specsDir = path.join(projectRoot, ".doctrina", "specs");
+  if (!files || files.length === 0 || !isDir(specsDir)) return [];
+  const norm = files.map((f) => f.replace(/\\/g, "/"));
+
+  const ranked = [];
+  for (const cap of readdirSync(specsDir).sort()) {
+    const specPath = path.join(specsDir, cap, "spec.md");
+    if (!isFile(specPath)) continue;
+    const specText = read(specPath);
+    let score = 0;
+    for (const f of norm) {
+      if (f.split("/").includes(cap)) score += 3;            // src/<cap>/... etc.
+      if (specText.includes(f)) score += 5;                  // file cited in the spec
+      else if (specText.includes(path.basename(f))) score += 2; // filename cited
+    }
+    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);
+}
+
+// A chore is a spec-less change (review F9): the playbook drops the spec-delta
+// steps and goes straight to implement → verify → archive → validate, so the
+// agent is not prompted to invent a delta for infra/docs/build work.
+function printChorePlaybook(projectRoot, { id, prompt }) {
+  console.log(c.bold(`Chore playbook — change ${id}`) + c.gray(" — agent-executed (ADR 0005); no spec deltas."));
+  console.log("");
+  console.log(`Prompt: "${prompt}"`);
+  console.log("");
+  console.log("Execute in order, in a single linear pass:");
+  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("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`);
+  console.log("   Then check the proposal's ## Verification boxes and every task.");
+  console.log("3. This is a chore: no spec changes. If you find yourself needing a");
+  console.log(`   spec delta, it is not a chore — reopen with ${c.cyan("doctrina work \"<prompt>\"")}.`);
+  console.log(`4. ${c.cyan(`doctrina change apply ${id}`)}  (zero deltas → flips to applied).`);
+  console.log(`5. ${c.cyan(`doctrina change archive ${id}`)}, then ${c.cyan("doctrina validate")}.`);
+  console.log(c.gray("   If this fix taught a lesson worth not relearning, capture it: ") +
+    c.cyan("doctrina skill new <slug>") + c.gray("."));
+}
+
+function printPlaybook(projectRoot, { id, prompt, pinned, matches, capability, clarity, fromDiff = false, diffMatches = [] }) {
   const capToken = capability ?? "<capability>";
-  console.log(c.bold(`Work playbook — change ${id}`) + c.gray(" — agent-executed (ADR 0005)."));
+  const title = fromDiff ? "Backfill playbook" : "Work playbook";
+  console.log(c.bold(`${title} — change ${id}`) + c.gray(" — agent-executed (ADR 0005)."));
   console.log("");
   console.log(`Prompt: "${prompt}"`);
+  if (fromDiff) {
+    console.log(c.gray("Code-first: write the spec that describes what the working tree already does."));
+  }
 
   // Clarification gate (review Topic A): a thin prompt is the moment to ask
   // the user, not to invent a spec. Advisory — the change is still scaffolded
   // (it is a draft), but the agent is told to resolve the gaps first.
-  if (clarity?.thin) {
+  if (clarity?.thin && !fromDiff) {
     console.log("");
     console.log(c.yellow("⚠ thin prompt — clarify with the user before writing spec deltas:"));
     for (const r of clarity.reasons) console.log(`    - ${r}`);
@@ -172,12 +361,22 @@ function printPlaybook(projectRoot, { id, prompt, pinned, matches, capability, c
     console.log(`Capability (pinned): ${c.cyan(pinned)}` +
       (hasSpec ? "" : c.yellow(" — no spec yet; create it in step 2")));
   } else if (matches.length > 0) {
-    console.log("Likely capabilities (deterministic term match — a hint, not a decision):");
+    const how = fromDiff ? "touched by your working tree" : "deterministic term match";
+    console.log(`Likely capabilities (${how} — a hint, not a decision):`);
     for (const m of matches) {
       console.log(`    ${c.cyan(m.id.padEnd(20))} score ${String(m.score).padStart(3)}   ${c.gray(m.path)}`);
     }
   } else {
-    console.log(c.gray("No existing spec matches the prompt — likely a new capability."));
+    console.log(c.gray(fromDiff
+      ? "No existing spec matches the changed files — likely a new capability."
+      : "No existing spec matches the prompt — likely a new capability."));
+  }
+
+  // Extra signal (review F10): even for a prompt-driven change, show which
+  // capabilities the working tree touched — often the truer hint.
+  if (!fromDiff && diffMatches.length > 0) {
+    console.log(c.gray("Also touched by your working tree: ") +
+      diffMatches.map((m) => c.cyan(m.id)).join(", "));
   }
 
   console.log("");
@@ -188,6 +387,10 @@ function printPlaybook(projectRoot, { id, prompt, pinned, matches, capability, c
   console.log("");
   console.log("2. If the capability has no spec yet:");
   console.log(`       ${c.cyan("doctrina spec new <capability>")}`);
+  console.log(c.gray("   Trace it to product intent: tag the product.md success-criteria bullet"));
+  console.log(c.gray("   it serves with an anchor (\"- [SC1] ...\") and set the spec's"));
+  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:`);
@@ -198,6 +401,11 @@ 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`\">"));
+  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"));
+    console.log(c.gray("   diff is tested). The changed files are listed in the proposal's ## Why."));
+  }
   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).");
@@ -207,15 +415,18 @@ function printPlaybook(projectRoot, { id, prompt, pinned, matches, capability, c
   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 deltas are merged by hand).`);
+  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("   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("."));
 }
 
 export const help = `
@@ -231,8 +442,18 @@ context → spec delta → tasks → implement → analyze → apply → verify
 (verify + coverage) → archive → validate. No natural-language
 interpretation happens in the CLI.
 
+When the prompt is a bare "continue"/"prossiga"/"next" and a change is
+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
   --id <id>            Override the derived change id
-  --force              Overwrite an existing change folder
+  --resume <id>        Reprint the playbook for an open change; create nothing
+  --from-diff          Backfill: scaffold from the working-tree changes (no
+                       prompt needed) and print a code-first playbook (F8)
+  --chore, --no-spec   Open a spec-less chore change (infra/docs/build) with a
+                       playbook that skips the spec-delta steps (F9)
+  --force              Open a new change even when one is open, and overwrite
+                       an existing change folder
 `;

package/src/index.js

@@ -26,11 +26,17 @@ import * as coverage from "./commands/coverage.js";
 import * as verify from "./commands/verify.js";
 import * as contract from "./commands/contract.js";
 import * as trace from "./commands/trace.js";
+import * as status from "./commands/status.js";
+import * as close from "./commands/close.js";
+import * as review from "./commands/review.js";
+import * as watch from "./commands/watch.js";
+import * as why from "./commands/why.js";
 
 const COMMANDS = {
   init, spec, change, decision, validate, hooks, analyze, clarify,
   templates, skill, index: indexCmd, next, metrics, context, search,
   intake, work, coverage, verify, contract, trace,
+  status, close, review, watch, why,
 };
 
 const TOP_HELP = `
@@ -56,6 +62,7 @@ Commands:
   skill new            Scaffold an on-demand procedural memory skill
   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)
   analyze              Inspect a change folder before applying
   clarify              Smell-test a Markdown file for ambiguity (--all for the tree)
   context              Print the context pack for a task in read order
@@ -63,12 +70,17 @@ Commands:
   validate             Run schema and structural checks
   coverage             Report acceptance criteria with linked evidence (--strict gates)
   trace                Report intent provenance: product intent → specs (--strict gates)
+  review               Conformance review of your changes vs specs/ADRs/contracts
   verify               Run project-declared typecheck/test/build checks (the real gate)
+  close                Run the whole close sequence for a change in one pass
+  status               One-glance project health dashboard
+  why                  Explain a capability's provenance (intent → proof → ADRs)
   templates list       List the templates shipped by the installed CLI
   templates check      Compare the project against the recommended template shape
   hooks install        Install the pre-commit hook
   index rebuild        Regenerate index.json from the artifacts on disk
   next                 Print the recommended next workflow actions
+  watch                Re-run validate --fix + next on every change (--once for one pass)
   metrics              Local git-derived adoption metrics (no network)
 
 Global flags:
@@ -78,7 +90,7 @@ Global flags:
 
 async function main(argv) {
   const { positional, flags } = parseArgs(argv, {
-    boolean: ["help", "h", "version", "v", "force", "non-interactive", "check", "save", "bug", "write", "all", "concat", "archive", "strict", "list", "init"],
+    boolean: ["help", "h", "version", "v", "force", "non-interactive", "check", "save", "bug", "write", "all", "concat", "archive", "strict", "list", "init", "fix", "once", "clean"],
   });
 
   if (flags.get("version") || flags.get("v")) {

package/src/lib/spec-ops.js

@@ -0,0 +1,236 @@
+// Structured spec operations (ADR 0007 / review F3). A MODIFIED spec delta
+// historically carried prose ("flip criterion 2 to verified", "bump to
+// 0.3.0") that a human merged by hand — the single most error-prone step in
+// the change flow, and the source of index/version drift. These functions
+// turn that prose into a small, declarative, mechanically applicable
+// operation set so `change apply` can edit the spec and regenerate the index
+// in one transaction. The verbs are deliberately narrow: they touch headers
+// and acceptance-criteria markers, never arbitrary spec prose — semantic
+// rewriting stays the agent's job (ADR 0005); only the bookkeeping is
+// automated.
+//
+// Delta format — an optional fenced block inside a MODIFIED delta body:
+//
+//   ```ops
+//   set-header Implementation: verified — durable adapter (`src/db.ts`)
+//   bump-version minor
+//   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`
+//   ```
+//
+// 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).
+
+const HEADER_RE = (name) =>
+  new RegExp(`^(\\s*(?:-\\s+)?\\*\\*${escapeRe(name)}:\\*\\*)\\s*(.*)$`, "m");
+
+function escapeRe(s) {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+// Pull the operations out of a delta body. Returns an array of parsed ops
+// (or an empty array when there is no `ops` block). Parsing is line-based and
+// tolerant of CRLF.
+export function extractOps(deltaText) {
+  const block = matchOpsBlock(deltaText);
+  if (block === null) return [];
+  const ops = [];
+  for (const raw of block.split(/\r?\n/)) {
+    const line = raw.trim();
+    if (line === "" || line.startsWith("#") || line.startsWith("<!--")) continue;
+    const op = parseOpLine(line);
+    ops.push(op); // includes { verb: null, error } for unknown lines
+  }
+  return ops;
+}
+
+// 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.
+function matchOpsBlock(text) {
+  const m = text.match(/^[ \t]*```[ \t]*ops[ \t]*\r?\n([\s\S]*?)^[ \t]*```[ \t]*$/m);
+  return m ? m[1] : null;
+}
+
+function parseOpLine(line) {
+  // `<verb> <rest>` — the verb is the first whitespace-delimited token.
+  const sp = line.indexOf(" ");
+  const verb = (sp < 0 ? line : line.slice(0, sp)).toLowerCase();
+  const rest = sp < 0 ? "" : line.slice(sp + 1).trim();
+
+  switch (verb) {
+    case "set-header": {
+      // set-header <Name>: <value>
+      const colon = rest.indexOf(":");
+      if (colon < 0) return { verb, error: `set-header needs "<Name>: <value>" (got "${rest}")` };
+      const name = rest.slice(0, colon).trim();
+      const value = rest.slice(colon + 1).trim();
+      if (!name) return { verb, error: "set-header is missing the header name" };
+      return { verb, name, value };
+    }
+    case "bump-version": {
+      const level = rest.toLowerCase();
+      if (!["major", "minor", "patch"].includes(level)) {
+        return { verb, error: `bump-version needs major|minor|patch (got "${rest}")` };
+      }
+      return { verb, level };
+    }
+    case "set-criterion":
+    case "replace-criterion": {
+      // <verb> <n>: <value>
+      const colon = rest.indexOf(":");
+      if (colon < 0) return { verb, error: `${verb} needs "<n>: <value>" (got "${rest}")` };
+      const n = Number(rest.slice(0, colon).trim());
+      const value = rest.slice(colon + 1).trim();
+      if (!Number.isInteger(n) || n < 1) return { verb, error: `${verb} needs a positive criterion number (got "${rest}")` };
+      if (!value) return { verb, error: `${verb} ${n} is missing a value` };
+      return { verb, n, value };
+    }
+    case "append-criterion": {
+      if (!rest) return { verb, error: "append-criterion is missing its text" };
+      return { verb, value: rest };
+    }
+    default:
+      return { verb: null, error: `unknown operation "${verb}"` };
+  }
+}
+
+// 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
+// `change apply` can refuse to write a partially-mutated spec.
+export function applyOps(specText, ops) {
+  let text = specText;
+  const applied = [];
+  const errors = [];
+  for (const op of ops) {
+    if (op.error || !op.verb) {
+      errors.push(op.error ?? "malformed operation");
+      continue;
+    }
+    const res = applyOne(text, op);
+    if (res.error) errors.push(res.error);
+    else {
+      text = res.text;
+      applied.push(res.summary);
+    }
+  }
+  return { text, applied, errors };
+}
+
+function applyOne(text, op) {
+  switch (op.verb) {
+    case "set-header":
+      return setHeader(text, op.name, op.value);
+    case "bump-version":
+      return bumpVersion(text, op.level);
+    case "set-criterion":
+      return setCriterionMark(text, op.n, op.value);
+    case "replace-criterion":
+      return replaceCriterion(text, op.n, op.value);
+    case "append-criterion":
+      return appendCriterion(text, op.value);
+    default:
+      return { error: `unknown operation "${op.verb}"` };
+  }
+}
+
+// Replace the value of a `**Name:** ...` header line (dash-optional),
+// preserving the original prefix. Errors when the header is absent — a
+// set-header that silently does nothing is exactly the drift this prevents.
+export function setHeader(text, name, value) {
+  const re = HEADER_RE(name);
+  if (!re.test(text)) {
+    return { error: `set-header: no "**${name}:**" header in the spec to set` };
+  }
+  const next = text.replace(re, (_m, prefix) => `${prefix} ${value}`.replace(/\s+$/, ""));
+  return { text: next, summary: `set ${name}: ${value}` };
+}
+
+export function bumpVersion(text, level) {
+  const re = HEADER_RE("Version");
+  const m = text.match(re);
+  if (!m) return { error: "bump-version: no **Version:** header in the spec" };
+  const cur = (m[2] ?? "").trim();
+  const parts = cur.split(".").map((x) => Number(x));
+  if (parts.length !== 3 || parts.some((x) => !Number.isInteger(x))) {
+    return { error: `bump-version: current version "${cur}" is not semver X.Y.Z` };
+  }
+  let [maj, min, pat] = parts;
+  if (level === "major") { maj += 1; min = 0; pat = 0; }
+  else if (level === "minor") { min += 1; pat = 0; }
+  else { pat += 1; }
+  const next = `${maj}.${min}.${pat}`;
+  const out = text.replace(re, (_m, prefix) => `${prefix} ${next}`);
+  return { text: out, summary: `bump-version ${level}: ${cur} -> ${next}` };
+}
+
+// The acceptance-criteria block: lines under "## Acceptance criteria" that
+// begin with "<n>. ". Returns { start, end, items: [{ n, lineIndex, line }] }
+// where lines is the full split array. Null when the section is absent.
+function locateCriteria(text) {
+  const lines = text.split(/\r?\n/);
+  let inSection = false;
+  let sectionStart = -1;
+  const items = [];
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    if (/^##\s+/.test(line)) {
+      if (inSection) { inSection = false; }
+      if (/^##\s+Acceptance criteria\b/i.test(line)) { inSection = true; sectionStart = i; }
+      continue;
+    }
+    if (!inSection) continue;
+    const m = line.match(/^(\s*)(\d+)\.\s+(.*)$/);
+    if (m) items.push({ n: Number(m[2]), lineIndex: i, indent: m[1] });
+  }
+  if (sectionStart < 0) return null;
+  return { lines, items };
+}
+
+// set-criterion <n>: <mark> — replace the [mark] token on criterion n.
+// Accepts "verified"/"[verified]"; if the criterion has no [..] token, one
+// is inserted right after the "n. " prefix.
+export function setCriterionMark(text, n, markRaw) {
+  const loc = locateCriteria(text);
+  if (!loc) return { error: "set-criterion: spec has no '## Acceptance criteria' section" };
+  const item = loc.items.find((it) => it.n === n);
+  if (!item) return { error: `set-criterion: no criterion #${n} found` };
+  const mark = markRaw.replace(/^\[|\]$/g, "").trim();
+  const line = loc.lines[item.lineIndex];
+  let next;
+  if (/\[[^\]]*\]/.test(line)) {
+    next = line.replace(/\[[^\]]*\]/, `[${mark}]`);
+  } else {
+    next = line.replace(/^(\s*\d+\.\s+)/, `$1[${mark}] `);
+  }
+  loc.lines[item.lineIndex] = next;
+  return { text: loc.lines.join("\n"), summary: `set-criterion ${n}: ${mark}` };
+}
+
+// replace-criterion <n>: <text> — replace the prose of criterion n (keeping
+// its "n. " numbering).
+export function replaceCriterion(text, n, value) {
+  const loc = locateCriteria(text);
+  if (!loc) return { error: "replace-criterion: spec has no '## Acceptance criteria' section" };
+  const item = loc.items.find((it) => it.n === n);
+  if (!item) return { error: `replace-criterion: no criterion #${n} found` };
+  loc.lines[item.lineIndex] = `${item.indent}${n}. ${value}`;
+  return { text: loc.lines.join("\n"), summary: `replace-criterion ${n}` };
+}
+
+// append-criterion <text> — add a new numbered criterion after the last one
+// in the section.
+export function appendCriterion(text, value) {
+  const loc = locateCriteria(text);
+  if (!loc) return { error: "append-criterion: spec has no '## Acceptance criteria' section" };
+  if (loc.items.length === 0) {
+    return { error: "append-criterion: no existing numbered criterion to append after" };
+  }
+  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}`);
+  return { text: loc.lines.join("\n"), summary: `append-criterion ${nextN}` };
+}