doctrina-cli 0.18.0 → 0.21.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",
 ];
@@ -48,6 +50,7 @@ export const OPERATIONS = [
   ["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"],
@@ -82,6 +85,20 @@ 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 tick", "List or tick a delivery's Release claims"],
+  ["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)"],
@@ -127,8 +144,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" },
@@ -146,6 +163,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" },
@@ -158,7 +178,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.
@@ -192,7 +212,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]);
@@ -317,7 +340,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.
 //
@@ -517,6 +543,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.21.0": [
+    "At a workspace root, `next`, `handoff`, `status`, `validate`, `context`, `doctor` and `metrics` answer for the workspace; never `doctrina init` there or in a shadowed repository's clone — the commands name `doctrina workspace attach` instead.",
+    "A task card carries the delta, the delivery's story and every binding decision, global ones included: as an executor, stop and report when the story or the task contradicts one; a card on placeholder tasks means the planner writes them first (`doctrina work --resume <id>`).",
+    "Run the command lines the CLI prints as printed: paths and titles are quoted for the shell, and tracker text stays data.",
+    "Cursor: the core loop is skills in `.cursor/skills/doctrina-*/`; run `doctrina upgrade --write` to move an older install. With a tool declared the guard fails closed — a refused call means fix the install or ask the human.",
+    "Absorb: after writing specs by hand run `doctrina validate --fix`; a stored code inventory resumes with a bare `doctrina intake`, never `--from-code` again.",
+  ],
+  "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\"`.",

package/src/lib/context-slice.js

