doctrina-cli 0.17.0 → 0.18.0

package/src/lib/skill-candidates.js

@@ -0,0 +1,162 @@
+// @ts-check
+import path from "node:path";
+import { readdirSync } from "node:fs";
+import { isDir, isFile, read, walk } from "./fs-ops.js";
+import { git, GIT_STATE } from "./git.js";
+import { FIX_SHAPED, FIX_SHAPED_SUBJECT, skillSlug } from "./lexicon.js";
+
+// The lessons worth a skill, as DATA (change 0202). `skill suggest` listed
+// them and `close` printed that whole listing at the end of every close —
+// the same thirteen candidates, close after close, which a field review of
+// 0.17 called noise. The close now asks for the list and renders only what
+// THIS close produced, so the collection lives here, where both read it
+// (ADR 0025: commands render, lib decides).
+
+/**
+ * @typedef {object} SkillCandidate
+ * @property {string} id
+ * @property {string} slug
+ * @property {"change"|"commit"} source
+ * @property {string} [from]  archive folder name, for a change candidate
+ * @property {string} [ref]   short sha, for a commit candidate
+ * @property {string} [why]
+ */
+
+/**
+ * Fix-shaped lessons not yet captured as a skill, from the archive and the
+ * git history, deduped by slug.
+ *
+ * @param {string} projectRoot
+ * @param {{ since?: string, limit?: number }} [opts]
+ * @returns {SkillCandidate[]}
+ */
+export function skillCandidates(projectRoot, { since, limit = 200 } = {}) {
+  const skillsDir = path.join(projectRoot, ".doctrina", "skills");
+  const existingFiles = isDir(skillsDir) ? walk(skillsDir).filter((f) => f.endsWith(".md")) : [];
+  const existing = new Set(existingFiles.map((f) => path.basename(f, ".md")));
+  // A lesson may already be captured under a DIFFERENT slug (0.11.0 field
+  // review item 11: the human names the skill after the lesson, not after the
+  // change id — "tela-preta-crash-de-render..." for change 0049). Two extra
+  // dedup signals: an existing skill whose body cites the candidate's change
+  // id / commit hash, and token-overlap similarity between the slugs.
+  const existingBodies = existingFiles.map((f) => ({ slug: path.basename(f, ".md"), body: read(f) }));
+  const captured = (cand) => {
+    if (existing.has(cand.slug)) return true;
+    for (const sk of existingBodies) {
+      if (cand.id && sk.body.includes(cand.id)) return true;
+      if (cand.from && sk.body.includes(cand.from)) return true;
+      if (slugSimilarity(cand.slug, sk.slug) >= 0.5) return true;
+    }
+    return false;
+  };
+
+  // Two deterministic sources, deduped by slug. `seen` guards against a lesson
+  // appearing twice (e.g. a fix committed and later archived as a change).
+  /** @type {SkillCandidate[]} */
+  const candidates = [];
+  const seen = new Set();
+
+  // Source 1 — archived change proposals with a fix-shaped folder name.
+  const archiveDir = path.join(projectRoot, ".doctrina", "changes", "archive");
+  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 (seen.has(slug)) continue;
+      /** @type {SkillCandidate} */
+      const cand = { id, slug, source: "change", from: name };
+      if (captured(cand)) continue; // captured (any slug) or cited by an existing skill
+      const proposal = path.join(archiveDir, name, "proposal.md");
+      cand.why = isFile(proposal) ? firstWhyLine(read(proposal)) : "";
+      seen.add(slug);
+      candidates.push(cand);
+    }
+  }
+
+  // Source 2 — fix-shaped commits in the git history (ADR 0013). Archive wins a
+  // slug collision: a `## Why` paragraph is a richer seed than a subject line.
+  for (const cand of gitFixCommits(projectRoot, { since, limit })) {
+    if (seen.has(cand.slug) || captured(cand)) continue;
+    seen.add(cand.slug);
+    candidates.push(cand);
+  }
+
+  return candidates;
+}
+
+// Source 2 for `skill suggest`: fix-shaped commits in the git history (ADR
+// 0013). Deterministic — a regex on the subject, never a read of the diff
+// (ADR 0005 semantic-fidelity ceiling). Returns [] silently when this is not a
+// git repo, git is absent, or the --since ref is unknown, so the command
+// degrades to archive-only rather than erroring.
+function gitFixCommits(projectRoot, { since, limit }) {
+  // US (0x1f) between fields, RS (0x1e) between records — robust against any
+  // newline or punctuation inside a subject or body.
+  const format = "%H%x1f%s%x1f%b%x1e";
+  const args = ["log", "--no-merges", `--format=${format}`];
+  if (since) args.push(`${since}..HEAD`);
+  else args.push("-n", String(limit));
+
+  const r = git(projectRoot, args);
+  if (r.state !== GIT_STATE.OK || !r.stdout) return [];
+
+  /** @type {SkillCandidate[]} */
+  const out = [];
+  const seen = new Set();
+  for (const record of r.stdout.split("\x1e")) {
+    const [sha, subject = "", body = ""] = record.replace(/^\r?\n/, "").split("\x1f");
+    if (!sha || !sha.trim()) continue;
+    if (!FIX_SHAPED_SUBJECT.test(subject)) continue;
+    const slug = commitSlug(subject);
+    if (!slug || seen.has(slug)) continue; // first commit wins a duplicate lesson
+    seen.add(slug);
+    const firstBodyLine = body.split(/\r?\n/).map((l) => l.trim()).find(Boolean) ?? "";
+    out.push({
+      id: slug,
+      slug,
+      source: "commit",
+      ref: sha.trim().slice(0, 9),
+      why: subject.trim() + (firstBodyLine ? ` — ${firstBodyLine}` : ""),
+    });
+  }
+  return out;
+}
+
+// Derive a skill slug from a commit subject: drop a conventional-commit
+// "type(scope): " prefix and hand the rest to the shared slug, which folds.
+function commitSlug(subject) {
+  return skillSlug(subject.replace(/^[a-z]+(?:\([^)]*\))?!?\s*:\s*/i, ""));
+}
+
+// Token-overlap similarity between two kebab slugs (Jaccard over meaningful
+// tokens). "0049-fix-tela-preta-render" vs "tela-preta-crash-de-render-sem-
+// error-boundary" share tela/preta/render → high overlap even though the
+// human renamed the skill after the lesson. Deterministic; never semantic.
+function slugSimilarity(a, b) {
+  const toks = (s) => new Set(
+    String(s).split("-").filter((t) => t.length >= 3 && !/^\d+$/.test(t) && !SLUG_NOISE.has(t)),
+  );
+  const A = toks(a);
+  const B = toks(b);
+  if (A.size === 0 || B.size === 0) return 0;
+  let inter = 0;
+  for (const t of A) if (B.has(t)) inter += 1;
+  return inter / (A.size + B.size - inter);
+}
+
+// Fix-shaped verbs and connectives carry no lesson identity — without this,
+// every "fix-..." candidate looks 30% similar to every "fix-..." skill.
+const SLUG_NOISE = new Set([
+  "fix", "bug", "hotfix", "patch", "the", "and", "for", "with", "sem", "com",
+  "que", "nao", "por", "para", "una", "uma", "dos", "das",
+]);
+
+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;
+}
+

