doctrina-cli 0.18.0 → 0.21.0

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/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", "consolidate"];
+export const PLAYBOOKS = ["work", "chore", "bootstrap", "consolidate", "absorb"];

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/skill-export.js

@@ -0,0 +1,95 @@
+// @ts-check
+import path from "node:path";
+import { readdirSync } from "node:fs";
+import { isDir, isFile, pruneEmptyDirs, read, remove, write, walk } from "./fs-ops.js";
+import { parseFrontmatter } from "./doc-model.js";
+import { describeAdapter, ADAPTER_STATES } from "./adapters.js";
+
+// The project's skills, where the agent looks for skills (change 0212).
+//
+// A field review of an agent in Cursor: the editor's skill catalogue lists
+// `~/.cursor/skills` and plugins, never `.doctrina/skills/`, so a skill that
+// matched the task fired only when the request named its file. AGENTS.md
+// said "skills are on demand"; nothing said the editor would never offer
+// them. The agents now share a format — a folder per skill holding a
+// SKILL.md with `name` and `description` — and discover it on their own:
+// `.agents/skills/` (Cursor, Codex) and `.claude/skills/` (Claude Code;
+// Cursor reads it too). `.doctrina/skills/` stays the one source; the
+// exports are generated from it, marked as generated, and pruned with it.
+
+export const EXPORT_MARK = "<!-- doctrina:skill-export";
+const DESCRIPTION_MAX = 1024;
+
+/** Where this project's skills are exported, as project-relative roots. */
+export function exportRoots(projectRoot) {
+  const roots = [".agents/skills"];
+  if (describeAdapter(projectRoot, "claude").state === ADAPTER_STATES.INSTALLED) roots.push(".claude/skills");
+  return roots;
+}
+
+/** The SKILL.md a Doctrina skill becomes. */
+export function renderSkillExport(name, text) {
+  const body = text.replace(/\r\n/g, "\n");
+  const description = parseFrontmatter(body, "description") ?? name;
+  const when = parseFrontmatter(body, "when");
+  // The agent decides from the description alone, so the trigger goes in it.
+  const full = (when ? `${description} Use when: ${when}` : description).replace(/\s+/g, " ").trim();
+  const clipped = full.length > DESCRIPTION_MAX ? `${full.slice(0, DESCRIPTION_MAX - 1)}…` : full;
+  const rest = body.replace(/^---\n[\s\S]*?\n---\n/, "").replace(/^\n+/, "");
+  return [
+    "---",
+    `name: ${name}`,
+    `description: ${JSON.stringify(clipped)}`,
+    "---",
+    `${EXPORT_MARK} — generated from .doctrina/skills/${name}.md by \`doctrina index rebuild\`; edit that file, not this one. -->`,
+    "",
+    rest,
+  ].join("\n").replace(/\n*$/, "\n");
+}
+
+/**
+ * What the export would change: files to write (missing or different) and
+ * generated skill folders to remove (their source is gone). Folders not
+ * carrying the generated mark are someone else's and never touched.
+ *
+ * @param {string} projectRoot
+ * @returns {{ writes: Array<{ rel: string, body: string }>, removes: string[] }}
+ */
+export function planSkillExport(projectRoot) {
+  const skillsDir = path.join(projectRoot, ".doctrina", "skills");
+  const skills = isDir(skillsDir)
+    ? walk(skillsDir).filter((f) => f.endsWith(".md") && path.dirname(f) === skillsDir)
+    : [];
+  const wanted = new Map(skills.map((f) => [path.basename(f, ".md"), read(f)]));
+  const writes = [];
+  const removes = [];
+  if (wanted.size === 0 && !exportRoots(projectRoot).some((r) => isDir(path.join(projectRoot, r)))) {
+    return { writes, removes };
+  }
+  for (const root of exportRoots(projectRoot)) {
+    for (const [name, text] of wanted) {
+      const rel = `${root}/${name}/SKILL.md`;
+      const body = renderSkillExport(name, text);
+      const abs = path.join(projectRoot, rel);
+      if (!isFile(abs) || read(abs).replace(/\r\n/g, "\n") !== body) writes.push({ rel, body });
+    }
+    const rootAbs = path.join(projectRoot, root);
+    if (!isDir(rootAbs)) continue;
+    for (const entry of readdirSync(rootAbs)) {
+      const skillFile = path.join(rootAbs, entry, "SKILL.md");
+      if (wanted.has(entry) || !isFile(skillFile)) continue;
+      if (read(skillFile).includes(EXPORT_MARK)) removes.push(`${root}/${entry}/SKILL.md`);
+    }
+  }
+  return { writes, removes };
+}
+
+/** Apply a plan; returns it. */
+export function applySkillExport(projectRoot, plan = planSkillExport(projectRoot)) {
+  for (const w of plan.writes) write(path.join(projectRoot, w.rel), w.body, { force: true });
+  for (const r of plan.removes) {
+    remove(path.join(projectRoot, r)); // the generated file only
+    pruneEmptyDirs(path.dirname(path.join(projectRoot, r)), projectRoot);
+  }
+  return plan;
+}

