doctrina-cli 0.17.0 → 0.18.0

package/src/commands/verify.js

@@ -8,9 +8,10 @@ import { exists, isDir, isFile, read, write, relPath } from "../lib/fs-ops.js";
 import { flagBool, flagString } from "../lib/args.js";
 import { today } from "../lib/dates.js";
 import { c } from "../lib/colors.js";
-import { loadSignoffs, saveSignoffs, recordSignoff, signoffState, short, SIGNOFF_REL } from "../lib/signoff.js";
+import { loadSignoffs, saveSignoffs, recordSignoff, signoffState, short, SIGNOFF_REL, declaredPaths, workingChanges } from "../lib/signoff.js";
 import { EXIT, notADoctrinaProject } from "../lib/exit-codes.js";
 import { collectReproducibility } from "../lib/reproducibility.js";
+import { verifyFingerprint, recordGreen, reusableGreen } from "../lib/verify-cache.js";
 
 // The build/verify gate `validate` is not. `validate` checks the shape of
 // the artifact tree; it never runs the project, so a repo that does not
@@ -40,7 +41,7 @@ const STARTER = {
 // Flags this command accepts. Declared HERE, with the command, so
 // adding a command never requires editing the entrypoint — the gap that
 // let six flags ship undeclared and silently swallow a positional (C3).
-export const flags = { boolean: ["json", "clean", "force", "init", "list", "strict"], string: ["signoff"] };
+export const flags = { boolean: ["json", "clean", "force", "init", "list", "strict", "reuse", "affected"], string: ["signoff"] };
 
 export async function run(_positional, flags) {
   const projectRoot = process.cwd();
@@ -182,6 +183,22 @@ export async function run(_positional, flags) {
   }
 
   const strict = flagBool(flags, "strict", false);
+  const affected = flagBool(flags, "affected", false);
+  // The fingerprint of the code these checks are about to run on, taken
+  // BEFORE they run (change 0203): what a green run proves is the tree it
+  // started from. Null outside git — then nothing is remembered or reused.
+  const fingerprint = verifyFingerprint(projectRoot, read(configPath));
+  if (flagBool(flags, "reuse", false) && fingerprint !== null) {
+    const green = reusableGreen(projectRoot, fingerprint);
+    if (green) {
+      console.log(c.bold("doctrina verify") + c.gray(` — ${checks.length} check${checks.length === 1 ? "" : "s"} from ${CONFIG_REL}`));
+      console.log("");
+      console.log(c.green("ok") + ` reused the green run of ${green.at.replace("T", " ").slice(0, 16)} UTC — ` +
+        `the code and ${CONFIG_REL} are byte-identical to what it ran on (${green.checks.join(", ")})`);
+      console.log(c.gray("   `doctrina verify` runs the checks again"));
+      return 0;
+    }
+  }
   console.log(c.bold("doctrina verify") + c.gray(` — ${checks.length} check${checks.length === 1 ? "" : "s"} from ${CONFIG_REL}`));
   const results = [];
   for (const ch of checks) {
@@ -220,6 +237,20 @@ export async function run(_positional, flags) {
       continue;
     }
 
+    // --affected (change 0204): a check that declares the "paths" it covers
+    // runs only when the uncommitted work touches one of them. The inner
+    // loop of a change — not the close, which always runs every check. A
+    // check that declares no paths covers everything and always runs; a
+    // question git cannot answer runs the check.
+    if (affected && declaredPaths(ch).length > 0) {
+      const touched = workingChanges(projectRoot, declaredPaths(ch));
+      if (touched !== null && touched.length === 0) {
+        console.log(c.gray(`──── ${name}: `) + c.gray(`skip — the uncommitted work touches none of ${declaredPaths(ch).join(", ")}`));
+        results.push({ name, ok: true, kind: "command", skipped: true });
+        continue;
+      }
+    }
+
     const where = ch.cwd ? c.gray(` [${ch.cwd}]`) : "";
     console.log(c.gray(`──── ${name}: `) + ch.run + where);
     // Run through the shell so declared commands can use pipes, &&, env,
@@ -287,9 +318,18 @@ export async function run(_positional, flags) {
   // manual check still awaiting sign-off. Pending manual checks are otherwise
   // a non-blocking report.
   const failGate = cmdFailed.length > 0 || (strict && pending.length > 0);
-  const pendNote = pending.length > 0 ? c.gray(` (${pending.length} manual pending)`) : "";
+  const skipped = results.filter((r) => r.skipped);
+  const pendNote = (pending.length > 0 ? c.gray(` (${pending.length} manual pending)`) : "") +
+    (skipped.length > 0 ? c.gray(` (${skipped.length} skipped by --affected: ${skipped.map((r) => r.name).join(", ")})`) : "");
   if (!failGate) {
-    console.log(c.green("ok") + ` ${passed}/${results.length} checks passed${pendNote}`);
+    const ran = passed - skipped.length;
+    console.log(c.green("ok") + ` ${ran}/${results.length - skipped.length} checks passed${pendNote}`);
+    // Remembered only when EVERY check passed — a run green with a manual
+    // check still pending is a report, not something a close may stand on,
+    // and neither is a run --affected cut short.
+    if (fingerprint !== null && pending.length === 0 && skipped.length === 0) {
+      recordGreen(projectRoot, fingerprint, results.map((r) => r.name));
+    }
     return 0;
   }
   const reasons = [];
@@ -403,7 +443,7 @@ function renderReproducibility(projectRoot) {
 }
 
 export const help = `
-Usage: doctrina verify [--list] [--init] [--clean] [--strict] [--signoff "<name>=<note>"] [--force]
+Usage: doctrina verify [--list] [--init] [--clean] [--strict] [--reuse] [--affected] [--signoff "<name>=<note>"] [--force]
 
 Run the project-declared build/verify checks from ${CONFIG_REL} in order,
 streaming their output, and exit non-zero if any check fails. This is the
@@ -414,13 +454,18 @@ root, targets a sub-package in a monorepo; a "manual" check is the
 qualitative gate — judged by a human/eval, recorded as a sign-off, not run):
   {
     "checks": [
-      { "name": "typecheck", "run": "tsc --noEmit", "cwd": "packages/api" },
+      { "name": "typecheck", "run": "tsc --noEmit", "cwd": "packages/api",
+        "paths": ["packages/api"] },
       { "name": "test",      "run": "npm test" },
       { "name": "build",     "run": "npm run build" },
       { "name": "chronicle", "type": "manual", "rubric": "is the chronicle enjoyable to read?" }
     ]
   }
 
+"paths" (git pathspecs, relative to the project root) says what a check
+covers: --affected runs it only when the uncommitted work touches one, and a
+manual check's sign-off expires when one changes.
+
 A manual check passes when it has been signed off and is otherwise reported
 as "pending" — non-blocking by default, failing only under --strict (so CI
 can require the sign-off). Sign-offs are stored in ${SIGNOFF_REL}.
@@ -450,6 +495,14 @@ Flags:
              prepare/prepack; a Prisma dep with no generate on install) so
              "verify green" can't hide a clean checkout that won't build.
   --strict   Fail the gate when a manual check is still pending sign-off
+  --reuse    Skip the checks when the last fully green run covered this exact
+             code: the working tree (tracked, untracked, edits) minus
+             .doctrina/, plus ${CONFIG_REL}, are byte-identical. \`close\` runs
+             verify this way; a plain \`doctrina verify\` always runs them.
+  --affected Run a check that declares "paths" only when the uncommitted work
+             (edits against HEAD, untracked files) touches one of them —
+             the inner loop of a change. Checks with no "paths" always run;
+             \`close\` always runs every check. Never remembered by --reuse.
   --signoff "<name>=<note>"
              Record today's sign-off for a manual check, then exit
   --force    With --init, overwrite an existing config

package/src/commands/work.js

@@ -9,9 +9,10 @@ import { c } from "../lib/colors.js";
 import { assessBrief } from "../lib/clarity.js";
 import { locateTemplatesDir, substitute } from "../lib/templates.js";
 import { EXIT, notADoctrinaProject } from "../lib/exit-codes.js";
-import { changeNew, reindexChange } from "../lib/change-ops.js";
+import { changeNew, reindexChange, addAffectedSpec } from "../lib/change-ops.js";
 import { classify } from "../lib/triage-model.js";
 import { printPlaybookTemplate } from "../lib/playbook.js";
+import { specShape } from "../lib/spec-ops.js";
 import { changedFiles } from "../lib/git.js";
 import { slugFromPrompt, fold, CONFIDENT_MARGIN } from "../lib/lexicon.js";
 import { rankCapabilities, rankCapabilitiesByDiff } from "../lib/work-model.js";
@@ -29,14 +30,36 @@ export { rankCapabilities, rankCapabilitiesByDiff } from "../lib/work-model.js";
 // Flags this command accepts. Declared HERE, with the command, so
 // adding a command never requires editing the entrypoint — the gap that
 // let six flags ship undeclared and silently swallow a positional (C3).
-export const flags = { boolean: ["json", "chore", "design", "force", "from-diff", "no-spec", "quiet"], string: ["capability", "id", "resume", "title"] };
+export const flags = { boolean: ["json", "chore", "design", "force", "from-diff", "no-spec", "quiet"], string: ["capability", "consolidate", "id", "resume", "title"] };
 
 export async function run(positional, flags) {
-  const prompt = positional.join(" ").trim();
   const projectRoot = process.cwd();
   if (!exists(path.join(projectRoot, ".doctrina"))) {
     throw notADoctrinaProject();
   }
+  // --consolidate <cap> (change 0206): a spec only ever grew — every change
+  // appended, nothing took a requirement out — and a field review of 0.17
+  // asked for "a command to consolidate a spec from time to time". It is an
+  // ordinary change pinned to the capability, with its own playbook: the
+  // agent decides what is redundant or superseded (ADR 0005), and the ops
+  // take it out.
+  const consolidate = flags.has("consolidate") ? flagString(flags, "consolidate") : null;
+  if (consolidate !== null) {
+    if (!consolidate || /** @type {unknown} */ (consolidate) === true || !/^[a-z][a-z0-9-]*$/.test(consolidate)) {
+      console.error(c.red("error:") + " --consolidate needs the capability whose spec to consolidate");
+      return EXIT.USAGE;
+    }
+    if (!isFile(path.join(projectRoot, ".doctrina", "specs", consolidate, "spec.md"))) {
+      console.error(c.red("error:") + ` capability "${consolidate}" has no spec at .doctrina/specs/${consolidate}/spec.md`);
+      return EXIT.USAGE;
+    }
+    flags.set("capability", consolidate);
+    flags.set("force", true);
+    if (!flags.has("title")) flags.set("title", `consolidate ${consolidate}`);
+  }
+  const prompt = consolidate
+    ? `Consolidate the ${consolidate} spec: merge requirements and criteria that say the same thing, drop what a later one superseded — no behaviour changes.`
+    : positional.join(" ").trim();
 
   // --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
@@ -205,6 +228,12 @@ export async function run(positional, flags) {
     ? null
     : scaffoldDelta(projectRoot, { id, capability, guess, runnerUp: promptMatches[1] ?? null });
 
+  // A guessed delta names the capability as surely as a pinned one: the
+  // header says what the folder says (change 0207). It stayed empty for
+  // every unpinned `work`, so the proposal claimed no spec while its delta
+  // targeted one.
+  if (scaffolded) addAffectedSpec(projectRoot, id, scaffolded.capability);
+
   // The proposal is written in two passes — `changeNew` scaffolds it, the
   // lines above stamp the lane and the pinned specs — so its index entry is
   // re-derived HERE, from the finished file. Indexing at the end of the first
@@ -223,7 +252,9 @@ export async function run(positional, flags) {
   }
 
   console.log("");
-  if (chore) {
+  if (consolidate) {
+    printConsolidatePlaybook(projectRoot, { id, capability: consolidate });
+  } else if (chore) {
     printChorePlaybook(projectRoot, { id, prompt: effPrompt });
   } else {
     printPlaybook(projectRoot, {
@@ -440,6 +471,21 @@ export function slugify(text) {
 // part that is not prose: computing the variable blocks. Each is PRE-RENDERED
 // into a token, so `substitute` stays a plain string map and the template
 // stays a document rather than a language with conditionals in it.
+// The consolidation playbook: the spec's shape, measured, then the steps.
+// Measuring is the CLI's part; deciding which requirement is redundant is
+// the agent's (ADR 0005).
+function printConsolidatePlaybook(projectRoot, { id, capability }) {
+  const text = read(path.join(projectRoot, ".doctrina", "specs", capability, "spec.md"));
+  const shape = specShape(text);
+  const sections = Object.entries(shape.sections).map(([k, n]) => `${k} ${n}`).join(" · ");
+  printPlaybookTemplate(projectRoot, "consolidate", {
+    CHANGE_ID: id,
+    CAPABILITY: capability,
+    SHAPE: `${shape.lines} lines · ${shape.requirements} requirements (${sections || "none"}) · ` +
+      `${shape.criteria} acceptance criteria`,
+  });
+}
+
 function printChorePlaybook(projectRoot, { id, prompt }) {
   printPlaybookTemplate(projectRoot, "chore", { CHANGE_ID: id, PROMPT: prompt });
 }
@@ -543,6 +589,10 @@ Options:
   --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)
+  --consolidate <cap>  Open a change that consolidates <cap>'s spec — merge
+                       what says the same thing, remove what was superseded
+                       (remove-requirement / remove-criterion) — with its own
+                       playbook; no prompt needed, no behaviour changes
   --chore, --no-spec   Open a spec-less chore change (infra/docs/build) with a
                        playbook that skips the spec-delta steps (F9)
   --design             Also scaffold design.md, for a change with non-trivial

package/src/lib/actions.js

@@ -199,9 +199,13 @@ export function computeActions(projectRoot, gates = {}) {
       }
       const status = listHeader(read(proposalPath), "Status") ?? "proposed";
       if (status === "applied") {
+        // The close, not the archive (change 0201). 0.17 retired the
+        // hand-driven tail — `close` skips the apply it already did and
+        // still runs verify, coverage and the docs gate — but this line kept
+        // teaching `change archive`, the one path past every one of them.
         actions.push(action({
           id: "change-archive-pending",
-          command: "change archive",
+          command: "close",
           args: [id],
           gate: "archive",
           runnable: true,
@@ -239,11 +243,11 @@ export function computeActions(projectRoot, gates = {}) {
       } else {
         actions.push(action({
           id: "change-deltas-missing",
-          command: "change apply",
+          command: "close",
           args: [id],
-          why: `add spec deltas under .doctrina/changes/${id}/specs/, or apply as metadata-only`,
+          why: `add spec deltas under .doctrina/changes/${id}/specs/, or close it as metadata-only`,
           text: `add spec deltas under .doctrina/changes/${id}/specs/, ` +
-            `or apply as metadata-only: doctrina change apply ${id}`,
+            `or close it as metadata-only: doctrina close ${id}`,
         }));
       }
     }

package/src/lib/change-ops.js

@@ -15,6 +15,10 @@ import { flagBool, flagString } from "./args.js";
 import { c } from "./colors.js";
 import { ensureDoctrinaProject, isChangeId, resolveWithinProject } from "./project.js";
 import { changeEntry } from "./scan.js";
+import { parseOp, insertOps, extractOps, applyOps } from "./spec-ops.js";
+import { parseOperation } from "./doc-model.js";
+import { substitute } from "./templates.js";
+import { EXIT } from "./exit-codes.js";
 export function changeNew(args, flags) {
   const id = args[0];
   const title = args.slice(1).join(" ").trim();
@@ -131,3 +135,91 @@ export function reindexChange(projectRoot, id, date = today()) {
   idx.touch(index, date);
   idx.save(projectRoot, index);
 }
+
+/**
+ * Add op lines to a change's MODIFIED delta for one capability (change 0205).
+ *
+ * A field review of 0.17 asked for "a command to add a requirement and a
+ * criterion without writing the ops blocks by hand". The grammar is
+ * `apply`'s (ADR 0021): every line is parsed by the same parser, and the
+ * whole block — what was there plus what is added — is dry-run against the
+ * current spec before anything is written, so an op that would not apply is
+ * refused now rather than at the close. Creates the delta from the template
+ * when the change has none for the capability yet; a second `bump-version`
+ * replaces the first instead of bumping twice.
+ *
+ * @param {string} projectRoot
+ * @param {string} id          change id (already refused/resolved by the caller)
+ * @param {string} capability
+ * @param {string[]} lines     op lines, one operation each
+ * @returns {{ code: number, error?: string, hint?: string, details?: string[],
+ *             deltaRel?: string, created?: boolean, block?: string[] }}
+ */
+export function addDeltaOps(projectRoot, id, capability, lines) {
+  if (lines.length === 0) {
+    return { code: EXIT.USAGE, error: "nothing to add",
+      hint: "pass --requirement \"<section>: <text>\", --criterion \"<text>\", --bump <level> or an op line" };
+  }
+  const bad = lines.map((l) => ({ l, op: parseOp(l) })).filter((x) => x.op.error);
+  if (bad.length > 0) {
+    return { code: EXIT.USAGE, error: "not an operation `apply` can read", details: bad.map((x) => x.op.error) };
+  }
+  const specPath = path.join(projectRoot, ".doctrina", "specs", capability, "spec.md");
+  if (!isFile(specPath)) {
+    return { code: EXIT.USAGE, error: `capability "${capability}" has no spec at ${relPath(projectRoot, specPath)}`,
+      hint: `a NEW capability is an ADDED delta with the full body — \`doctrina spec new ${capability}\`, then write it` };
+  }
+  const deltaPath = path.join(projectRoot, ".doctrina", "changes", id, "specs", capability, "delta.md");
+  const created = !isFile(deltaPath);
+  let text;
+  if (created) {
+    const tpl = read(path.join(locateTemplatesDir(), "change", "spec-delta.md.template"));
+    text = substitute(tpl, { CAPABILITY: capability }).replace(/^\*\*Operation:\*\*.*$/m, "**Operation:** MODIFIED");
+  } else {
+    text = read(deltaPath);
+    const op = parseOperation(text);
+    if (op && op !== "MODIFIED") {
+      return { code: EXIT.PRECONDITION, error: `${relPath(projectRoot, deltaPath)} is an ${op} delta — ops apply only to a MODIFIED one`,
+        hint: op === "ADDED" ? "write the requirement into the ADDED body itself" : "a REMOVED delta deletes the spec; there is nothing to add to" };
+    }
+  }
+  const next = insertOps(text, lines);
+  const dry = applyOps(read(specPath), extractOps(next));
+  if (dry.errors.length > 0) {
+    return { code: EXIT.GATE, error: `the ops block would not apply to ${relPath(projectRoot, specPath)} — nothing written`, details: dry.errors };
+  }
+  mkdirp(path.dirname(deltaPath));
+  write(deltaPath, next, { force: true });
+  addAffectedSpec(projectRoot, id, capability);
+  return { code: EXIT.OK, deltaRel: relPath(projectRoot, deltaPath), created, block: extractOps(next).map((o) => o.verb) };
+}
+
+/**
+ * Name `capability` in the proposal's `Affects specs:` header when the
+ * header does not already (change 0207). A change whose delta targets a
+ * capability affects that spec, and a header left empty while the delta
+ * folder said otherwise was the one fact `prime`, `status` and the review
+ * of the proposal disagreed on. A chore's "(none — chore)" is left alone:
+ * that is a declaration, and the structure gate is where a chore carrying a
+ * delta gets questioned.
+ *
+ * @param {string} projectRoot
+ * @param {string} id
+ * @param {string} capability
+ * @returns {boolean} whether the header changed
+ */
+export function addAffectedSpec(projectRoot, id, capability) {
+  const proposalPath = path.join(projectRoot, ".doctrina", "changes", id, "proposal.md");
+  if (!isFile(proposalPath)) return false;
+  const text = read(proposalPath);
+  const m = text.match(/^(-[ \t]+\*\*Affects specs:\*\*)([^\r\n]*)/m);
+  if (!m) return false;
+  const current = m[2].trim();
+  if (/^\(none/i.test(current)) return false;
+  const named = current.split(",").map((s) => s.trim().replace(/`/g, "")).filter(Boolean);
+  if (named.includes(capability)) return false;
+  const value = [...named, capability].join(", ");
+  write(proposalPath, text.replace(m[0], `${m[1]} ${value}`), { force: true });
+  reindexChange(projectRoot, id);
+  return true;
+}

package/src/lib/commands.js

@@ -47,6 +47,7 @@ export const OPERATIONS = [
   ["change check", "Pre-close dry-run: everything close would refuse, listed first"],
   ["change tick", "List/tick the unchecked boxes (tasks + verification; --all)"],
   ["change abandon", "Discard an open change cleanly (recorded in the ledger)"],
+  ["change delta", "Add a requirement/criterion/bump to a change's delta (ops written for you)"],
   ["contract new", "Own the integration surface (ports, env, interfaces)"],
   ["contract list", "List contracts with status and last-updated date"],
   ["contract check", "Verify port collisions, env drift, referenced specs"],
@@ -516,6 +517,13 @@ export const AGENT_CHANGELOG = {
   // Each entry lists only ITS OWN delta. The series carries the rest
   // forward (see agentChangelogEntries), so a patch never has to restate
   // the minor that introduced the commands, and never silently erases it.
+  "0.18.0": [
+    "`doctrina change delta <id> <capability> --requirement \"<section>: <text>\" --criterion \"<text>\" --bump minor` writes the ops lines for you and dry-runs them against the spec — stop hand-writing ops blocks.",
+    "`close` runs `verify --reuse`: running `doctrina verify` yourself right before `doctrina close` is no longer paid twice, and a batch close runs the suite once. Use `verify --affected` while working when checks declare `\"paths\"`.",
+    "The review inside `close` counts the change's own deltas as spec updates and reports code under other capabilities in ONE line — read it: either this change forgot a delta or other work is lying in the tree.",
+    "`close` ends by listing other open changes that look finished or are a week old; close them with the `doctrina close <id>` it prints. `next` no longer suggests `change archive`.",
+    "A spec can shrink: `remove-requirement <section> <n>` / `remove-criterion <n>`, and `doctrina work --consolidate <cap>` when a spec has grown past what it needs to say.",
+  ],
   "0.17.0": [
     "Preview a close with `doctrina change check <id>` (it exits 1 while a Verification box is open), then run `doctrina close <id>` — do not run `analyze`, `change apply` or `change archive` by hand; a chore closes the same way.",
     "Deprecated names still run with a notice — use the replacement: `analyze` → `change check`, `report` → `status --view report`, `skill sync` → `index rebuild`, `templates check|update` → `upgrade [--write]`. `constitution` and `change diff` are removed (exit 2).",

package/src/lib/git.js

@@ -1,5 +1,10 @@
 // @ts-check
 import { spawnSync } from "node:child_process";
+import { copyFileSync, existsSync, rmSync } from "node:fs";
+import { createHash } from "node:crypto";
+import os from "node:os";
+import path from "node:path";
+import process from "node:process";
 
 // One place that knows how to ask git a question and how to interpret not
 // getting an answer (audit item C8).
@@ -32,8 +37,13 @@ export const GIT_STATE = Object.freeze({
 
 // Run a git command. Never throws. Returns
 // { state, stdout, lines, stderr, code }.
-export function git(cwd, args) {
-  const r = spawnSync("git", args, { cwd, encoding: "utf8" });
+/**
+ * @param {string} cwd
+ * @param {string[]} args
+ * @param {{ env?: Record<string, string> }} [opts]
+ */
+export function git(cwd, args, { env } = {}) {
+  const r = spawnSync("git", args, { cwd, encoding: "utf8", ...(env ? { env: { ...process.env, ...env } } : {}) });
   if (r.error) {
     // ENOENT here means the binary is missing, not that the command failed.
     return { state: GIT_STATE.ABSENT, stdout: "", lines: [], stderr: String(r.error.message ?? ""), code: null };
@@ -227,3 +237,50 @@ export function lastTagDate(cwd) {
   const date = tags[0] ?? "";
   return /^\d{4}-\d{2}-\d{2}$/.test(date) ? date : null;
 }
+
+/**
+ * A content fingerprint of the working tree under `cwd` — tracked AND
+ * untracked files, .gitignore respected, uncommitted edits included — with
+ * the top-level entries named in `exclude` left out (change 0203). Null when
+ * git cannot answer.
+ *
+ * Built from git's own object model rather than by reading files: the real
+ * index is copied to a scratch one, `git add -A` stages the whole tree into
+ * the copy (reusing the stat cache, so only changed files are hashed), and
+ * `git write-tree` names the result. The real index, HEAD and the working
+ * tree are never touched; the only side effect is loose objects for changed
+ * files, which `git gc` reclaims.
+ *
+ * @param {string} cwd
+ * @param {{ exclude?: string[] }} [opts]
+ * @returns {string | null}
+ */
+export function worktreeFingerprint(cwd, { exclude = [] } = {}) {
+  const top = git(cwd, ["rev-parse", "--show-toplevel"]);
+  const dir = git(cwd, ["rev-parse", "--absolute-git-dir"]);
+  if (top.state !== GIT_STATE.OK || dir.state !== GIT_STATE.OK) return null;
+  const root = top.stdout.trim();
+  const scratch = path.join(os.tmpdir(), `doctrina-fingerprint-${process.pid}-${Date.now()}`);
+  try {
+    const real = path.join(dir.stdout.trim(), "index");
+    if (existsSync(real)) copyFileSync(real, scratch);
+    const env = { GIT_INDEX_FILE: scratch };
+    if (git(root, ["add", "-A", "--", "."], { env }).state !== GIT_STATE.OK) return null;
+    const tree = git(root, ["write-tree"], { env });
+    if (tree.state !== GIT_STATE.OK) return null;
+    // Asked of git, never computed with path.relative: on macOS the tmpdir
+    // is `/var/…`, a symlink to `/private/var/…`, and git answers with the
+    // resolved toplevel — the relative path between the two spellings is
+    // `../..`, which names nothing in the tree (the 0.18 macOS CI run).
+    const prefixed = git(cwd, ["rev-parse", "--show-prefix"]);
+    if (prefixed.state !== GIT_STATE.OK) return null;
+    const prefix = prefixed.stdout.trim().replace(/\/$/, "");
+    const listing = git(root, ["ls-tree", prefix ? `${tree.stdout.trim()}:${prefix}` : tree.stdout.trim()]);
+    if (listing.state !== GIT_STATE.OK) return null;
+    const skip = new Set(exclude);
+    const kept = listing.lines.filter((l) => !skip.has(l.split("\t")[1]));
+    return createHash("sha256").update(kept.join("\n")).digest("hex");
+  } finally {
+    rmSync(scratch, { force: true });
+  }
+}

package/src/lib/playbook.js

@@ -94,4 +94,4 @@ export function printPlaybookTemplate(projectRoot, name, tokens = {}) {
 }
 
 /** The playbooks the CLI ships and `templates check` expects to resolve. */
-export const PLAYBOOKS = ["work", "chore", "bootstrap"];
+export const PLAYBOOKS = ["work", "chore", "bootstrap", "consolidate"];

package/src/lib/runtime.js

@@ -631,6 +631,12 @@ export function expandBraces(glob) {
 // `{a,b}` alternates. Enough for the "where do my selectors live" and "which
 // code is mine" declarations, with no dependency and no surprises.
 export function globToRegExp(glob) {
+  // A pattern ending in `/` names a DIRECTORY, and a directory claims what
+  // is under it (change 0199). Compiled as written it matched only the
+  // literal path `src/health/` — which no file has — so the most natural way
+  // to declare a module's ownership claimed nothing, and `review` reported
+  // every file in it as ownerless.
+  if (/\/$/.test(String(glob))) glob = `${glob}**`;
   // Always compile the EXPANSION, never the original. Using it only when it
   // produced more than one alternative left `src/{a}.js` compiling with its
   // braces as literal characters, so a one-element group matched nothing

package/src/lib/scan.js

@@ -599,3 +599,16 @@ function artifactPathOf(file) {
   if (m) return m[1];
   return null;
 }
+
+// The capabilities a change's deltas target, sorted — the change's own scope.
+// `close` gates coverage on it and `review --change` reads it as "these specs
+// are being updated by this change", because the delta merges at apply.
+export function deltaCapabilities(changeDir) {
+  const caps = new Set();
+  for (const deltaPath of walk(path.join(changeDir, "specs"))) {
+    if (!deltaPath.endsWith("delta.md")) continue;
+    const cap = parseCapabilityFromDelta(read(deltaPath), deltaPath);
+    if (cap) caps.add(cap);
+  }
+  return [...caps].sort();
+}

package/src/lib/signoff.js

@@ -96,6 +96,30 @@ export function changedSince(projectRoot, sha, paths) {
   return [...out].sort();
 }
 
+/**
+ * Which of `paths` the uncommitted work touches — edits against HEAD plus
+ * untracked files, `.gitignore` respected (change 0204). The same pathspec
+ * reading a sign-off's "paths" gets, so "what this check covers" means one
+ * thing in verify.json. Null when git cannot answer: a caller then runs the
+ * check rather than reading "nothing changed" out of a question it never
+ * got to ask.
+ *
+ * @param {string} projectRoot
+ * @param {string[]} paths
+ * @returns {string[] | null}
+ */
+export function workingChanges(projectRoot, paths) {
+  const tracked = git(projectRoot, ["diff", "--name-only", "HEAD", "--", ...paths]);
+  // No commit yet: every file is new, so what is staged counts as changed.
+  const staged = tracked.state === GIT_STATE.EMPTY
+    ? git(projectRoot, ["ls-files", "--cached", "--", ...paths])
+    : tracked;
+  if (staged.state !== GIT_STATE.OK) return null;
+  const untracked = git(projectRoot, ["ls-files", "--others", "--exclude-standard", "--", ...paths]);
+  if (untracked.state !== GIT_STATE.OK) return null;
+  return [...new Set([...staged.lines, ...untracked.lines].filter(Boolean))].sort();
+}
+
 /** The commit a signature is anchored to, or null outside a repository. */
 export function currentSha(projectRoot) {
   const r = git(projectRoot, ["rev-parse", "HEAD"]);