doctrina-cli 0.20.0 → 0.21.0

package/src/lib/commands.js

@@ -96,6 +96,7 @@ export const OPERATIONS = [
   ["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"],
@@ -542,6 +543,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.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).",

package/src/lib/context-slice.js

@@ -1,6 +1,6 @@
 // @ts-check
 import { fold } from "./lexicon.js";
-import { getSection } from "./doc-model.js";
+import { commentRanges, getSection } from "./doc-model.js";
 
 // The lean read pack (change 0216).
 //
@@ -17,6 +17,31 @@ 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`
@@ -50,7 +75,12 @@ export function adrDigest(text, title, id) {
  */
 export function sliceSpec(text, queryTerms, rel) {
   if (queryTerms.length === 0) return null;
-  const lines = text.replace(/\r\n/g, "\n").split("\n");
+  // 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 = [];
@@ -112,7 +142,8 @@ export function sliceSpec(text, queryTerms, rel) {
   }
   flushOmitted();
   const kept = keep.size;
-  out.push("", `(sliced for "${queryTerms.join(" ")}" — ${kept} of ${items.length} requirements and criteria kept; ` +
+  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

@@ -1,12 +1,13 @@
 // @ts-check
 import { readdirSync } from "node:fs";
 import path from "node:path";
-import { isDir, isFile, read, write } from "./fs-ops.js";
+import { eolOf, isDir, isFile, read, withEol, write } from "./fs-ops.js";
 import { listHeader } from "./scan.js";
-import { checklistProgress, setHeader } from "./doc-model.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 } from "./workspace.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
@@ -72,8 +73,8 @@ export function setDeliveryHeader(wsDir, id, name, value) {
   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 });
+  else text = text.replace(/^(- \*\*Projects:\*\*[^\r\n]*)/m, `$1\n- **${name}:** ${value}`);
+  write(p, withEol(text, eolOf(read(p))), { force: true });
 }
 
 /**
@@ -138,16 +139,26 @@ export function deliveryChanges(wsDir, ws, delivery) {
         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 };
+        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,
         });
       }
     }
-    out.push({ project: name, path: project.path, changes });
+    // 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;
 }
@@ -181,9 +192,9 @@ export function daysBetween(from, to) {
 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*/, "")}`);
+  // 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;
 }
@@ -198,6 +209,8 @@ export function deliveryBlockers(wsDir, ws, delivery) {
   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}\``);