package/src/lib/snapshot.js

@@ -4,7 +4,7 @@ import { readdirSync } from "node:fs";
 import { isDir, isFile, read, walk } from "./fs-ops.js";
 import { projectName } from "./project.js";
 import * as idx from "./index-json.js";
-import { deriveIndex, indexesMatch, specHeader, listHeader } from "./scan.js";
+import { deriveIndex, indexesMatch, specHeader, listHeader, deltaCapabilities } from "./scan.js";
 import { cliVersion } from "./version.js";
 import { summarize as coverageSummary } from "./coverage-model.js";
 import { summarize as traceSummary } from "./trace-model.js";
@@ -72,6 +72,7 @@ export function collectSnapshot(projectRoot, { actions = true } = {}) {
     decisions: countDecisions(projectRoot),
     skills: countSkills(projectRoot),
     openChanges: openChanges(projectRoot),
+    recentlyClosed: recentlyClosed(projectRoot),
     adrs: acceptedDecisions(projectRoot),
     nonGoals: productSection(projectRoot, "Non-goals"),
     hasNonGoalsSection: hasProductSection(projectRoot, "Non-goals"),
@@ -151,7 +152,47 @@ export function openChanges(projectRoot) {
     const tasksDone = progress.done;
     const unchecked = progress.open.map((t) => t || "(unwritten task — the scaffold's placeholder)");
     const date = proposal ? (listHeader(proposal, "Date") ?? null) : null;
-    out.push({ id, title, status, tasksDone, tasksTotal, unchecked, date, ageDays: ageInDays(date) });
+    // 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));
+    // 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;
+}
+
+// How far back `prime` and the pulse look for closed changes (change 0214).
+export const RECENT_CLOSE_DAYS = 7;
+
+/**
+ * Changes archived in the last RECENT_CLOSE_DAYS, newest first: what the
+ * human may ask for again without knowing it is done. A field review: the
+ * close moved the work to `changes/archive/`, out of every default read, and
+ * the next request was to "create the doctrina work" for it.
+ *
+ * @param {string} projectRoot
+ * @param {{ limit?: number }} [opts]
+ * @returns {Array<{ id: string, title: string|null, date: string, path: string, ageDays: number|null }>}
+ */
+export function recentlyClosed(projectRoot, { limit = 3 } = {}) {
+  const archiveDir = path.join(projectRoot, ".doctrina", "changes", "archive");
+  if (!isDir(archiveDir)) return [];
+  const out = [];
+  for (const name of readdirSync(archiveDir).sort().reverse()) {
+    const m = name.match(/^(\d{4}-\d{2}-\d{2})-(.+)$/);
+    if (!m || !isDir(path.join(archiveDir, name))) continue;
+    const ageDays = ageInDays(m[1]);
+    if (ageDays === null || ageDays > RECENT_CLOSE_DAYS) break;
+    const proposal = path.join(archiveDir, name, "proposal.md");
+    out.push({
+      id: m[2], date: m[1], ageDays,
+      title: isFile(proposal) ? parseChangeTitle(read(proposal)) : null,
+      path: `.doctrina/changes/archive/${name}/`,
+    });
+    if (out.length >= limit) break;
   }
   return out;
 }

package/src/lib/task-card.js

@@ -0,0 +1,195 @@
+// @ts-check
+import path from "node:path";
+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
+// an executor needs to do it ALONE — the task, the lines indented under it
+// (files, requirement, verify command), why the change exists, and the spec
+// cut to the task. A subagent does not see the planner's conversation, so
+// the card is the whole of its context; a card that needs the conversation
+// is a card the planner has not finished writing.
+
+/**
+ * The tasks.md boxes, each with the indented lines under it.
+ * Ordinals are the same ones `change tick` uses (tasks.md comes first).
+ */
+export function taskBoxes(tasksText) {
+  const lines = String(tasksText).replace(/\r\n/g, "\n").split("\n");
+  return parseChecklist(tasksText).map((box, i) => {
+    const indent = (lines[box.line].match(/^\s*/)?.[0] ?? "").length;
+    const details = [];
+    for (let j = box.line + 1; j < lines.length; j++) {
+      const l = lines[j];
+      if (l.trim() === "") {
+        if (details.length) break;
+        continue;
+      }
+      if ((l.match(/^\s*/)?.[0] ?? "").length <= indent) break;
+      details.push(l.trim().replace(/^[-*]\s+/, ""));
+    }
+    return { ordinal: i + 1, text: box.text, checked: box.checked, placeholder: box.placeholder, details };
+  });
+}
+
+/** The `Field: value` lines of a card's details, keyed by lowercased field. */
+export function cardFields(details) {
+  const out = {};
+  for (const d of details) {
+    const m = d.match(/^([A-Za-z][A-Za-z ]{0,20}):\s*(.+)$/);
+    if (m) out[m[1].trim().toLowerCase()] = m[2].trim();
+  }
+  return out;
+}
+
+function firstParagraph(text, heading) {
+  const m = String(text).match(new RegExp(`^## ${heading}\\s*\\n+([\\s\\S]*?)(?:\\n\\s*\\n|\\n## |$)`, "m"));
+  return m ? m[1].replace(/<!--[\s\S]*?-->/g, "").trim() : "";
+}
+
+/**
+ * The card for task `ordinal` of a change — or, with no ordinal, the first
+ * open one. Null `card` with a reason when there is none to give.
+ * @returns {{ card: null, reason: string } | { card: object, reason: null }}
+ */
+export function taskCard(projectRoot, changeId, ordinal = null) {
+  const changeDir = path.join(projectRoot, ".doctrina", "changes", changeId);
+  const tasksPath = path.join(changeDir, "tasks.md");
+  if (!isFile(tasksPath)) return { card: null, reason: "the change has no tasks.md" };
+  const boxes = taskBoxes(read(tasksPath));
+  if (boxes.length === 0) return { card: null, reason: "tasks.md has no task box" };
+  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);
+    if (!box) return { card: null, reason: `no task ${ordinal} (tasks.md has ${boxes.length})` };
+  }
+  if (box.placeholder) return { card: null, reason: `task ${box.ordinal} is a scaffold placeholder — write the task first` };
+  // 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);
+  // 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;
+    // 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: {
+      change: changeId,
+      title: parseChangeTitle(proposal) ?? changeId,
+      delivery: listHeader(proposal, "Delivery") ?? null,
+      ordinal: box.ordinal,
+      total: boxes.length,
+      done: boxes.filter((b) => b.checked).length,
+      checked: box.checked,
+      text: box.text,
+      details: box.details,
+      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