package/src/lib/snapshot.js

@@ -15,6 +15,7 @@ import { parseChangeTitle, checklistProgress } from "./doc-model.js";
 import { summarizeSignoffs } from "./signoff.js";
 import { gitWindow, historyState, windowCutoff } from "./git.js";
 import { collectMetrics } from "./metrics-model.js";
+import { today } from "./dates.js";
 
 // ONE collector, several views (audit finding F7).
 //
@@ -149,11 +150,47 @@ export function openChanges(projectRoot) {
     const tasksTotal = progress.total;
     const tasksDone = progress.done;
     const unchecked = progress.open.map((t) => t || "(unwritten task — the scaffold's placeholder)");
-    out.push({ id, title, status, tasksDone, tasksTotal, unchecked });
+    const date = proposal ? (listHeader(proposal, "Date") ?? null) : null;
+    out.push({ id, title, status, tasksDone, tasksTotal, unchecked, date, ageDays: ageInDays(date) });
   }
   return out;
 }
 
+// How old a change has to be before "still open" is worth saying on its own.
+export const STALE_CHANGE_DAYS = 7;
+
+/**
+ * The open changes worth a line at the end of someone else's close (change
+ * 0201): a change that LOOKS finished — applied, or every task ticked — and
+ * was never closed, and a change open for a week or more. A field review of
+ * 0.17 found change 0078 shipped and left open, and no later close said so:
+ * the close is the moment someone is looking, so it is where to say it.
+ *
+ * @param {string} projectRoot
+ * @param {{ exclude?: string[] }} [opts]
+ */
+export function unfinishedChanges(projectRoot, { exclude = [] } = {}) {
+  const skip = new Set(exclude);
+  const out = [];
+  for (const ch of openChanges(projectRoot)) {
+    if (skip.has(ch.id)) continue;
+    const finished = ch.status === "applied" ||
+      (ch.tasksTotal > 0 && ch.tasksDone === ch.tasksTotal);
+    const old = ch.ageDays !== null && ch.ageDays >= STALE_CHANGE_DAYS;
+    const reason = ch.status === "applied"
+      ? "applied but never closed"
+      : finished ? "every task ticked, never closed" : old ? "still open" : null;
+    out.push({ ...ch, finished, old, reason });
+  }
+  return out;
+}
+
+function ageInDays(date) {
+  if (!date || !/^\d{4}-\d{2}-\d{2}$/.test(date)) return null;
+  const ms = Date.parse(`${today()}T00:00:00Z`) - Date.parse(`${date}T00:00:00Z`);
+  return Number.isFinite(ms) ? Math.max(0, Math.round(ms / 86400000)) : null;
+}
+
 function countSpecs(projectRoot) {
   const specsDir = path.join(projectRoot, ".doctrina", "specs");
   const impl = {};

package/src/lib/spec-ops.js

@@ -117,6 +117,40 @@ function matchOpsBlock(text) {
   return null;
 }
 
+/** One op line, parsed by the grammar `apply` reads: `{ verb, ... }` or `{ verb, error }`. */
+export function parseOp(line) {
+  return parseOpLine(String(line).trim());
+}
+
+/**
+ * Append op lines to a delta's live `ops` block — creating the block at the
+ * end when there is none (change 0205). A `bump-version` line replaces the
+ * block's existing one instead of stacking a second bump on it. Pure.
+ *
+ * @param {string} deltaText
+ * @param {string[]} lines  already validated with `parseOp`
+ * @returns {string}
+ */
+export function insertOps(deltaText, lines) {
+  const ranges = commentRanges(deltaText);
+  const fenceRe = /^([ \t]*```[ \t]*ops[ \t]*\r?\n)([\s\S]*?)(^[ \t]*```[ \t]*$)/gm;
+  const bumps = lines.some((l) => parseOp(l).verb === "bump-version");
+  let m;
+  while ((m = fenceRe.exec(deltaText))) {
+    if (isInsideComment(ranges, m.index)) continue;
+    const kept = m[2].split(/\r?\n/).filter((l) => l.trim() !== "")
+      .filter((l) => !(bumps && parseOp(l).verb === "bump-version"));
+    // The bump goes last, where a reader looks for it.
+    const ordered = [...kept, ...lines].sort((a, b) =>
+      Number(parseOp(a).verb === "bump-version") - Number(parseOp(b).verb === "bump-version"));
+    const block = `${m[1]}${ordered.join("\n")}\n${m[3]}`;
+    return deltaText.slice(0, m.index) + block + deltaText.slice(m.index + m[0].length);
+  }
+  const ordered = [...lines].sort((a, b) =>
+    Number(parseOp(a).verb === "bump-version") - Number(parseOp(b).verb === "bump-version"));
+  return `${deltaText.replace(/\s*$/, "")}\n\n\`\`\`ops\n${ordered.join("\n")}\n\`\`\`\n`;
+}
+
 function parseOpLine(line) {
   // `<verb> <rest>` — the verb is the first whitespace-delimited token.
   const sp = line.indexOf(" ");
@@ -178,6 +212,24 @@ function parseOpLine(line) {
       if (!value) return { verb, error: `replace-requirement ${n} is missing the requirement text` };
       return { verb, section, n, value };
     }
+    case "remove-requirement": {
+      // remove-requirement <section> <n>[: <why>] — the reason is for the
+      // reader of the delta; the spec loses the bullet either way.
+      const colon = rest.indexOf(":");
+      const head = (colon < 0 ? rest : rest.slice(0, colon)).trim().split(/\s+/);
+      const n = Number(head[head.length - 1]);
+      const section = normalizeSection(head.slice(0, -1).join(" "));
+      if (!section) return { verb, error: `remove-requirement: unknown section "${head.slice(0, -1).join(" ")}" (use ${SECTION_TOKENS})` };
+      if (!Number.isInteger(n) || n < 1) return { verb, error: `remove-requirement needs "<section> <n>" with a positive bullet number (got "${rest}")` };
+      return { verb, section, n };
+    }
+    case "remove-criterion": {
+      // remove-criterion <n>[: <why>]
+      const colon = rest.indexOf(":");
+      const n = Number((colon < 0 ? rest : rest.slice(0, colon)).trim());
+      if (!Number.isInteger(n) || n < 1) return { verb, error: `remove-criterion needs a positive criterion number (got "${rest}")` };
+      return { verb, n };
+    }
     default:
       return { verb: null, error: `unknown operation "${verb}"` };
   }
@@ -238,6 +290,10 @@ function applyOne(text, op) {
       return appendRequirement(text, op.section, op.value);
     case "replace-requirement":
       return replaceRequirement(text, op.section, op.n, op.value);
+    case "remove-requirement":
+      return removeRequirement(text, op.section, op.n);
+    case "remove-criterion":
+      return removeCriterion(text, op.n);
     default:
       return { error: `unknown operation "${op.verb}"` };
   }
@@ -334,10 +390,33 @@ export function replaceCriterion(text, n, value) {
   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}`;
+  // The whole item, continuation lines included (change 0206) — the lesson
+  // `replace-requirement` learned, which this verb never picked up: a
+  // criterion wrapped over three lines kept its old second and third lines
+  // under the new first one, so the spec stated a proof and then the
+  // previous proof's tail.
+  loc.lines.splice(item.lineIndex, endOfItem(loc.lines, item.lineIndex) - item.lineIndex + 1, `${item.indent}${n}. ${value}`);
   return { text: loc.lines.join("\n"), summary: `replace-criterion ${n}` };
 }
 
+// remove-criterion <n> — delete criterion n, continuation lines included,
+// and renumber the ones after it so the list stays 1..N (change 0206). A
+// spec only ever grew: there was no verb to take a criterion out, so a
+// superseded one stayed beside its replacement for good.
+export function removeCriterion(text, n) {
+  const loc = locateCriteria(text);
+  if (!loc) return { error: "remove-criterion: spec has no '## Acceptance criteria' section" };
+  const item = loc.items.find((it) => it.n === n);
+  if (!item) return { error: `remove-criterion: no criterion #${n} found` };
+  const end = endOfItem(loc.lines, item.lineIndex);
+  const lines = loc.lines;
+  for (const it of loc.items) {
+    if (it.n > n) lines[it.lineIndex] = lines[it.lineIndex].replace(/^(\s*)\d+\./, `$1${it.n - 1}.`);
+  }
+  lines.splice(item.lineIndex, end - item.lineIndex + 1);
+  return { text: lines.join("\n"), summary: `remove-criterion ${n} (${loc.items.length - n} renumbered)` };
+}
+
 // 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
