doctrina-cli 0.18.0 → 0.20.0

package/src/lib/delivery.js

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

package/src/lib/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/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,43 @@ 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));
+    out.push({ id, title, status, tasksDone, tasksTotal, unchecked, date, ageDays: ageInDays(date), capabilities });
+  }
+  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,102 @@
+// @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 { 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);
+    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);
+  const query = terms([box.text, ...box.details].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 });
+  }
+  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,
+    },
+    reason: null,
+  };
+}

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
@@ -191,6 +191,16 @@ export function prime(s) {
     }
   }
 
+  // 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})`)}`);
+    }
+  }
+
   out.push("");
   out.push(c.bold("Next"));
   if (s.actions.length === 0) {
@@ -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}>} 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})`).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

@@ -120,3 +120,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);
+}