doctrina-cli 0.17.0 → 0.20.0

package/src/lib/commands.js

@@ -19,6 +19,8 @@ export const COMMAND_NAMES = [
   "prime", "context", "show", "search", "status", "next", "why", "handoff",
   // gates
   "analyze", "clarify", "validate", "coverage", "trace", "review", "verify", "close", "doctor",
+  // orchestrate
+  "workspace", "delivery",
   // maintenance
   "templates", "hooks", "index", "watch", "metrics", "report", "completion", "upgrade", "ci",
 ];
@@ -47,6 +49,8 @@ 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)"],
+  ["change card", "One task as an executor receives it: the task, its why, the spec cut to it"],
   ["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"],
@@ -81,6 +85,19 @@ export const OPERATIONS = [
   ["status", "One-glance project health dashboard"],
   ["why", "Explain provenance: a capability's chain, or an anchor's (SC1)"],
   ["handoff", "Markdown handoff note: open work, task state, resume command"],
+  ["workspace init", "Create a multi-repository workspace (a private git repo of context)"],
+  ["workspace add", "Register a repository: in-repo, or shadowed when it cannot carry .doctrina/"],
+  ["workspace attach", "Re-create a shadow project's links in its repository"],
+  ["workspace detach", "Remove a shadow project's links; the shadow stays"],
+  ["workspace list", "Projects with mode, state and open changes"],
+  ["workspace tool", "Declare a tool (MCP server) the work uses: role, read or write"],
+  ["workspace guard", "Pre-call hook: allow, deny or ask an MCP call from the declared access"],
+  ["delivery new", "Open a delivery across repositories; print the orchestration playbook"],
+  ["delivery route", "Choose the projects a delivery touches, dependencies first"],
+  ["delivery list", "Deliveries with status, ref and closed/total changes"],
+  ["delivery status", "Per project: the changes carrying a delivery and their tasks"],
+  ["delivery check", "What still keeps a delivery from closing (exit 1 while anything does)"],
+  ["delivery close", "Close a delivery once every project's change is closed"],
   ["templates list", "List the templates shipped by the installed CLI"],
   ["templates check", "Compare the project against the recommended template shape"],
   ["templates update", "Additive fixer for check findings (preview; --write applies)"],
@@ -126,8 +143,8 @@ export const COMMAND_META = {
   why:          { moment: "Orient",     when: "you need to justify or trace a capability's existence", purpose: "provenance: intent, proof, ADRs, and history" },
   handoff:      { moment: "Orient",     when: "BEFORE compaction or handing over to another session", purpose: "a resume note: open work, task state, next command" },
 
-  triage:       { moment: "Change",     when: "a request arrives — BEFORE scaffolding, especially if it smells like an incident", purpose: "classify the lane (product/runtime/chore) and check the declared runtime surface" },
-  work:         { moment: "Change",     when: "a request arrives that changes behaviour (triage says PRODUCT)", purpose: "scaffold a change and print the playbook to execute" },
+  triage:       { moment: "Change",     when: "diagnosing an incident or a runtime symptom — `work` classifies every other request itself", purpose: "classify the lane (product/runtime/chore) and check the declared runtime surface" },
+  work:         { moment: "Change",     when: "a request changes behaviour — BEFORE editing code; it classifies the lane itself", purpose: "scaffold a change and print the playbook to execute" },
   spec:         { moment: "Change",     when: "a capability needs creating or its headers advancing", purpose: "create, list, and edit capability specs" },
   change:       { moment: "Change",     when: "driving a change through its lifecycle by hand", purpose: "drive a change by hand — check --verbose previews every delta" },
   decision:     { moment: "Change",     when: "the change decides something a later session must not relitigate", purpose: "record, accept, land, scope, and supersede ADRs" },
@@ -145,6 +162,9 @@ export const COMMAND_META = {
   close:        { moment: "Gate",       when: "a change is implemented and ready to finish", purpose: "the whole closing sequence in one attested pass" },
   doctor:       { moment: "Gate",       when: "something looks wrong and you do not know which gate to ask", purpose: "aggregate diagnostic with per-finding remedies" },
 
+  delivery:     { moment: "Orchestrate", when: "a story or screen must land in more than one repository", purpose: "plan, route, track and close one item of work across repositories" },
+  workspace:    { moment: "Orchestrate", when: "the work spans several repositories, or a repository cannot carry .doctrina/", purpose: "register repositories, in-repo or shadowed, in one versioned workspace" },
+
   templates:    { moment: "Maintain",   when: "customising a scaffold, to see which template file wins", purpose: "where each shipped template resolves from" },
   upgrade:      { moment: "Maintain",   when: "you just updated the doctrina-cli package", purpose: "bring this project up to the installed CLI" },
   index:        { moment: "Maintain",   when: "the index drifted from the tree", purpose: "regenerate index.json from the artifacts on disk" },
@@ -157,7 +177,7 @@ export const COMMAND_META = {
 };
 
 // The order moments appear in the generated block.
-export const MOMENTS = ["Bootstrap", "Orient", "Change", "Gate", "Maintain"];
+export const MOMENTS = ["Bootstrap", "Orient", "Change", "Gate", "Orchestrate", "Maintain"];
 
 // The Commands block of `doctrina --help`, generated from OPERATIONS so the
 // printed surface can never omit an operation the catalog knows about.
@@ -191,7 +211,10 @@ export function surfaceHelp() {
       const ops = live.filter(([op]) => op.split(" ")[0] === cmd);
       const subs = ops.map(([op]) => op.split(" ")[1]).filter(Boolean);
       const text = ops.length === 1 ? ops[0][1] : capitalise(COMMAND_META[cmd].purpose);
-      out.push(line(subs.length > 0 ? `${cmd} ${subs.join("|")}` : cmd, text));
+      const op = subs.length > 0 ? `${cmd} ${subs.join("|")}` : cmd;
+      // A compact moment's long invocation stands alone rather than wrapping
+      // onto a second line (change 0220): `doctrina <cmd> --help` has the rest.
+      out.push(COMPACT_MOMENTS.has(moment) && op.length >= 20 ? `  ${op}` : line(op, text));
     }
   }
   const old = OPERATIONS.filter(([op]) => DEPRECATED[op]);
@@ -316,7 +339,10 @@ export const SURFACE_LINE_BUDGET = 40;
 // each its own line pushed the block past its budget. The budget is the
 // forcing function — a surface that cannot describe itself in 40 lines is
 // too large, and the answer is to cut commands (M8), not to raise it.
-const COMPACT_MOMENTS = new Set(["Maintain"]);
+// "Orchestrate" is compact too (change 0220): an orchestrating session reads
+// the workspace's own AGENTS.md, which carries the delivery playbook in full;
+// inside one repository the commands only need to be discoverable.
+const COMPACT_MOMENTS = new Set(["Orchestrate", "Maintain"]);
 
 // The full managed section, heading included, between the markers.
 //
@@ -516,6 +542,27 @@ 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.20.0": [
+    "Work across repositories is a delivery: from the workspace, `doctrina delivery new \"<title>\" --ref <id>`, then follow its playbook — route, one change per repository with `doctrina work \"<title>\" --delivery <id>`, close each, then `doctrina delivery close <id>`.",
+    "Write tasks as self-contained cards (indented `Files:`, `Requirement:`, `Verify:` lines) and hand an executor `doctrina change card <id>`; one writer per repository, and only the planner closes (ADR 0030).",
+    "An existing codebase with no specs: `doctrina intake --from-code`, then the absorb playbook — describe what the code does today and send what it cannot tell to the human as open questions.",
+    "A repository that may not carry `.doctrina/` is a workspace shadow: its `.doctrina/` is a link, hidden from its git — never commit it there; commit the workspace.",
+    "MCP tools declared in the workspace are read-only unless declared `write`: a refused or held call means ask the human, never route around it.",
+  ],
+  "0.19.0": [
+    "A request that changes behaviour is a change opened BEFORE code, whether or not it names Doctrina; say its id in your first sentence to the human, and repeat the `Tell the human:` line `work` and `close` print.",
+    "`doctrina context <cap> --for \"<task>\" --concat` is now lean (no AGENTS.md, ADR digests, the spec sliced to the task) — read it before editing; `prime` is state, not the spec. `--full` gives the whole text.",
+    "Project skills are exported to `.agents/skills/` and `.claude/skills/`, where your agent lists skills — use them; edit `.doctrina/skills/`, never the exports.",
+    "`work` holds (exit 3) a request that repeats an open change or one archived in the last 14 days: resume it, or tell the human it is done and where; `--force` only for genuinely new work.",
+    "Hooks: `doctrina adapter add claude|cursor` merges session/prompt hooks (`prime --hook`, `prime --pulse`) into the agent's settings.",
+  ],
+  "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/context-slice.js

@@ -0,0 +1,118 @@
+// @ts-check
+import { fold } from "./lexicon.js";
+import { getSection } from "./doc-model.js";
+
+// The lean read pack (change 0216).
+//
+// A field review: the agent ran `prime` and `work` and skipped `context`,
+// although AGENTS.md calls it the read for ANY task. Measured on this
+// repository, the reason is the price: `context gates --concat` was ~40k
+// tokens — AGENTS.md again (the agent already carries it), the whole spec,
+// and every accepted ADR in full — and `--for "<task>"` cut nothing, because
+// retrieval only degraded the pack once the 50k budget overflowed. These
+// cuts are the default now; `--full` restores the whole text.
+
+// How much of an ADR's Decision a digest keeps.
+const ADR_DIGEST_CHARS = 700;
+// How many requirements and criteria a sliced spec keeps at most, each.
+const SLICE_MAX_ITEMS = 25;
+
+/**
+ * An ADR as a reader deciding whether it binds the task needs it: the
+ * title and the opening of its Decision section. `doctrina show NNNN`
+ * reads the rest.
+ *
+ * @param {string} text
+ * @param {string} title
+ * @param {string} id   four-digit ADR number
+ */
+export function adrDigest(text, title, id) {
+  const decision = (getSection(text.replace(/\r\n/g, "\n"), "Decision") ?? "")
+    .split("\n").filter((l) => !l.trim().startsWith("<!--")).join("\n").trim();
+  const clipped = decision.length > ADR_DIGEST_CHARS
+    ? `${decision.slice(0, ADR_DIGEST_CHARS).replace(/\s+\S*$/, "")} …`
+    : decision;
+  return [`# ${title}`, "", clipped || "(no Decision section)", "",
+    `(digest — full text: \`doctrina show ${id}\`, or \`context --full\`)`].join("\n");
+}
+
+/**
+ * A spec cut to what the task is about: its headers, its Purpose, and the
+ * requirements and criteria that match the query best — the rest named by
+ * count, never silently dropped. Deterministic: an item's score is how many
+ * distinct query terms it contains; the items scoring at least half the
+ * best score are kept, best first in document order, up to a cap per list.
+ *
+ * @param {string} text
+ * @param {string[]} queryTerms  already folded, stop words removed
+ * @param {string} rel           the spec's path, for the footer
+ * @returns {{ text: string, kept: number, total: number } | null}  null when nothing matched
+ */
+export function sliceSpec(text, queryTerms, rel) {
+  if (queryTerms.length === 0) return null;
+  const lines = text.replace(/\r\n/g, "\n").split("\n");
+  // Items: a bullet or numbered entry with its continuation lines.
+  /** @type {Array<{ start: number, end: number, kind: "req"|"crit", score: number }>} */
+  const items = [];
+  let section = "";
+  for (let i = 0; i < lines.length; i++) {
+    const l = lines[i];
+    if (/^##\s/.test(l)) { section = l; continue; }
+    const req = /^##\s+Requirements/i.test(section) && /^\s*-\s+\S/.test(l);
+    const crit = /^##\s+Acceptance criteria/i.test(section) && /^\s*\d+\.\s+\S/.test(l);
+    if (!req && !crit) continue;
+    let end = i;
+    while (end + 1 < lines.length && /^\s+\S/.test(lines[end + 1]) && !/^\s*(-|\d+\.)\s/.test(lines[end + 1])) end += 1;
+    const body = fold(lines.slice(i, end + 1).join(" "));
+    const score = queryTerms.filter((t) => body.includes(t)).length;
+    items.push({ start: i, end, kind: req ? "req" : "crit", score });
+    i = end;
+  }
+  const best = Math.max(0, ...items.map((it) => it.score));
+  if (best === 0) return null;
+  const floor = Math.max(1, Math.ceil(best / 2));
+  const keep = new Set();
+  for (const kind of ["req", "crit"]) {
+    items.filter((it) => it.kind === kind && it.score >= floor)
+      .sort((a, b) => b.score - a.score || a.start - b.start)
+      .slice(0, SLICE_MAX_ITEMS)
+      .forEach((it) => keep.add(it.start));
+  }
+
+  const out = [];
+  section = "";
+  let omitted = 0;
+  const flushOmitted = () => {
+    if (omitted > 0) out.push(`  … ${omitted} not matching the task`);
+    omitted = 0;
+  };
+  for (let i = 0; i < lines.length; i++) {
+    const l = lines[i];
+    if (/^##\s/.test(l)) {
+      flushOmitted();
+      section = l;
+      out.push(l);
+      continue;
+    }
+    const item = items.find((it) => it.start === i);
+    if (item) {
+      if (keep.has(i)) { flushOmitted(); out.push(...lines.slice(i, item.end + 1)); } else omitted += 1;
+      i = item.end;
+      continue;
+    }
+    // Headers, Purpose and subsection headings are kept; prose in the other
+    // sections (Out of scope, Maturity, …) is the first thing a task can do
+    // without.
+    const inLists = /^##\s+(Requirements|Acceptance criteria)/i.test(section);
+    const prose = section !== "" && !/^##\s+Purpose/i.test(section) && !inLists;
+    if (/^###\s/.test(l)) { flushOmitted(); out.push(l); continue; }
+    if (section === "" || /^##\s+Purpose/i.test(section)) { out.push(l); continue; }
+    if (inLists && l.trim() !== "") continue;
+    if (!prose) out.push(l);
+  }
+  flushOmitted();
+  const kept = keep.size;
+  out.push("", `(sliced for "${queryTerms.join(" ")}" — ${kept} of ${items.length} requirements and criteria kept; ` +
+    `full text: ${rel}, or \`context --full\`)`);
+  return { text: out.join("\n").replace(/\n{3,}/g, "\n\n"), kept, total: items.length };
+}

package/src/lib/delivery.js

@@ -0,0 +1,208 @@
+// @ts-check
+import { readdirSync } from "node:fs";
+import path from "node:path";
+import { isDir, isFile, read, write } from "./fs-ops.js";
+import { listHeader } from "./scan.js";
+import { checklistProgress, setHeader } from "./doc-model.js";
+import { terms } from "./lexicon.js";
+import { slugify, padNumber } from "./dates.js";
+import { artifactRootOf } from "./workspace.js";
+
+// A DELIVERY is one item of work that crosses repositories (ADR 0030): a
+// story, a screen, a fix. It lives in the workspace's `deliveries/` and
+// holds what no single repository owns — the story, the sources, the plan
+// across projects, the release. Each project it touches gets ONE change,
+// opened in that repository and carrying `- **Delivery:** <id>`, so the
+// delivery's state is READ from the projects, never copied into it.
+
+export const DELIVERY_FILE = "delivery.md";
+export const DELIVERY_ID = /^\d{4}-[a-z0-9][a-z0-9-]*$/;
+
+export function deliveriesDir(wsDir) {
+  return path.join(wsDir, "deliveries");
+}
+
+/** Every delivery on disk, oldest first. */
+export function listDeliveries(wsDir) {
+  const dir = deliveriesDir(wsDir);
+  if (!isDir(dir)) return [];
+  return readdirSync(dir).filter((d) => DELIVERY_ID.test(d) && isFile(path.join(dir, d, DELIVERY_FILE))).sort()
+    .map((id) => readDelivery(wsDir, id));
+}
+
+export function deliveryPath(wsDir, id) {
+  return path.join(deliveriesDir(wsDir), id, DELIVERY_FILE);
+}
+
+/** A delivery by id — or by its number alone (`1`, `0001`). Null when absent. */
+export function resolveDeliveryId(wsDir, ref) {
+  if (!ref) return null;
+  if (DELIVERY_ID.test(ref) && isFile(deliveryPath(wsDir, ref))) return ref;
+  if (/^\d+$/.test(ref)) {
+    const prefix = padNumber(Number(ref)) + "-";
+    return listDeliveries(wsDir).find((d) => d.id.startsWith(prefix))?.id ?? null;
+  }
+  return null;
+}
+
+export function readDelivery(wsDir, id) {
+  // CRLF on a Windows checkout: a `$` would leave the \r in the title.
+  const text = read(deliveryPath(wsDir, id)).replace(/\r\n/g, "\n");
+  const title = text.match(/^#\s+Delivery\s+\S+\s+[—-]\s+(.+)$/m)?.[1]?.trim() ?? id;
+  const projects = (listHeader(text, "Projects") ?? "").split(",").map((s) => s.trim()).filter((s) => s && s !== "—");
+  return {
+    id, title, text,
+    status: (listHeader(text, "Status") ?? "open").toLowerCase(),
+    date: listHeader(text, "Date") ?? null,
+    closed: listHeader(text, "Closed") ?? null,
+    ref: listHeader(text, "Ref") ?? "—",
+    projects,
+  };
+}
+
+export function nextDeliveryId(wsDir, title) {
+  const numbers = listDeliveries(wsDir).map((d) => Number(d.id.slice(0, 4)));
+  const next = (numbers.length ? Math.max(...numbers) : 0) + 1;
+  return `${padNumber(next)}-${slugify(title).slice(0, 40).replace(/-+$/, "") || "delivery"}`;
+}
+
+/** Rewrite one list header of a delivery (adding it when absent). */
+export function setDeliveryHeader(wsDir, id, name, value) {
+  const p = deliveryPath(wsDir, id);
+  let text = read(p);
+  const next = setHeader(text, name, value);
+  if (next !== null) text = next;
+  else text = text.replace(/^(- \*\*Projects:\*\*.*)$/m, `$1\n- **${name}:** ${value}`);
+  write(p, text, { force: true });
+}
+
+/**
+ * Projects ranked against a delivery's text — how many of its terms each
+ * project's name, role, description and capability names share. A hint for
+ * the orchestrator, never a decision (ADR 0005): `delivery route` is where
+ * the projects are chosen.
+ */
+export function rankProjects(wsDir, ws, text) {
+  const want = new Set(terms(text));
+  const out = [];
+  for (const p of ws.projects) {
+    const caps = capabilityNames(wsDir, p);
+    const words = new Set(terms([p.name, p.role, p.about, ...caps].join(" ")));
+    const shared = [...want].filter((t) => words.has(t));
+    out.push({ project: p, score: shared.length, shared, capabilities: caps });
+  }
+  return out.sort((a, b) => b.score - a.score || a.project.name.localeCompare(b.project.name));
+}
+
+function capabilityNames(wsDir, project) {
+  const specs = path.join(artifactRootOf(wsDir, project), ".doctrina", "specs");
+  if (!isDir(specs)) return [];
+  return readdirSync(specs).filter((d) => isFile(path.join(specs, d, "spec.md")));
+}
+
+/** The projects in dependency order: a project after every project it depends on. */
+export function dependencyOrder(ws, names) {
+  const byName = new Map(ws.projects.map((p) => [p.name, p]));
+  const out = [];
+  const seen = new Set();
+  const visit = (name, trail) => {
+    if (seen.has(name) || trail.has(name)) return;
+    trail.add(name);
+    for (const dep of byName.get(name)?.dependsOn ?? []) if (names.includes(dep)) visit(dep, trail);
+    seen.add(name);
+    out.push(name);
+  };
+  for (const n of names) visit(n, new Set());
+  return out;
+}
+
+/**
+ * The changes each routed project carries for this delivery — open ones in
+ * `changes/`, closed ones in `changes/archive/` — read from the projects.
+ */
+export function deliveryChanges(wsDir, ws, delivery) {
+  const out = [];
+  for (const name of delivery.projects) {
+    const project = ws.projects.find((p) => p.name === name);
+    if (!project) {
+      out.push({ project: name, missing: "not registered in the workspace", changes: [] });
+      continue;
+    }
+    const changesDir = path.join(artifactRootOf(wsDir, project), ".doctrina", "changes");
+    const changes = [];
+    for (const { dir, archived } of [{ dir: changesDir, archived: false }, { dir: path.join(changesDir, "archive"), archived: true }]) {
+      if (!isDir(dir)) continue;
+      for (const entry of readdirSync(dir).sort()) {
+        const proposal = path.join(dir, entry, "proposal.md");
+        if (entry === "archive" || !isFile(proposal)) continue;
+        const text = read(proposal);
+        if ((listHeader(text, "Delivery") ?? "").trim() !== delivery.id) continue;
+        const tasks = path.join(dir, entry, "tasks.md");
+        const progress = isFile(tasks) ? checklistProgress(read(tasks)) : { total: 0, done: 0 };
+        changes.push({
+          id: archived ? entry.replace(/^\d{4}-\d{2}-\d{2}-/, "") : entry,
+          archived,
+          status: archived ? "archived" : (listHeader(text, "Status") ?? "proposed").toLowerCase(),
+          tasksDone: progress.done, tasksTotal: progress.total,
+        });
+      }
+    }
+    out.push({ project: name, path: project.path, changes });
+  }
+  return out;
+}
+
+/** A section's own text: comments and blank lines removed. Empty string when absent. */
+export function sectionText(text, heading) {
+  const lines = String(text).replace(/\r\n/g, "\n").replace(/<!--[\s\S]*?-->/g, "").split("\n");
+  const at = lines.findIndex((l) => l.trim() === `## ${heading}`);
+  if (at < 0) return "";
+  const out = [];
+  for (const l of lines.slice(at + 1)) {
+    if (/^## /.test(l)) break;
+    if (l.trim()) out.push(l.trim());
+  }
+  return out.join("\n");
+}
+
+/** Days between two YYYY-MM-DD dates, or null. */
+export function daysBetween(from, to) {
+  const a = Date.parse(String(from ?? "") + "T00:00:00Z");
+  const b = Date.parse(String(to ?? "") + "T00:00:00Z");
+  return Number.isNaN(a) || Number.isNaN(b) ? null : Math.round((b - a) / 86400000);
+}
+
+/**
+ * The record a delivery keeps of its own work (change 0224): the story it
+ * came from, every Release claim ticked, and at least one line of what was
+ * watched after the release. The changes prove the code; these prove the
+ * delivery reached its users and was looked at once it had.
+ */
+export function recordBlockers(delivery) {
+  const out = [];
+  if (sectionText(delivery.text, "Story") === "") out.push("## Story is empty — copy the tracker item's story and acceptance criteria, verbatim");
+  const release = sectionText(delivery.text, "Release");
+  const open = release.split("\n").filter((l) => /^[-*]\s*\[\s\]/.test(l));
+  for (const box of open) out.push(`## Release: unticked — ${box.replace(/^[-*]\s*\[\s\]\s*/, "")}`);
+  if (sectionText(delivery.text, "Observability") === "") out.push("## Observability is empty — record what was watched after the release (monitor, dashboard or query, the window, what it showed)");
+  return out;
+}
+
+/**
+ * Everything that keeps a delivery from closing. Each routed project must
+ * carry at least one change for it, and every such change must be archived;
+ * the delivery's own record must be written (recordBlockers).
+ */
+export function deliveryBlockers(wsDir, ws, delivery) {
+  const blockers = [];
+  if (delivery.projects.length === 0) blockers.push("no project routed — `doctrina delivery route <id> <a,b>`");
+  for (const row of deliveryChanges(wsDir, ws, delivery)) {
+    if (row.missing) blockers.push(`${row.project}: ${row.missing}`);
+    else if (row.changes.length === 0) blockers.push(`${row.project}: no change carries this delivery — open one there with \`doctrina work "<title>" --delivery ${delivery.id}\``);
+    else for (const ch of row.changes.filter((x) => !x.archived)) {
+      blockers.push(`${row.project}: change ${ch.id} is ${ch.status} (${ch.tasksDone}/${ch.tasksTotal} tasks) — close it there with \`doctrina close ${ch.id}\``);
+    }
+  }
+  blockers.push(...recordBlockers(delivery));
+  return blockers;
+}

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/metrics-model.js

@@ -48,6 +48,16 @@ export function computeSnapshot(commits, since) {
     for (const f of cm.files) lastTouch.set(f, cm.ts);
   }
 
+  // Workflow adherence (change 0218): of the commits that changed code, how
+  // many carried a change — touched `.doctrina/changes/`, or named one in the
+  // subject. A field review found an agent that "knows the framework
+  // exists" and still went straight to code when the request did not name
+  // it; this is the number that says whether the hooks and the contract
+  // moved that. A proxy, like re-edit: a typo fix needs no change.
+  const code = commits.filter((cm) => cm.files.some(isCodePath));
+  const withChange = code.filter((cm) =>
+    cm.files.some((f) => f.startsWith(".doctrina/changes/")) || CHANGE_REF.test(cm.subject));
+
   return {
     generated: today(),
     window: since,
@@ -57,10 +67,22 @@ export function computeSnapshot(commits, since) {
     fix_share: round(fixes / total),
     reedit_window_days: REEDIT_WINDOW_DAYS,
     reedit_rate: round(reedits / total),
+    code_commits: code.length,
+    change_adherence: code.length > 0 ? round(withChange.length / code.length) : null,
     top_churn: topChurn,
   };
 }
 
+// A subject that names a change: "Change 0212", or an id like "0212-x".
+const CHANGE_REF = /\bchange\s+\d{4}\b|\b\d{4}-[a-z0-9][a-z0-9-]*\b/i;
+
+// Code, for the adherence rate: not the Doctrina tree, not an agent's own
+// config or generated skills, not prose.
+function isCodePath(f) {
+  if (/^\.(doctrina|agents|claude|cursor)\//.test(f)) return false;
+  return !/\.(md|mdx|txt)$/i.test(f);
+}
+
 
 export function parseLog(stdout) {
   const commits = [];
@@ -174,7 +196,7 @@ export function latestSnapshot(projectRoot, excludeBase = null) {
  * @param {ReturnType<typeof readSeries>} series
  */
 export function trend(series) {
-  const rates = ["revert_rate", "fix_share", "reedit_rate"];
+  const rates = ["revert_rate", "fix_share", "reedit_rate", "change_adherence"];
   if (series.length < 2) return { span: series.length, rows: [] };
   const first = series[0];
   const last = series[series.length - 1];

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", "absorb"];

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"]);