@@ -505,6 +584,23 @@ export function replaceRequirement(text, section, n, value) {
   return { text: loc.lines.join("\n"), summary: `replace-requirement ${section} ${n}` };
 }
 
+// remove-requirement <section> <n> — delete the nth bullet (1-based) of the
+// EARS subsection, continuation lines included (change 0206). The heading
+// stays even when it empties: `append-requirement` can fill it again.
+export function removeRequirement(text, section, n) {
+  const loc = locateRequirements(text);
+  if (!loc) return { error: "remove-requirement: spec has no '## Requirements (EARS)' section" };
+  const sec = loc.sections[section];
+  if (!sec) return { error: `remove-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: `remove-requirement: section "${section}" has ${real.length} requirement${real.length === 1 ? "" : "s"}, no #${n}` };
+  }
+  const start = real[n - 1];
+  loc.lines.splice(start, endOfItem(loc.lines, start) - start + 1);
+  return { text: loc.lines.join("\n"), summary: `remove-requirement ${section} ${n}` };
+}
+
 // append-criterion <text> — add a new numbered criterion after the last one
 // in the section.
 export function appendCriterion(text, value) {
@@ -523,3 +619,23 @@ export function appendCriterion(text, 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}` };
 }
+
+/**
+ * The size of a spec, as `work --consolidate` reports it (change 0206):
+ * lines, real requirement bullets per EARS subsection, and criteria.
+ * @param {string} text
+ */
+export function specShape(text) {
+  const req = locateRequirements(text);
+  const sections = {};
+  let requirements = 0;
+  for (const token of EARS_ORDER) {
+    const sec = req?.sections[token];
+    if (!sec) continue;
+    const n = sec.bullets.filter((i) => !/^\s*-\s*$/.test(req.lines[i])).length;
+    sections[token] = n;
+    requirements += n;
+  }
+  const crit = locateCriteria(text);
+  return { lines: text.split(/\r?\n/).length, requirements, sections, criteria: crit ? crit.items.length : 0 };
+}

package/src/lib/validation-model.js

@@ -509,7 +509,7 @@ export function collectValidation(projectRoot, { fix = false, runtime = false }
       const specPath = path.join(specsDir, cap, "spec.md");
       if (isFile(specPath)) {
         const lines = lineCount(specPath);
-        if (lines > 400) warnings.push(`${relPath(projectRoot, specPath)} is ${lines} lines (>400 soft cap)`);
+        if (lines > 400) warnings.push(`${relPath(projectRoot, specPath)} is ${lines} lines (>400 soft cap) — consolidate it: \`doctrina work --consolidate ${path.basename(path.dirname(specPath))}\``);
 
         // 8b. EARS grammar shape — section-appropriate When/While/Where/shall.
         const text = read(specPath);