@@ -2,7 +2,7 @@
 import { c } from "./colors.js";
 import { today } from "./dates.js";
 import { churnByCapability } from "./ledger.js";
-import { STALE_CHANGE_DAYS } from "./snapshot.js";
+import { STALE_CHANGE_DAYS, RECENT_CLOSE_DAYS } from "./snapshot.js";
 
 // Executed proof and signed proof are different claims (change 0039). One
 // phrasing, used by every view, so none of them can quietly add the two
@@ -187,7 +187,17 @@ 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}` : ""})`)}`);
+    }
+  }
+
+  // What was just finished, where it went (change 0214): archived work is out
+  // of every default read, so without this line it looks undone.
+  if ((s.recentlyClosed ?? []).length > 0) {
+    out.push("");
+    out.push(c.bold("Recently closed") + c.gray(` (last ${RECENT_CLOSE_DAYS} days)`));
+    for (const ch of s.recentlyClosed) {
+      out.push(`  ${c.cyan(ch.id)}  ${ch.title ?? ""}${c.gray(` (${ch.date} → ${ch.path})`)}`);
     }
   }
 
@@ -201,10 +211,49 @@ export function prime(s) {
   }
 
   out.push("");
-  out.push(c.gray("Read deeper: `doctrina context [<cap>] --concat` · `doctrina why <cap>` · `doctrina show <ref>`"));
+  // The read for the work in hand, as a command to copy (change 0217): a
+  // field review found `prime` taken as enough and `context` skipped, and a
+  // generic "read deeper" is the line a reader skips first.
+  const focus = s.openChanges.find((ch) => (ch.capabilities ?? []).length > 0);
+  if (focus) {
+    const query = String(focus.title ?? focus.id).replace(/["`]/g, "").replace(/\s+/g, " ").trim().slice(0, 80);
+    out.push(c.bold("Read for ") + c.cyan(focus.id) + ": " +
+      c.cyan(`doctrina context ${focus.capabilities[0]} --for "${query}" --concat`) +
+      (focus.capabilities.length > 1 ? c.gray(` (also: ${focus.capabilities.slice(1).join(", ")})`) : ""));
+  }
+  out.push(c.gray("Read deeper: `doctrina context <cap> --for \"<task>\" --concat` · `doctrina why <cap>` · `doctrina show <ref>`"));
   return out;
 }
 