@@ -206,3 +219,68 @@ export function deliveryBlockers(wsDir, ws, delivery) {
   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?
  *

package/src/lib/json-out.js

@@ -71,12 +71,14 @@ export function deferJson() {
  * Write the held payload with the exit code the command actually returned,
  * and leave deferred mode. A no-op when the command emitted nothing.
  */
+/** Write the held payload; false when the command held none. */
 export function flushJson(code) {
   deferring = false;
-  if (!held) return;
+  if (!held) return false;
   const { command, data } = held;
   held = null;
   writeEnvelope(command, data, { ok: code === EXIT.OK, exitCode: code });
+  return true;
 }
 
 // Print a structured payload. `command` is the invocation, `data` whatever
@@ -165,6 +167,12 @@ export async function captureOutput(fn) {
   try {
     const code = await fn();
     return { code: code ?? EXIT.OK, stdout, stderr };
+  } catch (err) {
+    // A thrown precondition still answers inside the envelope (change 0234):
+    // it escaped as English on stderr, with no JSON on stdout at all.
+    stderr.push(`error: ${err?.message ?? err}`);
+    if (err?.remedy) stderr.push(`hint: run ${err.remedy} first, then retry`);
+    return { code: err?.exitCode ?? EXIT.GATE, stdout, stderr, error: err };
   } finally {
     console.log = origLog;
     console.error = origError;

package/src/lib/shell.js

@@ -0,0 +1,45 @@
+// @ts-check
+import process from "node:process";
+
+// THE COMMANDS THE CLI PRINTS ARE RUN AS PRINTED (fourth audit, change 0235).
+//
+// `next`, `delivery status`, the playbooks and the hub hand an agent a line
+// to paste into its shell: `cd <repo> && doctrina work "<title>" --delivery
+// <id>`. The title comes from the tracker — text the delivery playbook calls
+// data, never an instruction — and it was interpolated between double quotes
+// as it came: a story titled `Fix $(curl … | sh)` became a command the agent
+// ran, and a repository under `~/my api/` became a `cd` into `~/my`.
+
+// Inside double quotes a POSIX shell still expands these.
+const DOUBLE_QUOTE_UNSAFE = /["`$\\!]/;
+const BARE_PATH = /^[A-Za-z0-9_./:\\~+@%=,-]+$/;
+
+/**
+ * One shell argument, quoted so the shell reads it back verbatim. Plain text
+ * keeps the double quotes every surface has always printed; text a double
+ * quote would still expand is single-quoted — POSIX `'\''` for an embedded
+ * quote, PowerShell's `''` on Windows.
+ * @param {string} value
+ * @param {NodeJS.Platform} [platform]
+ */
+export function qarg(value, platform = process.platform) {
+  const s = String(value ?? "");
+  if (!DOUBLE_QUOTE_UNSAFE.test(s)) return `"${s}"`;
+  const inner = platform === "win32" ? s.replace(/'/g, "''") : s.replace(/'/g, "'\\''");
+  return `'${inner}'`;
+}
+
+/**
+ * A path as a shell argument: bare when nothing in it needs quoting.
+ * @param {string} dir
+ * @param {NodeJS.Platform} [platform]
+ */
+export function qpath(dir, platform = process.platform) {
+  const s = String(dir ?? "");
+  return BARE_PATH.test(s) ? s : qarg(s, platform);
+}
+
+/** `cd <dir> && <command>`, with the directory quoted when it must be. */
+export function cdThen(dir, command) {
+  return `cd ${qpath(dir)} && ${command}`;
+}

package/src/lib/snapshot.js

@@ -155,7 +155,11 @@ export function openChanges(projectRoot) {
     // The capabilities its deltas target — what `prime` turns into the
     // exact read command for the change (change 0217).
     const capabilities = deltaCapabilities(path.join(changesDir, id));
-    out.push({ id, title, status, tasksDone, tasksTotal, unchecked, date, ageDays: ageInDays(date), capabilities });
+    // The delivery a change belongs to (change 0226): a session opened in the
+    // repository — an executor's, or a human's — sees it is one part of a
+    // larger item of work, not a change on its own.
+    const delivery = proposal ? (listHeader(proposal, "Delivery") ?? null) : null;
+    out.push({ id, title, status, tasksDone, tasksTotal, unchecked, date, ageDays: ageInDays(date), capabilities, delivery });
   }
   return out;
 }

package/src/lib/task-card.js

@@ -1,9 +1,12 @@
 // @ts-check
 import path from "node:path";
-import { isFile, read } from "./fs-ops.js";
-import { parseChangeTitle, parseChecklist } from "./doc-model.js";
-import { listHeader, deltaCapabilities } from "./scan.js";
-import { sliceSpec } from "./context-slice.js";
+import { isDir, isFile, read, walk } from "./fs-ops.js";
+import { getSection, parseChangeTitle, parseChecklist } from "./doc-model.js";
+import { listHeader, deltaCapabilities, parseAdrScope } from "./scan.js";
+import { extractOps } from "./spec-ops.js";
+import { findWorkspace } from "./workspace.js";
+import { deliveryPath, resolveDeliveryId, sectionText } from "./delivery.js";
+import { sliceSpec, withoutComments } from "./context-slice.js";
 import { terms } from "./lexicon.js";
 
 // A TASK CARD (change 0222, ADR 0030): one task of a change, carrying what
@@ -64,6 +67,10 @@ export function taskCard(projectRoot, changeId, ordinal = null) {
   let box;
   if (ordinal === null) {
     box = boxes.find((b) => !b.checked && !b.placeholder);
+    // Only scaffold boxes left is not "every task is ticked" (third audit,
+    // change 0234): the planner was told to review and close a change
+    // whose tasks no one had written.
+    if (!box && boxes.some((b) => !b.checked && b.placeholder)) return { card: null, reason: "tasks.md holds only the scaffold's placeholder boxes — write the tasks as cards first" };
     if (!box) return { card: null, reason: "every task is ticked — the change is ready for review and close" };
   } else {
     box = boxes.find((b) => b.ordinal === ordinal);
@@ -73,14 +80,40 @@ export function taskCard(projectRoot, changeId, ordinal = null) {
   // CRLF on a Windows checkout: the Why is read paragraph by paragraph.
   const proposal = isFile(path.join(changeDir, "proposal.md")) ? read(path.join(changeDir, "proposal.md")).replace(/\r\n/g, "\n") : "";
   const fields = cardFields(box.details);
-  const query = terms([box.text, ...box.details].join(" "));
+  // What this change DOES to each spec (change 0231). The slice below is
+  // the spec as it stands — the current truth, before apply — so the
+  // requirement the executor is there to implement lived only in the delta,
+  // and reached the card only if the planner copied it into a line by hand.
+  const changes = [];
+  for (const cap of deltaCapabilities(changeDir)) {
+    const delta = path.join(changeDir, "specs", cap, "delta.md");
+    if (!isFile(delta)) continue;
+    for (const op of extractOps(read(delta))) {
+      if (op.verb === "append-requirement") changes.push({ capability: cap, line: `adds ${/^[aeiou]/.test(op.section) ? "an" : "a"} ${op.section} requirement: ${op.value}` });
+      else if (op.verb === "replace-requirement") changes.push({ capability: cap, line: `replaces ${op.section} requirement ${op.n} with: ${op.value}` });
+      else if (op.verb === "remove-requirement") changes.push({ capability: cap, line: `removes ${op.section} requirement ${op.n}` });
+      else if (op.verb === "append-criterion") changes.push({ capability: cap, line: `adds the criterion: ${op.value}` });
+      else if (op.verb === "replace-criterion") changes.push({ capability: cap, line: `replaces criterion ${op.n} with: ${op.value}` });
+      else if (op.verb === "remove-criterion") changes.push({ capability: cap, line: `removes criterion ${op.n}` });
+    }
+  }
+  // The task's words AND what the change writes into the spec (second
+  // audit, change 0233): a card for "lock the account on the third wrong
+  // password" cut the spec's only /login requirement, because the task never
+  // said "login" — the delta it implements did. Requirements only: a
+  // criterion's "[unverified] … — verified by `…`" matched any spec's
+  // placeholder on the boilerplate alone.
+  const query = terms([box.text, ...box.details, parseChangeTitle(proposal) ?? "", ...changes.filter((ch) => / requirement[^:]*: /.test(ch.line)).map((ch) => ch.line.slice(ch.line.indexOf(": ") + 2))].join(" "));
   const slices = [];
   for (const cap of deltaCapabilities(changeDir)) {
     const rel = `.doctrina/specs/${cap}/spec.md`;
     const specPath = path.join(projectRoot, rel);
     if (!isFile(specPath)) continue;
-    const slice = sliceSpec(read(specPath), query, rel);
-    if (slice) slices.push({ capability: cap, ...slice });
+    // Nothing in the spec matched the task: the whole spec, as `context`
+    // gives it (change 0231). Dropping it left a card with no spec at all.
+    const text = read(specPath);
+    const slice = sliceSpec(text, query, rel);
+    slices.push(slice ? { capability: cap, ...slice } : { capability: cap, text: withoutComments(text) ?? text, kept: null, total: null, whole: true });
   }
   return {
     card: {
@@ -96,7 +129,67 @@ export function taskCard(projectRoot, changeId, ordinal = null) {
       fields,
       why: firstParagraph(proposal, "Why"),
       slices,
+      changes,
+      story: deliveryStory(projectRoot, listHeader(proposal, "Delivery")),
+      decisions: bindingDecisions(projectRoot, deltaCapabilities(changeDir)),
     },
     reason: null,
   };
 }
+
+// The story the change serves, when it belongs to a delivery (change 0231):
+// its acceptance criteria are what the work is checked against, and they
+// live in the workspace, where an executor opened in the repository never
+// looks.
+const STORY_MAX_CHARS = 1500;
+function deliveryStory(projectRoot, deliveryId) {
+  if (!deliveryId) return null;
+  const found = findWorkspace(projectRoot);
+  if (!found) return null;
+  const id = resolveDeliveryId(found.dir, deliveryId.trim());
+  if (!id || !isFile(deliveryPath(found.dir, id))) return null;
+  const story = sectionText(read(deliveryPath(found.dir, id)), "Story");
+  if (!story) return null;
+  return story.length > STORY_MAX_CHARS ? `${story.slice(0, STORY_MAX_CHARS).replace(/\s+\S*$/, "")} …` : story;
+}
+
+// The accepted decisions that bind the capabilities the change touches:
+// those whose Scope names one, and the unscoped ones that cite one. A card
+// the executor follows without them is how an implementation re-decides
+// what an ADR settled.
+function bindingDecisions(projectRoot, capabilities) {
+  const dir = path.join(projectRoot, ".doctrina", "decisions");
+  if (!isDir(dir) || capabilities.length === 0) return { list: [], more: 0 };
+  /** @type {Array<{ id: string, title: string, decision: string, rank: number }>} */
+  const found = [];
+  for (const f of walk(dir).sort()) {
+    const m = path.basename(f).match(/^(\d{4})-.*\.md$/);
+    if (!m) continue;
+    const text = read(f).replace(/\r\n/g, "\n");
+    if ((listHeader(text, "Status") ?? "").trim().toLowerCase() !== "accepted") continue;
+    const scope = parseAdrScope(text);
+    const cites = (/** @type {string} */ cap) => new RegExp(`(^|[^a-z0-9-])${cap.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}([^a-z0-9-]|$)`, "im").test(text);
+    // An unscoped ADR is GLOBAL — it binds every capability, as `decision
+    // scope` documents and the context pack loads it (sixth audit, change
+    // 0237). The card bound one only when its text named the capability, so
+    // a repository-wide rule ("error codes are MAIUSCULAS_SNAKE") never
+    // reached the executor, who reads nothing else. Scoped first, then the
+    // global ones that name the capability, then the rest.
+    const rank = scope.length > 0 ? (capabilities.some((cap) => scope.includes(cap)) ? 0 : -1) : (capabilities.some(cites) ? 1 : 2);
+    if (rank < 0) continue;
+    const decision = (getSection(text, "Decision") ?? "").replace(/<!--[\s\S]*?-->/g, "").replace(/\s+/g, " ").trim();
+    found.push({
+      id: m[1],
+      title: text.match(/^#\s+ADR\s+\d{4}\s*[—-]\s*(.+)$/m)?.[1]?.trim() ?? path.basename(f),
+      decision: decision.length > DECISION_EXCERPT ? `${decision.slice(0, DECISION_EXCERPT).replace(/\s+\S*$/, "")} …` : decision,
+      rank,
+    });
+  }
+  const sorted = found.sort((a, b) => a.rank - b.rank || a.id.localeCompare(b.id));
+  return { list: sorted.slice(0, DECISIONS_ON_CARD), more: Math.max(0, sorted.length - DECISIONS_ON_CARD) };
+}
+
+// How many binding decisions a card names, and how much of each it quotes.
+const DECISIONS_ON_CARD = 8;
+const DECISION_EXCERPT = 240;
+

package/src/lib/views.js

@@ -187,7 +187,7 @@ export function prime(s) {
       // one forgotten for three weeks used to read identically.
       const age = ch.ageDays !== null && ch.ageDays !== undefined && ch.ageDays >= STALE_CHANGE_DAYS
         ? ` · open ${ch.ageDays}d` : "";
-      out.push(`  ${c.cyan(ch.id)}  ${ch.title ?? ""}${c.gray(` (${ch.status}${tasks}${age})`)}`);
+      out.push(`  ${c.cyan(ch.id)}  ${ch.title ?? ""}${c.gray(` (${ch.status}${tasks}${age}${ch.delivery ? ` · delivery ${ch.delivery}` : ""})`)}`);
     }
   }
 
@@ -236,7 +236,7 @@ export function prime(s) {
  * Worded as facts, not orders: an agent's prompt-injection defences treat
  * imperatives from a hook with suspicion, and they should.
  *
- * @param {Array<{id: string, title: string|null, status: string}>} open
+ * @param {Array<{id: string, title: string|null, status: string, delivery?: string|null}>} open
  * @param {Array<{id: string, date: string, path: string}>} [recent]
  */
 export function pulse(open, recent = []) {
@@ -247,7 +247,7 @@ export function pulse(open, recent = []) {
     return ["Doctrina: no change is open in this project. A request that changes behaviour is opened as a change " +
       "before code is edited — `doctrina work \"<request>\"` (it classifies the lane itself); a question or a read needs none." + last];
   }
-  const named = open.slice(0, 3).map((ch) => `${ch.id}${ch.title ? ` — "${ch.title}"` : ""} (${ch.status})`).join("; ");
+  const named = open.slice(0, 3).map((ch) => `${ch.id}${ch.title ? ` — "${ch.title}"` : ""} (${ch.status}${ch.delivery ? `, part of delivery ${ch.delivery}` : ""})`).join("; ");
   const more = open.length > 3 ? ` and ${open.length - 3} more` : "";
   return [`Doctrina: open change${open.length === 1 ? "" : "s"}: ${named}${more}. Work that belongs to ${open.length === 1 ? "it" : "one of them"} ` +
     "is named by its id in the first sentence to the human and finishes with `doctrina close <id>`; " +

package/src/lib/work-model.js

@@ -16,7 +16,13 @@ import { globToRegExp } from "./runtime.js";
 // file scores its capability when the file sits under a path segment named for
 // it, or when the spec cites the file as evidence. A deterministic overlap
 // hint for the agent — never a decision (ADR 0005).
-export function rankCapabilitiesByDiff(projectRoot, files, { limit = 3 } = {}) {
+//
+// `pending` (change 0228) is, per capability, the spec as the change under
+// review will leave it: the criterion a change adds cites its new test, a
+// `set-header Source:` claims new paths, and `review` runs before `apply`
+// merges either — so without it the files the change itself claims were
+// reported as belonging to no capability.
+export function rankCapabilitiesByDiff(projectRoot, files, { limit = 3, pending = new Map() } = {}) {
   const specsDir = path.join(projectRoot, ".doctrina", "specs");
   if (!files || files.length === 0 || !isDir(specsDir)) return [];
   const norm = files.map((f) => f.replace(/\\/g, "/"));
@@ -25,7 +31,7 @@ export function rankCapabilitiesByDiff(projectRoot, files, { limit = 3 } = {}) {
   for (const cap of readdirSync(specsDir).sort()) {
     const specPath = path.join(specsDir, cap, "spec.md");
     if (!isFile(specPath)) continue;
-    const text = read(specPath);
+    const text = pending.get(cap) ?? read(specPath);
     specs.push({ cap, text, declared: parseSourceGlobs(text).map((g) => globToRegExp(g)) });
   }