package/src/lib/verify-cache.js

@@ -0,0 +1,76 @@
+// @ts-check
+import path from "node:path";
+import { createHash } from "node:crypto";
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { git, GIT_STATE, worktreeFingerprint } from "./git.js";
+import { cliVersion } from "./version.js";
+
+// A green verify, remembered for the exact code it ran on (change 0203).
+//
+// A field review of 0.17 put the fixed cost of a small change at the close
+// running the whole suite — 2.5 to 4 minutes — and an agent typically runs
+// `doctrina verify` itself right before `doctrina close`, so the same suite
+// ran twice on the same code. In a batch close it ran once per id, on a tree
+// whose only difference between ids was the artifacts the previous close
+// archived.
+//
+// The fingerprint is the CODE: the working tree (tracked, untracked, edits,
+// .gitignore respected) minus `.doctrina/`, plus the verify.json that
+// defines the checks and the CLI version that runs them. `.doctrina/` is
+// left out on purpose — the close's apply and archive move it between the
+// verify a person ran and the one the close would run — and the artifact
+// tree is proven by the close's own steps (coverage, trace, index drift,
+// validate), which always run.
+//
+// The record lives in the git directory, never in the tree: it is a fact
+// about this checkout, not an artifact to commit or review.
+
+const RECORD = "doctrina-verify-green.json";
+
+/**
+ * @param {string} projectRoot
+ * @param {string} configText  the verify.json the checks come from
+ * @returns {string | null}    null when git cannot fingerprint the tree
+ */
+export function verifyFingerprint(projectRoot, configText) {
+  const tree = worktreeFingerprint(projectRoot, { exclude: [".doctrina"] });
+  if (tree === null) return null;
+  return createHash("sha256").update(`${tree}\n${configText}\n${cliVersion()}`).digest("hex");
+}
+
+function recordPath(projectRoot) {
+  const dir = git(projectRoot, ["rev-parse", "--absolute-git-dir"]);
+  return dir.state === GIT_STATE.OK ? path.join(dir.stdout.trim(), RECORD) : null;
+}
+
+/**
+ * Remember that every check passed on this fingerprint.
+ * @param {string} projectRoot
+ * @param {string} fingerprint
+ * @param {string[]} checks
+ */
+export function recordGreen(projectRoot, fingerprint, checks) {
+  const file = recordPath(projectRoot);
+  if (!file) return;
+  try {
+    mkdirSync(path.dirname(file), { recursive: true });
+    writeFileSync(file, JSON.stringify({ fingerprint, checks, at: new Date().toISOString() }, null, 2) + "\n");
+  } catch { /* a cache that cannot be written is a cache miss, never an error */ }
+}
+
+/**
+ * The last green run, when it covered exactly this fingerprint.
+ * @param {string} projectRoot
+ * @param {string} fingerprint
+ * @returns {{ fingerprint: string, checks: string[], at: string } | null}
+ */
+export function reusableGreen(projectRoot, fingerprint) {
+  const file = recordPath(projectRoot);
+  if (!file) return null;
+  try {
+    const rec = JSON.parse(readFileSync(file, "utf8"));
+    return rec && rec.fingerprint === fingerprint ? rec : null;
+  } catch {
+    return null;
+  }
+}

