doctrina-cli 0.4.0 → 0.8.0

package/src/commands/hooks.js

@@ -43,7 +43,9 @@ export async function run(positional, flags) {
   write(target, body, { force: true });
   chmodSync(target, 0o755);
   console.log(c.green("installed") + ` ${relPath(projectRoot, target)}`);
-  console.log(`The hook runs ${c.cyan("doctrina validate")} before each commit.`);
+  console.log(`The hook runs ${c.cyan("doctrina validate --fix")} before each commit:`);
+  console.log(c.gray("  it rebuilds index.json from the tree (healing drift, re-staging it)"));
+  console.log(c.gray("  and still blocks the commit on errors a rebuild cannot heal."));
   return 0;
 }
 
@@ -51,8 +53,12 @@ export const help = `
 Usage: doctrina hooks install [--force]
 
 Install the Doctrina pre-commit hook into .git/hooks/pre-commit.
-The hook runs \`doctrina validate\` and blocks the commit when
-validation reports errors.
+The hook runs \`doctrina validate --fix\`: it regenerates index.json
+from the tree (healing the most common gate failure — a hand-edited
+header that drifted the index — and re-staging the repaired index)
+and still blocks the commit on errors a rebuild cannot heal. Edit the
+installed hook freely; to gate without auto-repair, swap the line for a
+bare \`doctrina validate\`.
 
 Options:
   --force    Overwrite an existing pre-commit hook

package/src/commands/next.js

@@ -58,17 +58,43 @@ export async function run(_positional, _flags) {
     }
   }
 
-  // ADRs stuck in proposed need a human decision.
+  // ADRs stuck in proposed need a human decision; accepted-but-bare ADRs are
+  // the rot the review flagged — a decision with nothing behind it (no Evidence,
+  // no Landed) is drift waiting to be superseded. Surface the proposed ones
+  // first (a pending decision blocks more than a missing stamp).
   const adrDir = path.join(projectRoot, ".doctrina", "decisions");
+  const landNudges = [];
+  const isBareValue = (v) => {
+    const t = (v ?? "").trim();
+    return t === "" || t === "—" || t === "-";
+  };
   for (const f of walk(adrDir)) {
     if (!f.endsWith(".md")) continue;
     const m = path.basename(f).match(/^(\d{4})-/);
     if (!m) continue;
-    const status = listHeader(read(f), "Status");
+    const text = read(f);
+    const status = listHeader(text, "Status");
     if (status && status.toLowerCase() === "proposed") {
       actions.push(`review ADR ${m[1]} (${relPath(projectRoot, f)}): doctrina decision accept ${m[1]}, or supersede it`);
+    } else if (status && status.toLowerCase() === "accepted") {
+      // Bare only when BOTH anchors are empty (Evidence header present-but-bare
+      // and no Landed stamp). An ADR that opts out of Evidence entirely
+      // (header absent) is not nagged.
+      const evidence = listHeader(text, "Evidence");
+      const landed = listHeader(text, "Landed");
+      if (evidence !== null && isBareValue(evidence) && isBareValue(landed)) {
+        landNudges.push(`record what proves ADR ${m[1]}: cite its **Evidence:**, or once it ships, doctrina decision land ${m[1]}`);
+      }
     }
   }
+  for (const n of landNudges) actions.push(n);
+
+  // No procedural memory captured yet, but the history shows a fix-shaped
+  // change — exactly the lesson a skill exists to keep from being relearned
+  // (review §5: the change-0003 "tolerate LLM code fences" case). One gentle
+  // nudge, only when skills are empty, so it never nags a project that opted in.
+  const skillNudge = suggestSkillCapture(projectRoot);
+  if (skillNudge) actions.push(skillNudge);
 
   // Index drift is silent rot; surface it last.
   try {
@@ -95,13 +121,40 @@ export async function run(_positional, _flags) {
   return 0;
 }
 
+// Return a single skill-capture nudge, or null. Fires only when no skill has
+// been written yet (skills/ holds nothing but .gitkeep) AND the archive shows a
+// fix-shaped change whose lesson is the textbook case for a skill. Deterministic
+// pattern match on the archived folder name — a hint, never a decision (ADR 0005).
+const FIX_SHAPED = /(?:^|-)(fix|bug|hotfix|patch|parse|parsing|tolerate|workaround|race|deadlock|flaky|retry|escape|sanitize|sanitise)(?:-|$)/;
+
+function suggestSkillCapture(projectRoot) {
+  const skillsDir = path.join(projectRoot, ".doctrina", "skills");
+  if (isDir(skillsDir)) {
+    const hasSkill = walk(skillsDir).some((f) => f.endsWith(".md"));
+    if (hasSkill) return null; // opted in already — never nag
+  }
+  const archiveDir = path.join(projectRoot, ".doctrina", "changes", "archive");
+  if (!isDir(archiveDir)) return null;
+  for (const name of readdirSync(archiveDir).sort()) {
+    if (!isDir(path.join(archiveDir, name))) continue;
+    const id = name.replace(/^\d{4}-\d{2}-\d{2}-/, "");
+    if (FIX_SHAPED.test(id)) {
+      return `capture a skill from past fixes (e.g. "${id}"): doctrina skill new <slug> — ` +
+        `on-demand procedural memory so the next agent does not relearn it (none exist yet)`;
+    }
+  }
+  return null;
+}
+
 export const help = `
 Usage: doctrina next
 
 Inspect the .doctrina/ tree and print the recommended next workflow
 actions in priority order: open changes (missing proposal, unchecked
 tasks, deltas ready to apply, applied-but-unarchived), ADRs still in