+// ------------------------------------------------------------------- pulse
+
+/**
+ * The one fact an agent needs with EVERY prompt (change 0211): whether a
+ * change is open, which, and that a request changing behaviour opens one.
+ * A field review: "without the framework's name in the request, the request
+ * for code wins" — the cycle sat in AGENTS.md, read once, against the
+ * request read now. A UserPromptSubmit hook prints this beside each prompt.
+ * 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, delivery?: string|null}>} open
+ * @param {Array<{id: string, date: string, path: string}>} [recent]
+ */
+export function pulse(open, recent = []) {
+  if (open.length === 0) {
+    // The last closed change, so "do the work for X" is answered "already
+    // done, archived at …" instead of done twice (change 0214).
+    const last = recent[0] ? ` Last closed: ${recent[0].id} (${recent[0].date}, ${recent[0].path}).` : "";
+    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}${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>`; " +
+    "a different request is its own change (`doctrina work \"<request>\"`)."];
+}
+
 // ----------------------------------------------------------------- handoff
 
 export function handoff(s) {

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)) });
   }
 
@@ -120,3 +126,61 @@ export function rankCapabilities(projectRoot, prompt) {
   // 0, the same convention `triage` uses for a lane nothing scored against.
   return sorted.slice(0, 3).map((e, i) => ({ ...e, margin: e.score - (sorted[i + 1]?.score ?? 0) }));
 }
+
+// How far back `work` looks for an archived change the prompt may repeat,
+// and how much of one side the other must cover to count (change 0215).
+export const SIMILAR_CHANGE_DAYS = 14;
+// Three shared terms: two matched "mudar uma coisa" with "mudar outra coisa".
+const SIMILAR_MIN_SHARED = 3;
+const SIMILAR_MIN_COVER = 0.6;
+
+/**
+ * Open changes, and changes archived in the last SIMILAR_CHANGE_DAYS, whose
+ * title and Why the prompt mostly repeats. A field review: two changes were
+ * done and archived, and the next request — "create the doctrina work for
+ * payment and admin" — would have opened the same work twice. Deterministic
+ * term overlap (ADR 0005), measured from both sides: a short prompt that
+ * names most of a change, or a change named mostly by a long prompt.
+ *
+ * @param {string} projectRoot
+ * @param {string} prompt
+ * @returns {Array<{ id: string, title: string, where: "open"|"archived", path: string, shared: string[] }>}
+ */
+export function similarChanges(projectRoot, prompt) {
+  const asked = terms(prompt);
+  if (asked.length === 0) return [];
+  const changesDir = path.join(projectRoot, ".doctrina", "changes");
+  if (!isDir(changesDir)) return [];
+  const candidates = [];
+  for (const name of readdirSync(changesDir).sort()) {
+    if (name === "archive" || name.startsWith(".")) continue;
+    const proposal = path.join(changesDir, name, "proposal.md");
+    if (isFile(proposal)) candidates.push({ id: name, where: /** @type {"open"|"archived"} */ ("open"), rel: `.doctrina/changes/${name}/`, text: read(proposal) });
+  }
+  const archiveDir = path.join(changesDir, "archive");
+  if (isDir(archiveDir)) {
+    const cutoff = Date.now() - SIMILAR_CHANGE_DAYS * 86400000;
+    for (const name of readdirSync(archiveDir)) {
+      const m = name.match(/^(\d{4}-\d{2}-\d{2})-(.+)$/);
+      if (!m || Date.parse(`${m[1]}T00:00:00Z`) < cutoff) continue;
+      const proposal = path.join(archiveDir, name, "proposal.md");
+      if (isFile(proposal)) candidates.push({ id: m[2], where: /** @type {"open"|"archived"} */ ("archived"), rel: `.doctrina/changes/archive/${name}/`, text: read(proposal) });
+    }
+  }
+  const out = [];
+  for (const cand of candidates) {
+    const title = (cand.text.match(/^#\s+Change\s+\S+\s+—\s+(.+)$/m)?.[1] ?? cand.id).trim();
+    const why = cand.text.match(/##\s*Why\s*\r?\n+([^\r\n]+)/)?.[1] ?? "";
+    const theirs = terms(`${cand.id.replace(/^\d+-/, "").replace(/-/g, " ")} ${title} ${why}`);
+    const shared = asked.filter((t) => theirs.includes(t));
+    if (shared.length < SIMILAR_MIN_SHARED) continue;
+    // Each side's cover counts only the terms on that side: a word the Why
+    // happens to share must not stand in for the title (a prompt about "the
+    // work" matched "trabalho aparece para o humano" through its Why).
+    const titleTerms = terms(title);
+    const titleShared = asked.filter((t) => titleTerms.includes(t));
+    const cover = Math.max(shared.length / asked.length, titleTerms.length > 0 ? titleShared.length / titleTerms.length : 0);
+    if (cover >= SIMILAR_MIN_COVER) out.push({ id: cand.id, title, where: cand.where, path: cand.rel, shared, cover });
+  }
+  return out.sort((a, b) => b.cover - a.cover).map(({ cover: _c, ...rest }) => rest);
+}