package/src/lib/views.js

@@ -2,6 +2,7 @@
 import { c } from "./colors.js";
 import { today } from "./dates.js";
 import { churnByCapability } from "./ledger.js";
+import { STALE_CHANGE_DAYS } from "./snapshot.js";
 
 // Executed proof and signed proof are different claims (change 0039). One
 // phrasing, used by every view, so none of them can quietly add the two
@@ -182,7 +183,11 @@ export function prime(s) {
   } else {
     for (const ch of s.openChanges) {
       const tasks = ch.tasksTotal > 0 ? ` · tasks ${ch.tasksDone}/${ch.tasksTotal}` : "";
-      out.push(`  ${c.cyan(ch.id)}  ${ch.title ?? ""}${c.gray(` (${ch.status}${tasks})`)}`);
+      // The age, once it is news (change 0201): a change opened today and
+      // one forgotten for three weeks used to read identically.
+      const age = ch.ageDays !== null && ch.ageDays !== undefined && ch.ageDays >= STALE_CHANGE_DAYS
+        ? ` · open ${ch.ageDays}d` : "";
+      out.push(`  ${c.cyan(ch.id)}  ${ch.title ?? ""}${c.gray(` (${ch.status}${tasks}${age})`)}`);
     }
   }
 

package/src/lib/work-model.js