-proposed status, and index drift. Read-only; always exits 0.
+proposed status, accepted ADRs with nothing proving them (cite Evidence
+or run "decision land"), a skill-capture nudge when a past fix went
+uncaptured, and index drift last. Read-only; always exits 0.
 
 Intended use: agents and humans run it to resume work without
 re-reading the whole tree.

package/src/commands/review.js

@@ -0,0 +1,177 @@
+import path from "node:path";
+import process from "node:process";
+import { spawnSync } from "node:child_process";
+import { readdirSync } from "node:fs";
+import { exists, isDir, isFile, read } from "../lib/fs-ops.js";
+import { flagBool, flagString } from "../lib/args.js";
+import { c } from "../lib/colors.js";
+import { rankCapabilitiesByDiff } from "./work.js";
+import { summarize as coverageSummary } from "./coverage.js";
+import { summarize as traceSummary } from "./trace.js";
+
+// Deterministic conformance review (review 2026-06-27 passive-user feature #3).
+// Given the working tree (or a diff against a ref), report STRUCTURAL breaks
+// between the change and the spec/ADR/contract tree, so the agent self-reviews
+// before bringing work to the human and the human's approval is one command.
+//
+// It checks links and conformance shape, NOT semantic fidelity — whether the
+// code actually does what the spec says stays a human/LLM call, the same honest
+// ceiling as `trace`/`clarify` (ADR 0005). Read-only; exits 0 as a report, 1
+// under --strict when any break exists (CI gate).
+
+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 strict = flagBool(flags, "strict", false);
+  const against = flagString(flags, "diff"); // optional git ref to diff against
+
+  const { all, sourceFiles } = changedFiles(projectRoot, against);
+  console.log(c.bold("Review") + c.gray(against ? ` — vs ${against}` : " — working-tree changes"));
+  console.log("");
+
+  if (all.length === 0) {
+    console.log(c.gray(against
+      ? `no changes between ${against} and the working tree`
+      : "no working-tree changes to review (stage or edit code first, or pass --diff <ref>)"));
+    return 0;
+  }
+
+  const breaks = []; // hard conformance breaks (fail --strict)
+  const notes = [];  // advisory observations
+
+  // 1. Code changed under a capability whose spec was NOT touched — the spec
+  //    may have drifted from the code it describes.
+  const specChanged = new Set(
+    all.filter((f) => /(^|\/)\.doctrina\/specs\/[^/]+\/spec\.md$/.test(f.replace(/\\/g, "/")))
+      .map((f) => f.replace(/\\/g, "/").match(/\.doctrina\/specs\/([^/]+)\/spec\.md$/)[1]),
+  );
+  const ranked = rankCapabilitiesByDiff(projectRoot, sourceFiles);
+  for (const m of ranked) {
+    if (!specChanged.has(m.id)) {
+      breaks.push(`code under capability "${m.id}" changed, but its spec was not updated — confirm \`.doctrina/specs/${m.id}/spec.md\` still describes the code (update it, or note why not)`);
+    }
+  }
+
+  // 2. New source files that map to no capability at all — code with no home
+  //    in any spec (a likely new, unspecced capability).
+  if (ranked.length === 0 && sourceFiles.length > 0) {
+    notes.push(`changed code maps to no existing capability spec — if this is a new capability, scaffold it: \`doctrina spec new <capability>\` (or \`doctrina work --from-diff\`)`);
+  }
+
+  // 3. Coverage — acceptance criteria whose cited proof is missing/skipped.
+  const cov = coverageSummary(projectRoot);
+  if (cov.totalDangling > 0) {
+    breaks.push(`${cov.totalDangling} acceptance criterion(s) cite evidence missing on disk (\`doctrina coverage\`)`);
+  }
+  if (cov.totalConditional > 0) {
+    notes.push(`${cov.totalConditional} acceptance criterion(s) proven only by a skipped test (\`doctrina coverage\`)`);
+  }
+  if (cov.totalCriteria > 0 && cov.totalCovered < cov.totalCriteria - cov.totalDangling - cov.totalConditional) {
+    notes.push(`coverage is ${cov.pct}% (${cov.totalCovered}/${cov.totalCriteria}) — uncovered criteria carry no proof`);
+  }
+
+  // 4. Trace — product intent that no spec realizes, or specs realizing nothing.
+  const tr = traceSummary(projectRoot);
+  if (tr.dropped > 0) breaks.push(`${tr.dropped} product intent anchor(s) are realized by no spec (\`doctrina trace\`)`);
+  if (tr.untraceable > 0) notes.push(`${tr.untraceable} active spec(s) trace to no product intent (\`doctrina trace\`)`);
+
+  // 5. Contract surface — port collisions / env drift / dangling spec refs.
+  const contractIssues = runContractCheck(projectRoot);
+  for (const issue of contractIssues) breaks.push(issue);
+
+  // --- Output ---
+  console.log(c.gray(`${all.length} changed path(s); ${sourceFiles.length} source file(s) outside .doctrina/.`));
+  if (ranked.length > 0) {
+    console.log(c.gray("Capabilities touched: ") + ranked.map((m) => c.cyan(m.id)).join(", "));
+  }
+  console.log("");
+
+  if (breaks.length === 0 && notes.length === 0) {
+    console.log(c.green("ok") + " no structural conformance breaks found");
+  } else {
+    for (const b of breaks) console.log(`  ${c.red("✗")} ${b}`);
+    for (const n of notes) console.log(`  ${c.yellow("!")} ${n}`);
+    console.log("");
+    const summary = `${breaks.length} break${breaks.length === 1 ? "" : "s"}, ${notes.length} note${notes.length === 1 ? "" : "s"}`;
+    const status = breaks.length === 0 ? c.green("ok") : (strict ? c.red("fail") : c.yellow("gap"));
+    console.log(status + " " + summary);
+  }
+
+  console.log("");
+  console.log(c.gray("Structural review only — whether the code is FAITHFUL to the spec is a human/LLM call."));
+  return strict && breaks.length > 0 ? 1 : 0;
+}
+
+// Changed paths between a base (a git ref, or HEAD + untracked for the working
+// tree) and now. Returns the full list and the subset outside .doctrina/.
+function changedFiles(projectRoot, against) {
+  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();
+  if (against) {
+    for (const f of run(["diff", "--name-only", against])) set.add(f);
+  } else {
+    for (const f of run(["diff", "--name-only", "HEAD"])) set.add(f);
+    for (const f of run(["ls-files", "--others", "--exclude-standard"])) set.add(f);
+  }
+  const all = [...set];
+  const sourceFiles = all.filter((f) => !f.replace(/\\/g, "/").startsWith(".doctrina/"));
+  return { all, sourceFiles };
+}
+
+// Light re-detection of the two contract breaks that matter to a review — a
+// port claimed by two contracts, and a referenced spec that does not exist. The
+// full contract gate stays `doctrina contract check`; this keeps review
+// self-contained without spawning it.
+function runContractCheck(projectRoot) {
+  const issues = [];
+  const contractsDir = path.join(projectRoot, ".doctrina", "contracts");
+  if (!isDir(contractsDir)) return issues;
+  const specsDir = path.join(projectRoot, ".doctrina", "specs");
+  const ports = new Map(); // port -> contract id
+  for (const f of readdirSync(contractsDir)) {
+    if (!f.endsWith(".md")) continue;
+    const id = path.basename(f, ".md");
+    const text = read(path.join(contractsDir, f));
+    for (const m of text.matchAll(/`?(\d{2,5})`?\s*\|/g)) {
+      const port = m[1];
+      if (Number(port) >= 1 && Number(port) <= 65535) {
+        if (ports.has(port) && ports.get(port) !== id) {
+          issues.push(`contract port ${port} is claimed by both "${ports.get(port)}" and "${id}" (\`doctrina contract check\`)`);
+        } else {
+          ports.set(port, id);
+        }
+      }
+    }
+    for (const m of text.matchAll(/\.doctrina\/specs\/([a-z0-9-]+)\//g)) {
+      const cap = m[1];
+      if (!isFile(path.join(specsDir, cap, "spec.md"))) {
+        issues.push(`contract "${id}" references spec "${cap}" which does not exist (\`doctrina contract check\`)`);
+      }
+    }
+  }
+  return issues;
+}
+
+export const help = `
+Usage: doctrina review [--diff <ref>] [--strict]
+
+Deterministic conformance review of your changes against the spec / ADR /
+contract tree. By default it reviews the working-tree changes (tracked +
+untracked); with --diff <ref> it reviews everything that differs from a git
+ref (e.g. \`doctrina review --diff main\`).
+
+Reports structural breaks: code changed under a capability whose spec was
+not updated, changed code that maps to no capability, acceptance criteria
+citing missing proof, product intent realized by no spec, and contract
+port/reference collisions. It checks conformance shape, NOT semantic
+fidelity (whether the code does what the spec says stays a human/LLM call).
+
+Read-only. Exits 0 as a report; with --strict, exits 1 when any hard break
+exists (CI gate). Notes (advisory) never fail the gate.
+`;

package/src/commands/skill.js

@@ -1,6 +1,7 @@
 import path from "node:path";
 import process from "node:process";
-import { exists, isDir, mkdirp, read, relPath, walk, write } from "../lib/fs-ops.js";
+import { readdirSync } from "node:fs";
+import { exists, isDir, isFile, mkdirp, read, relPath, walk, write } from "../lib/fs-ops.js";
 import { locateTemplatesDir, substitute } from "../lib/templates.js";
 import * as idx from "../lib/index-json.js";
 import { today } from "../lib/dates.js";
@@ -8,7 +9,7 @@ import { flagBool } from "../lib/args.js";
 import { c } from "../lib/colors.js";
 import { suggest } from "../lib/suggest.js";
 
-const SUBCOMMANDS = ["new", "list", "sync"];
+const SUBCOMMANDS = ["new", "list", "sync", "suggest"];
 
 export async function run(positional, flags) {
   const sub = positional[0];
@@ -22,9 +23,114 @@ export async function run(positional, flags) {
   }
   if (sub === "new") return skillNew(positional.slice(1), flags);
   if (sub === "sync") return skillSync();
+  if (sub === "suggest") return skillSuggest(positional.slice(1), flags);
   return skillList();
 }
 
+// Surface (and optionally scaffold) skills worth capturing (review 2026-06-27
+// passive-user feature #6). A skill exists so a hard-won lesson is not relearned
+// by the next agent/session; the framework otherwise never pulls you toward
+// writing one. `skill suggest` scans the archived changes for fix-shaped work —
+// the textbook case for a skill — and lists candidates whose lesson is not yet
+// captured. With --write it scaffolds a stub per candidate, pre-seeded from the
+// change so the human/agent only fills the body. Deterministic pattern match on
+// the archived folder name — a hint, never a decision (ADR 0005).
+const FIX_SHAPED = /(?:^|-)(fix|bug|hotfix|patch|parse|parsing|tolerate|workaround|race|deadlock|flaky|retry|escape|sanitize|sanitise)(?:-|$)/;
+
+function skillSuggest(args, flags) {
+  const projectRoot = process.cwd();
+  ensureDoctrinaProject(projectRoot);
+  const doWrite = flagBool(flags, "write", false);
+
+  const archiveDir = path.join(projectRoot, ".doctrina", "changes", "archive");
+  const skillsDir = path.join(projectRoot, ".doctrina", "skills");
+  const existing = new Set(
+    isDir(skillsDir) ? walk(skillsDir).filter((f) => f.endsWith(".md")).map((f) => path.basename(f, ".md")) : [],
+  );
+
+  const candidates = [];
+  if (isDir(archiveDir)) {
+    for (const name of readdirSync(archiveDir).sort()) {
+      if (!isDir(path.join(archiveDir, name))) continue;
+      const id = name.replace(/^\d{4}-\d{2}-\d{2}-/, "");
+      if (!FIX_SHAPED.test(id)) continue;
+      const slug = skillSlug(id);
+      if (existing.has(slug)) continue; // lesson already captured
+      const proposal = path.join(archiveDir, name, "proposal.md");
+      const why = isFile(proposal) ? firstWhyLine(read(proposal)) : "";
+      candidates.push({ id, slug, why, archive: name });
+    }
+  }
+
+  if (candidates.length === 0) {
+    console.log(c.gray("no uncaptured fix-shaped lessons found in .doctrina/changes/archive/"));
+    console.log(c.gray("(skills are written by humans; this only surfaces candidates — `doctrina skill new <slug>` to author one)"));
+    return 0;
+  }
+
+  if (!doWrite) {
+    console.log(c.bold("Skill candidates") + c.gray(" — fix-shaped lessons not yet captured:"));
+    console.log("");
+    for (const cand of candidates) {
+      console.log(`  ${c.cyan(cand.slug.padEnd(28))} ${c.gray("from " + cand.archive)}`);
+      if (cand.why) console.log(`    ${c.gray(cand.why.slice(0, 90))}`);
+    }
+    console.log("");
+    console.log(c.gray(`${candidates.length} candidate${candidates.length === 1 ? "" : "s"}. Scaffold them: `) + c.cyan("doctrina skill suggest --write"));
+    return 0;
+  }
+
+  // --write: scaffold a stub per candidate, pre-seeded from the change.
+  const templatesDir = locateTemplatesDir();
+  const tplPath = path.join(templatesDir, "skill.md.template");
+  const tpl = read(tplPath);
+  mkdirp(skillsDir);
+  const index = idx.load(projectRoot);
+  const date = today();
+  let created = 0;
+  for (const cand of candidates) {
+    const target = path.join(skillsDir, `${cand.slug}.md`);
+    if (exists(target)) {
+      console.log(c.yellow("skip   ") + ` ${cand.slug} (already exists)`);
+      continue;
+    }
+    let body = substitute(tpl, { SKILL_NAME: cand.slug });
+    if (cand.why) {
+      // Drop the originating lesson into the body so authoring is "fill", not "start".
+      body += `\n<!-- Candidate from change "${cand.id}". The lesson to capture:\n${cand.why}\n-->\n`;
+    }
+    write(target, body, { force: false });
+    idx.addSkill(index, {
+      id: cand.slug,
+      path: `.doctrina/skills/${cand.slug}.md`,
+      description: parseFrontmatter(body, "description") ?? "<edit me — one-sentence summary>",
+      last_updated: date,
+    });
+    console.log(c.green("created") + ` ${relPath(projectRoot, target)}`);
+    created += 1;
+  }
+  if (created > 0) {
+    idx.touch(index, date);
+    idx.save(projectRoot, index);
+  }
+  console.log("");
+  console.log(c.green("ok") + ` scaffolded ${created} skill stub${created === 1 ? "" : "s"} — fill the description/when/body, then \`doctrina skill sync\``);
+  return 0;
+}
+
+function skillSlug(id) {
+  // Reuse the change id as the skill slug, trimmed to a sane length.
+  const slug = id.replace(/[^a-z0-9-]+/g, "-").replace(/^-+|-+$/g, "");
+  return slug.length > 40 ? slug.slice(0, 40).replace(/-+$/g, "") : (slug || "lesson");
+}
+
+function firstWhyLine(proposalText) {
+  const m = proposalText.match(/##\s*Why\s*\r?\n+([^\r\n][^\r\n]*)/i);
+  if (!m) return "";
+  const line = m[1].trim();
+  return /^<!--/.test(line) ? "" : line;
+}
+
 function skillNew(args, flags) {
   const name = args[0];
   if (!name || !/^[a-z][a-z0-9-]*$/.test(name)) {
@@ -176,6 +282,10 @@ Subcommands:
   sync          Copy each skill's frontmatter description into
                 .doctrina/index.json so the index never drifts
                 from the frontmatter (single source of truth).
+  suggest [--write]
+                Surface fix-shaped lessons in the change archive whose
+                skill is not yet captured. --write scaffolds a stub per
+                candidate (pre-seeded from the change) to fill in.
 
 Skills are written by humans, not generated. See docs/en/skills.md
 for the design rationale and the distinction from specs / AGENTS.md /

package/src/commands/spec.js

@@ -3,14 +3,15 @@ import process from "node:process";
 import { readdirSync } from "node:fs";
 import { exists, isDir, isFile, lineCount, read, relPath, write } from "../lib/fs-ops.js";
 import { locateTemplatesDir, substitute } from "../lib/templates.js";
-import { specHeader } from "../lib/scan.js";
+import { specHeader, deriveIndex } from "../lib/scan.js";
+import { setHeader, bumpVersion, setCriterionMark } from "../lib/spec-ops.js";
 import * as idx from "../lib/index-json.js";
 import { today } from "../lib/dates.js";
-import { flagBool } from "../lib/args.js";
+import { flagBool, flagString } from "../lib/args.js";
 import { c } from "../lib/colors.js";
 import { suggest } from "../lib/suggest.js";
 
-const SUBCOMMANDS = ["new", "list"];
+const SUBCOMMANDS = ["new", "list", "set"];
 
 export async function run(positional, flags) {
   const sub = positional[0];
@@ -23,6 +24,7 @@ export async function run(positional, flags) {
     return 2;
   }
   if (sub === "list") return specList();
+  if (sub === "set") return specSet(positional.slice(1), flags);
 
   const capability = positional[1];
   if (!capability || !/^[a-z][a-z0-9-]*$/.test(capability)) {
@@ -109,6 +111,82 @@ function specList() {
   return 0;
 }
 
+// Edit a spec's bookkeeping headers (and a criterion mark) and resync the
+// index in one step — the inverse drift footgun the review hit (G8): a manual
+// "bump the version in the spec, then bump it again in index.json" lockstep.
+// Reuses the same structured ops as `change apply` (ADR 0007), so the header
+// and the index can never diverge after a `spec set`.
+function specSet(args, flags) {
+  const capability = args[0];
+  if (!capability || !/^[a-z][a-z0-9-]*$/.test(capability)) {
+    console.error(c.red("error:") + " spec set requires a <capability> (lowercase letters, digits, hyphens)");
+    return 2;
+  }
+  const projectRoot = process.cwd();
+  ensureDoctrinaProject(projectRoot);
+
+  const specPath = path.join(projectRoot, ".doctrina", "specs", capability, "spec.md");
+  if (!isFile(specPath)) {
+    console.error(c.red("error:") + ` no spec at ${relPath(projectRoot, specPath)} (create it with \`doctrina spec new ${capability}\`)`);
+    return 1;
+  }
+
+  const impl = flagString(flags, "implementation");
+  const status = flagString(flags, "status");
+  const bump = flagString(flags, "bump");
+  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");
+    console.error(c.gray("hint: ") + `example: doctrina spec set ${capability} --implementation "verified — \`src/x.js\`" --bump minor`);
+    return 2;
+  }
+
+  let text = read(specPath);
+  const applied = [];
+  const errors = [];
+  const apply = (res) => {
+    if (res.error) errors.push(res.error);
+    else { text = res.text; applied.push(res.summary); }
+  };
+  // Order: headers, then version, then criterion — independent edits, all or
+  // none (a failed op leaves the spec untouched, like `change apply`).
+  if (status !== undefined) apply(setHeader(text, "Status", status));
+  if (impl !== undefined) apply(setHeader(text, "Implementation", impl));
+  if (bump !== undefined) {
+    if (!["major", "minor", "patch"].includes(bump)) errors.push(`--bump needs major|minor|patch (got "${bump}")`);
+    else apply(bumpVersion(text, bump));
+  }
+  if (criterion !== undefined) {
+    const m = String(criterion).match(/^(\d+)\s*:\s*(.+)$/);
+    if (!m) errors.push(`--criterion needs "<n>:<mark>" (got "${criterion}")`);
+    else apply(setCriterionMark(text, Number(m[1]), m[2].trim()));
+  }
+
+  if (errors.length > 0) {
+    console.error(c.red("error:") + ` ${errors.length} operation error${errors.length === 1 ? "" : "s"} — spec left untouched:`);
+    for (const e of errors) console.error(`  - ${e}`);
+    return 1;
+  }
+
+  // Stamp Last updated when the header exists (best-effort, never an error).
+  const date = today();
+  const lu = setHeader(text, "Last updated", date);
+  if (!lu.error) text = lu.text;
+
+  write(specPath, text, { force: true });
+  console.log(c.green("updated") + ` ${relPath(projectRoot, specPath)}`);
+  for (const s of applied) console.log(c.gray(`    · ${s}`));
+
+  // Single source of truth: regenerate the index from the now-updated tree so
+  // the spec headers and the index can never drift (no manual lockstep — G8).
+  const index = idx.load(projectRoot);
+  const derived = deriveIndex(projectRoot, index);
+  derived.last_updated = date;
+  idx.save(projectRoot, derived);
+  console.log(c.green("indexed") + ` spec "${capability}" synced`);
+  return 0;
+}
+
 function ensureDoctrinaProject(projectRoot) {
   if (!exists(path.join(projectRoot, ".doctrina"))) {
     throw new Error("not a Doctrina project (no .doctrina/ in cwd). Run `doctrina init` first.");
@@ -125,9 +203,17 @@ Subcommands:
   list                                 One line per spec: id, version,
                                        status, line count, last updated.
                                        Read-only.
+  set <capability> [opts]              Edit a spec's headers / a criterion
+                                       mark and resync the index in one step
+                                       (no manual lockstep bump — G8).
 
 Options:
-  --bug      Scaffold the bug-shape template (current / expected /
-             unchanged behaviour) instead of the EARS capability spec.
-  --force    Overwrite an existing spec.
+  --bug                  Scaffold the bug-shape template (current / expected /
+                         unchanged behaviour) instead of the EARS capability spec.
+  --force                Overwrite an existing spec (with \`new\`).
+  --implementation "..." With \`set\`: set the Implementation header.
+  --status "..."         With \`set\`: set the Status header.
+  --bump major|minor|patch  With \`set\`: bump the spec Version.
+  --criterion "<n>:<mark>"  With \`set\`: set criterion n's [mark]
+                         (e.g. --criterion "2:verified").
 `;