@@ -0,0 +1,149 @@
+// @ts-check
+import { fold } from "./lexicon.js";
+import { commentRanges, 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;
+
+/**
+ * A change file as a reader needs it: without its HTML comments (change
+ * 0228). The proposal, tasks and delta templates carry their authoring
+ * instructions in comments — forty lines of "for ADDED… for MODIFIED…" in
+ * every delta — and the change in focus enters the pack whole, so a change
+ * with eight deltas spent ~2.6k tokens repeating the template to an agent
+ * that was reading, not writing. Null when the text has no comment.
+ *
+ * @param {string} text
+ * @returns {string | null}
+ */
+export function withoutComments(text) {
+  const lf = String(text).replace(/\r\n/g, "\n");
+  const ranges = commentRanges(lf);
+  if (ranges.length === 0) return null;
+  let out = "";
+  let at = 0;
+  for (const [a, b] of ranges) {
+    out += lf.slice(at, a);
+    at = b;
+  }
+  out += lf.slice(at);
+  return out.replace(/[ \t]+\n/g, "\n").replace(/\n{3,}/g, "\n\n").trim();
+}
+
+/**
+ * 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;
+  // Read without the template's comments (second audit, change 0233). The
+  // EARS comment lists the five forms as bullets — "- Ubiquitous: The system
+  // shall <action>." — and they were counted as requirements: every pack of
+  // a scaffolded spec reported "… 5 not matching the task" for bullets no
+  // one wrote, and carried the forty-line header comment besides.
+  const lines = (withoutComments(text) ?? 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;
+  const shownTerms = queryTerms.length > 12 ? `${queryTerms.slice(0, 12).join(" ")} …` : queryTerms.join(" ");
+  out.push("", `(sliced for "${shownTerms}" — ${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,286 @@
+// @ts-check
+import { readdirSync } from "node:fs";
+import path from "node:path";
+import { eolOf, isDir, isFile, read, withEol, write } from "./fs-ops.js";
+import { listHeader } from "./scan.js";
+import { checklistProgress, maskComments, parseChecklist, setHeader } from "./doc-model.js";
+import { parseLedger } from "./ledger.js";
+import { terms } from "./lexicon.js";
+import { slugify, padNumber } from "./dates.js";
+import { artifactRootOf, projectState } 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:\*\*[^\r\n]*)/m, `$1\n- **${name}:** ${value}`);
+  write(p, withEol(text, eolOf(read(p))), { 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, placeholders: 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,
+          // Scaffold boxes no one wrote (third audit, change 0234): counted
+          // as tasks, they read "3 tasks left — hand the next card" for a
+          // change whose card command answers that none is written.
+          placeholders: progress.placeholders ?? 0,
+        });
+      }
+    }
+    // Abandoned for this delivery: the ledger keeps the delivery's id (change 0234).
+    const ledger = path.join(changesDir, "archive", "LEDGER.md");
+    const abandoned = isFile(ledger)
+      ? parseLedger(read(ledger)).entries.filter((e) => e.kind === "abandoned" && new RegExp(`\\(delivery ${delivery.id}\\)\\s*$`).test(e.title))
+        .map((e) => ({ id: e.id, reason: e.title.replace(/^abandoned\s*(—\s*)?/i, "").replace(/\s*\(delivery [^)]*\)\s*$/, "") }))
+      : [];
+    out.push({ project: name, path: project.path, absent: !isDir(project.path), changes, abandoned });
+  }
+  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");
+  // The same boxes `delivery tick` lists and ticks — one reader, so a box
+  // the check holds you to is always one the CLI can tick.
+  for (const box of releaseBoxes(delivery.text).filter((b) => !b.checked)) out.push(`## Release: unticked — ${box.text}`);
+  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.absent) blockers.push(`${row.project}: the repository is not at ${row.path} — \`doctrina workspace attach ${row.project} --path <dir>\``);
+    else if (row.changes.length === 0 && row.abandoned?.length) blockers.push(`${row.project}: its change ${row.abandoned.map((a) => a.id).join(", ")} was abandoned — re-route the delivery without ${row.project}, or open a new change there with \`doctrina work "<title>" --delivery ${delivery.id}\``);
+    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;
+}
+
+/**
+ * The `## Release` boxes of a delivery, in order, with their line index in
+ * the LF-normalised text (change 0226). The other sections are prose the
+ * planner writes; these are claims, and a claim is ticked through the CLI.
+ */
+export function releaseBoxes(text) {
+  // One owner for the box grammar (ADR 0021): the document model reads the
+  // boxes; a box inside a comment is the template's example, not a claim.
+  const lf = String(text).replace(/\r\n/g, "\n");
+  return parseChecklist(maskComments(lf), { section: "Release" })
+    .filter((b) => b.section === "Release")
+    .map((b, i) => ({ ordinal: i + 1, line: b.line, checked: b.checked, text: b.text }));
+}
+
+/** The text with the given Release boxes ticked (all when `ordinals` is "all"). */
+export function tickRelease(text, ordinals) {
+  const lines = String(text).replace(/\r\n/g, "\n").split("\n");
+  for (const box of releaseBoxes(text)) {
+    if (ordinals === "all" || ordinals.includes(box.ordinal)) {
+      lines[box.line] = lines[box.line].replace(/\[\s\]/, "[x]");
+    }
+  }
+  return lines.join("\n");
+}
+
+/**
+ * Projects a delivery cannot be routed to yet (change 0226): one whose
+ * repository is missing, or one still `pending` — no spec to write a delta
+ * against, so the change opened there would have nothing to change.
+ * @returns {{ name: string, state: string, reason: string, path: string }[]}
+ */
+export function unroutable(wsDir, ws, names) {
+  const out = [];
+  for (const name of names) {
+    const project = ws.projects.find((p) => p.name === name);
+    if (!project) continue;
+    const st = projectState(wsDir, project);
+    if (st.state !== "ready") out.push({ name, state: st.state, reason: st.reason, path: project.path });
+  }
+  return out;
+}
+
+/**
+ * Open changes in a routed repository that do NOT belong to this delivery
+ * (change 0226). Each is a second writer the planner must sequence: one
+ * writer per repository at a time holds across deliveries too.
+ * @returns {{ project: string, id: string, delivery: string|null }[]}
+ */
+export function otherWriters(wsDir, ws, delivery) {
+  const out = [];
+  for (const name of delivery.projects) {
+    const project = ws.projects.find((p) => p.name === name);
+    if (!project) continue;
+    const changesDir = path.join(artifactRootOf(wsDir, project), ".doctrina", "changes");
+    if (!isDir(changesDir)) continue;
+    for (const entry of readdirSync(changesDir).sort()) {
+      const proposal = path.join(changesDir, entry, "proposal.md");
+      if (entry === "archive" || !isFile(proposal)) continue;
+      const of = (listHeader(read(proposal), "Delivery") ?? "").trim() || null;
+      if (of !== delivery.id) out.push({ project: name, id: entry, delivery: of });
+    }
+  }
+  return out;
+}

package/src/lib/docs-impact.js

@@ -257,10 +257,16 @@ export function documentedSurfaceSignals(changeDir, projectRoot = null) {
     signals.push(`endpoints: ${[...routes].sort().slice(0, 6).join(", ")}`);
   }
 
+  // An UPPER_SNAKE name is an environment variable when something says so
+  // (change 0239): the shape alone also matches an error code
+  // (`CONTA_BLOQUEADA`) or a constant (`MAX_FALHAS`), and every change that
+  // merely cited one was asked to document an "environment" it never touched.
+  const exampleNames = projectRoot === null ? new Set() : envExampleNames(projectRoot);
   const envVars = new Set();
   for (const m of code.matchAll(/\b([A-Z][A-Z0-9]*(?:_[A-Z0-9]+)+)\b/g)) {
     // Not twice: a declared variable is already reported by name above.
-    if (!touchedDeclared.includes(m[1])) envVars.add(m[1]);
+    if (touchedDeclared.includes(m[1])) continue;
+    if (looksLikeEnv(m[1], text) || exampleNames.has(m[1])) envVars.add(m[1]);
   }
   if (envVars.size > 0) {
     signals.push(`environment: ${[...envVars].sort().slice(0, 8).join(", ")}`);
@@ -408,3 +414,32 @@ export function checkDocsImpact(projectRoot, changeDir) {
     reason: "alters a documented surface but no docs/ or README change accompanies it",
   };
 }
+
+// The suffixes configuration read from the environment carries.
+const ENV_SUFFIX = /_(URL|URI|DSN|HOST|PORT|ENDPOINT|KEY|TOKEN|SECRET|PASSWORD|PASS|USER|USERNAME|PATH|DIR|FILE|HOME|ENV|MODE|LEVEL|TIMEOUT|REGION|BUCKET|ENABLED|DISABLED|DEBUG|FLAG|PROFILE)$/;
+
+/**
+ * Whether the change text marks a name as an environment variable: read the
+ * way code reads one (`process.env.X`, `$X`, `${X}`, `getenv("X")`,
+ * `os.environ["X"]`, `X=`), named on a line that speaks of the environment,
+ * or carrying a configuration suffix (`_URL`, `_TOKEN`, `_PORT`…).
+ * @param {string} name
+ * @param {string} text  the change's authored text
+ */
+export function looksLikeEnv(name, text) {
+  if (ENV_SUFFIX.test(name)) return true;
+  const n = name.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  if (new RegExp(`(process\\.env\\.|process\\.env\\[["'\`]|\\benv\\.|\\$\\{?|getenv\\(["']|environ(?:\\.get\\(|\\[)["']|ENV\\[["'])${n}\\b|\\b${n}=`).test(text)) return true;
+  return text.split("\n").some((line) => line.includes(name) && /\b(env|environment|environment variable|variável de ambiente|ambiente|secret|segredo|\.env)\b/i.test(line));
+}
+
+/** The variable names a project's env example files declare. */
+function envExampleNames(projectRoot) {
+  const out = new Set();
+  for (const f of [".env.example", ".env.sample", ".env.template", ".env.dist", "example.env"]) {
+    const file = path.join(projectRoot, f);
+    if (!isFile(file)) continue;
+    for (const m of read(file).matchAll(/^\s*(?:export\s+)?([A-Z][A-Z0-9_]*)\s*=/gm)) out.add(m[1]);
+  }
+  return out;
+}

package/src/lib/fs-ops.js

@@ -19,6 +19,29 @@ import path from "node:path";
 // A file that had one loses it when a command rewrites it. That is a
 // normalisation, and the right one — nothing in this tree is served by
 // keeping it.
+/**
+ * The line ending a file already uses: CRLF when it carries one, LF otherwise.
+ * A command that rewrites a file a person owns keeps the file's ending — a
+ * Windows checkout with `core.autocrlf` stores CRLF, and turning it into LF
+ * on a tick makes every line of the file show as changed in the diff.
+ * @param {string} text
+ * @returns {"\r\n"|"\n"}
+ */
+export function eolOf(text) {
+  return /\r\n/.test(String(text)) ? "\r\n" : "\n";
+}
+
+/**
+ * `text` with every line ending made `eol` — what a rewrite hands to `write`
+ * after editing in LF, so an inserted line never mixes endings.
+ * @param {string} text
+ * @param {"\r\n"|"\n"} eol
+ */
+export function withEol(text, eol) {
+  const lf = String(text).replace(/\r\n/g, "\n");
+  return eol === "\n" ? lf : lf.replace(/\n/g, "\r\n");
+}
+
 export function read(p) {
   const text = readFileSync(p, "utf8");
   return text.charCodeAt(0) === 0xFEFF ? text.slice(1) : text;

package/src/lib/intake-model.js

@@ -15,7 +15,7 @@ import { stateWord } from "./spec-ops.js";
 // Clarification gate (review Topic A). A description too thin to spec from is
 // the moment to ask the user, not to let the agent invent requirements. Prints
 // the specific gaps before the bootstrap playbook; advisory, never blocking —
-// the intake is still captured verbatim (the playbook step 6 resolves it).
+// the intake is still captured verbatim (the playbook step 8 resolves it).
 /**
  * Does this argument read as a FILE PATH, or as the description itself?
  *