@@ -21,23 +21,43 @@ export function rankCapabilitiesByDiff(projectRoot, files, { limit = 3 } = {}) {
   if (!files || files.length === 0 || !isDir(specsDir)) return [];
   const norm = files.map((f) => f.replace(/\\/g, "/"));
 
-  const ranked = [];
+  const specs = [];
   for (const cap of readdirSync(specsDir).sort()) {
     const specPath = path.join(specsDir, cap, "spec.md");
     if (!isFile(specPath)) continue;
-    const specText = read(specPath);
-    // A DECLARED glob outranks every inference: the spec said this code is
-    // its own, and a declaration is not a guess (change 0077).
-    const declared = parseSourceGlobs(specText).map((g) => globToRegExp(g));
-    let score = 0;
-    for (const f of norm) {
-      if (declared.some((re) => re.test(f))) score += 10;     // the spec claims it
-      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
+    const text = read(specPath);
+    specs.push({ cap, text, declared: parseSourceGlobs(text).map((g) => globToRegExp(g)) });
+  }
+
+  // Per file, the strongest answer the tree holds wins, and a weaker one is
+  // never added on top of it (change 0200, ADR 0027):
+  //   1. the specs whose `**Source:**` claims the file — a declaration;
+  //   2. else the specs citing the exact path (a proof or a pointer);
+  //   3. else the path/basename inferences, and only from specs that declare
+  //      NO Source — a spec that stated what it owns has said all it owns.
+  // The old sum added every signal from every spec, so a file claimed by
+  // `health` still "belonged" to `cloud` because cloud's spec mentioned an
+  // `index.ts`, and every close warned about a spec the change never touched.
+  const scores = new Map();
+  const add = (cap, n) => scores.set(cap, (scores.get(cap) ?? 0) + n);
+  for (const f of norm) {
+    const claimed = specs.filter((s) => s.declared.some((re) => re.test(f)));
+    if (claimed.length > 0) {
+      for (const s of claimed) add(s.cap, 10);
+      continue;
+    }
+    const citing = specs.filter((s) => s.text.includes(f));
+    if (citing.length > 0) {
+      for (const s of citing) add(s.cap, 5);
+      continue;
+    }
+    for (const s of specs) {
+      if (s.declared.length > 0) continue;
+      if (f.split("/").includes(s.cap)) add(s.cap, 3);            // src/<cap>/... etc.
+      if (s.text.includes(path.basename(f))) add(s.cap, 2);       // filename cited
     }
-    if (score > 0) ranked.push({ id: cap, score, path: `.doctrina/specs/${cap}/spec.md` });
   }
+  const ranked = [...scores].map(([id, score]) => ({ id, score, path: `.doctrina/specs/${id}/spec.md` }));
   // `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.

package/templates/AGENTS.md.template

@@ -46,7 +46,7 @@ canonical templates and syncs `index.json`. Flags: `doctrina <cmd> --help`.
 - `doctrina triage` — classify the lane (product/runtime/chore) and check the declared runtime surface. *When:* a request arrives — BEFORE scaffolding, especially if it smells like an incident.
 - `doctrina work "<prompt>" (--capability · --chore · --from-diff · --quiet)` — scaffold a change and print the playbook to execute. *When:* a request arrives that changes behaviour (triage says PRODUCT).
 - `doctrina spec new|list|set` — create, list, and edit capability specs. *When:* a capability needs creating or its headers advancing.
-- `doctrina change new|apply|archive|check|tick|abandon` — drive a change by hand — check --verbose previews every delta. *When:* driving a change through its lifecycle by hand.
+- `doctrina change new|apply|archive|check|tick|abandon|delta` — drive a change by hand — check --verbose previews every delta. *When:* driving a change through its lifecycle by hand.
 - `doctrina contract new|list|check` — own and verify the integration surface. *When:* the change touches ports, env vars, or public endpoints.
 - `doctrina decision new|accept|land|supersede|list|scope` — record, accept, land, scope, and supersede ADRs. *When:* the change decides something a later session must not relitigate.
 - `doctrina skill new|list|suggest` — capture on-demand procedural memory. *When:* a lesson is worth not relearning.

package/templates/README.md

@@ -45,6 +45,7 @@ loops in it.
 | `{{CAPABILITY_BLOCK}}` | The pinned capability, the ranked hints, or "no match" | required in `work` |
 | `{{DIFF_MATCHES}}` | Capabilities the working tree touched | empty |
 | `{{STEP3_INTRO}}` | The delta step's opening, pinned or not | required in `work` |
+| `{{SHAPE}}` | The spec's measured size — lines, requirements per EARS subsection, criteria | required in `consolidate` |
 | `{{FROM_DIFF_DELTA_NOTE}}` | The backfill caveat on writing the delta | empty |
 | `{{MISSING_SPECS_WARNING}}` | Warning that `.doctrina/specs/` is absent | empty |
 
@@ -68,6 +69,7 @@ README.md                                  this file
 playbooks/work.md.template                 the work / backfill playbook
 playbooks/chore.md.template                the spec-less chore playbook
 playbooks/bootstrap.md.template            the intake -> specs playbook
+playbooks/consolidate.md.template          the spec consolidation playbook
 AGENTS.md.template                         root rules for the target repo
 doctrina/                                  the .doctrina/ skeleton
   product.md.template

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

@@ -24,6 +24,8 @@ typical delta applies mechanically end to end; only free-prose rewrites
   ```
 
 Requirement sections: ubiquitous | event | state | unwanted | optional.
+To take one out: `remove-requirement <section> <n>` / `remove-criterion <n>`
+(the criteria after it renumber; write removals highest number first).
 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.

package/templates/playbooks/consolidate.md.template

@@ -0,0 +1,28 @@
+[[b]]Consolidation playbook — change {{CHANGE_ID}}[[/b]][[g]] — agent-executed (ADR 0005); the spec shrinks, the behaviour does not change.[[/g]]
+
+Capability: [[c]]{{CAPABILITY}}[[/c]] — {{SHAPE}}
+
+Execute in order, in a single linear pass:
+
+1. Read the spec and its history:
+       [[c]]doctrina context {{CAPABILITY}} --concat[[/c]]
+       [[c]]doctrina why {{CAPABILITY}}[[/c]]
+2. Find what the spec says more than once: a requirement a later one
+   superseded, two requirements stating the same rule, a criterion proven
+   by another one, a bullet describing behaviour that no longer exists.
+   You decide; the CLI only measures. Keep every rule the code still
+   honours — consolidating removes words, never guarantees.
+3. Write the delta with the ops (the scaffold is at
+   .doctrina/changes/{{CHANGE_ID}}/specs/{{CAPABILITY}}/delta.md):
+       [[c]]doctrina change delta {{CHANGE_ID}} {{CAPABILITY}} --op "remove-requirement <section> <n>: <why>"[[/c]]
+       [[c]]doctrina change delta {{CHANGE_ID}} {{CAPABILITY}} --op "replace-requirement <section> <n>: <merged text>"[[/c]]
+       [[c]]doctrina change delta {{CHANGE_ID}} {{CAPABILITY}} --op "remove-criterion <n>: <why>"[[/c]]
+       [[c]]doctrina change delta {{CHANGE_ID}} {{CAPABILITY}} --bump minor[[/c]]
+[[g]]   Ops run in order and a removal renumbers what follows it: write the[[/g]]
+[[g]]   removals of one section highest number first. Every kept criterion[[/g]]
+[[g]]   must still cite proof that exists — coverage gates the close.[[/g]]
+[[g]]   Preview the merged spec: [[/g]][[c]]doctrina change check {{CHANGE_ID}} --verbose[[/c]]
+4. Fill the proposal's What (what was merged or removed, and why each) and
+   replace the placeholder tasks; no code changes.
+5. Close in one attested pass:
+       [[c]]doctrina close {{CHANGE_ID}}[[/c]]

package/templates/playbooks/work.md.template

@@ -40,6 +40,9 @@ Execute in order, in a single linear pass:
 [[g]]   append-* ops number/position at APPLY time, so concurrent changes[[/g]]
 [[g]]   appending to the same spec never collide. Only free-prose rewrites[[/g]]
 [[g]]   (Purpose, Maturity, ...) stay a by-hand merge.[[/g]]
+[[g]]   Or let the CLI write the lines and dry-run them against the spec:[[/g]]
+[[g]]       doctrina change delta {{CHANGE_ID}} <capability> --requirement "event: ..." \[[/g]]
+[[g]]         --criterion "[unverified] ... — verified by `...`" --bump minor[[/g]]
 {{FROM_DIFF_DELTA_NOTE}}
 
 4. Replace the placeholder tasks in .doctrina/changes/{{CHANGE_ID}}/tasks.md