doctrina-cli 0.20.0 → 0.22.0

package/src/lib/workspace-tools.js

@@ -25,10 +25,11 @@ export const TOOL_PRESETS = {
 };
 
 /** A tool entry from flags and an optional preset. Throws a message on bad input. */
-export function toolEntry(name, opts, existing = null) {
+export function toolEntry(name, opts, existing = /** @type {any} */ (null)) {
   if (!TOOL_NAME.test(name)) throw new Error(`tool name "${name}" must match ${TOOL_NAME}`);
   const preset = TOOL_PRESETS[name] ?? {};
   const base = existing ?? { name, server: preset.server ?? null, access: "read", for: preset.for ?? [], purpose: preset.purpose ?? "" };
+  /** @type {any} */
   const entry = { ...base };
   if (opts.server) entry.server = opts.server;
   if (opts.access) {
@@ -42,10 +43,40 @@ export function toolEntry(name, opts, existing = null) {
     entry.for = roles;
   }
   if (opts.purpose) entry.purpose = opts.purpose;
+  // The calls this tool may make, by name (change 0244). `none` takes the
+  // list away; a pattern is a tool name, `*` standing for any run of it.
+  if (opts.only !== undefined && opts.only !== null) {
+    const patterns = String(opts.only).split(",").map((s) => s.trim()).filter(Boolean);
+    if (patterns.length === 0 || (patterns.length === 1 && patterns[0].toLowerCase() === "none")) {
+      delete entry.only;
+    } else {
+      const bad = patterns.filter((p) => !CALL_PATTERN.test(p));
+      if (bad.length) throw new Error(`--only takes MCP tool names, \`*\` for any run of characters (got ${bad.map((b) => `"${b}"`).join(", ")})`);
+      entry.only = patterns;
+    }
+  }
   if (!entry.server) throw new Error(`tool "${name}" has no preset — pass --server <the MCP server's name in your agent's config>`);
   return entry;
 }
 
+// A LIST OF THE CALLS A TOOL MAY MAKE (change 0244).
+//
+// "Does this call write?" is answered from the call's name and input, which
+// is a guess: a verb the list below has never seen reads as a read, and the
+// call goes through. A tool that declares `only` turns the question around —
+// the calls named pass on to that judgment, and every other call through
+// its server is denied, whatever its name suggests.
+const CALL_PATTERN = /^[A-Za-z0-9_.*:-]+$/;
+
+/** Does `tool` match one of the patterns (case-insensitive, `*` = any run)? */
+export function matchesCall(patterns, tool) {
+  const name = String(tool).toLowerCase();
+  return patterns.some((p) => {
+    const re = new RegExp("^" + String(p).toLowerCase().split("*").map((part) => part.replace(/[.+?^${}()|[\]\\]/g, "\\$&")).join(".*") + "$");
+    return re.test(name);
+  });
+}
+
 // Verbs that change state in the system a tool talks to. Matched on the
 // tool's own name, word by word.
 const WRITE_VERBS = new Set([
@@ -53,35 +84,82 @@ const WRITE_VERBS = new Set([
   "transition", "assign", "comment", "publish", "upload", "deploy", "trigger", "set", "move",
   "merge", "close", "archive", "insert", "drop", "alter", "truncate", "mutate", "rollback", "restart",
   "approve", "reject", "resolve", "mute", "unmute", "schedule", "cancel", "import",
+  // The fourth audit (change 0235): verbs real MCP servers use that passed as reads.
+  "upsert", "link", "unlink", "reopen", "rename", "replace", "save", "submit", "sync", "release",
+  "rotate", "grant", "revoke", "reset", "clear", "purge", "destroy", "terminate", "kill", "pause",
+  "enable", "disable", "snooze", "escalate", "notify", "reply", "react", "vote", "fork", "push",
+  "commit", "lock", "unlock", "ack", "acknowledge", "install", "uninstall", "provision", "scale",
+  "rerun", "retry", "dispatch", "copy", "duplicate", "invite", "share", "subscribe", "unsubscribe",
+  "block", "unblock", "revert", "restore", "empty",
 ]);
-const MUTATING_SQL = /\b(insert|update|delete|merge|drop|alter|create|truncate|grant|revoke|replace)\b/i;
+// Statements that change the database, a procedure that may, and a SELECT
+// that writes a table (`SELECT … INTO`). A keyword in a comment counts: the
+// guard errs on the side of asking.
+const MUTATING_SQL = /\b(insert|update|delete|merge|drop|alter|create|truncate|grant|revoke|replace|call|exec|execute|copy|do|vacuum|reindex|cluster|refresh|upsert|load|unload|optimize|restore|rename|comment|lock|into)\b/i;
+const SQL_START = /^\s*(\(|\/\*|--)?\s*(select|with|insert|update|delete|merge|drop|alter|create|truncate|show|describe|explain|call|exec|execute|copy|grant|revoke|vacuum|refresh|optimize|do)\b/i;
+// An argument that names the operation a generic tool performs.
+const ACTION_KEYS = new Set(["action", "operation", "op", "method", "verb", "mutation"]);
 
 /**
  * Whether a tool call would change state. A SQL statement in the input
  * decides for itself; otherwise the tool's name does.
  */
 export function isWriteCall(toolName, toolInput) {
-  const sql = sqlIn(toolInput);
+  const input = parsed(toolInput);
+  // An argument that says what a generic tool does: `{ action: "delete" }`,
+  // `{ method: "POST" }`, a GraphQL `mutation` (change 0235).
+  if (actionWrites(input)) return true;
+  const sql = sqlIn(input);
   if (sql !== null) return MUTATING_SQL.test(sql.replace(/'[^']*'/g, "''"));
   // camelCase and snake_case alike: `transitionJiraIssue`, `transition_issue`.
-  const words = String(toolName).replace(/([a-z0-9])([A-Z])/g, "$1_$2").toLowerCase().split(/[^a-z]+/).filter(Boolean);
-  return words.some((w) => WRITE_VERBS.has(w));
+  const words = nameWords(toolName);
+  if (words.some((w) => WRITE_VERBS.has(w))) return true;
+  // A name with no separator at all — `createissue`, `CREATEISSUE`,
+  // `getandremove` — hides its verbs inside one word (change 0235).
+  if (words.length === 1 && words[0].length > 6) {
+    return [...WRITE_VERBS].some((v) => v.length >= 5 && words[0].includes(v));
+  }
+  return false;
 }
 
-function sqlIn(input) {
-  let obj = input;
-  if (typeof obj === "string") {
-    try {
-      obj = JSON.parse(obj);
-    } catch {
-      return /^\s*(select|with|insert|update|delete|merge|drop|alter|create|truncate|show|describe)\b/i.test(obj) ? obj : null;
-    }
+function nameWords(name) {
+  return String(name).replace(/([a-z0-9])([A-Z])/g, "$1_$2").toLowerCase().split(/[^a-z]+/).filter(Boolean);
+}
+
+function parsed(input) {
+  if (typeof input !== "string") return input;
+  try {
+    return JSON.parse(input);
+  } catch {
+    return input;
   }
-  if (!obj || typeof obj !== "object") return null;
-  for (const key of ["sql", "query", "statement", "sql_query"]) {
-    if (typeof obj[key] === "string") return obj[key];
+}
+
+/** Every string inside an input, to a bounded depth. */
+function stringsIn(value, depth = 0, out = /** @type {Array<{ key: string, value: string }>} */ ([]), key = "") {
+  if (depth > 5 || out.length > 200) return out;
+  if (typeof value === "string") out.push({ key, value });
+  else if (Array.isArray(value)) for (const v of value) stringsIn(v, depth + 1, out, key);
+  else if (value && typeof value === "object") for (const [k, v] of Object.entries(value)) stringsIn(v, depth + 1, out, k);
+  return out;
+}
+
+function actionWrites(input) {
+  for (const { key, value } of stringsIn(input)) {
+    if (/^\s*mutation\b/i.test(value)) return true;
+    if (!ACTION_KEYS.has(key.toLowerCase())) continue;
+    const words = nameWords(value);
+    if (words.some((w) => WRITE_VERBS.has(w) || ["post", "put", "patch", "delete"].includes(w))) return true;
   }
-  return null;
+  return false;
+}
+
+// SQL wherever the input carries it — `sql`, `query`, `q`, a `statements`
+// list, a nested `{ input: { sql } }` (change 0235): only four top-level
+// keys were read, and a DELETE under any other passed as no SQL at all.
+function sqlIn(input) {
+  const found = stringsIn(input).map((s) => s.value).filter((s) => SQL_START.test(s));
+  return found.length ? found.join(";\n") : null;
 }
 
 /**
@@ -93,6 +171,15 @@ function sqlIn(input) {
 export function guardDecision(tools, server, tool, input) {
   const declared = tools.filter((t) => t.server === server && t.enabled !== false);
   if (declared.length === 0) return { decision: "none", reason: `server "${server}" is not declared in the workspace` };
+  // A list on any tool of this server is the server's list: a call outside
+  // it is denied before its name is read for a verb.
+  const listed = declared.filter((t) => Array.isArray(t.only) && t.only.length > 0);
+  if (listed.length > 0 && !listed.some((t) => matchesCall(t.only, tool))) {
+    return {
+      decision: "deny",
+      reason: `${tool} is not among the calls the workspace allows through "${server}" (${listed.map((t) => `${t.name}: ${t.only.join(", ")}`).join("; ")}). Ask the human; to allow it: doctrina workspace tool ${listed[0].name} --only "${[...listed[0].only, tool].join(",")}"`,
+    };
+  }
   const write = isWriteCall(tool, input);
   if (!write) return { decision: "allow", reason: `${tool} reads` };
   const writable = declared.some((t) => t.access === "write");

package/src/lib/workspace-view.js

@@ -0,0 +1,391 @@
+// @ts-check
+import path from "node:path";
+import os from "node:os";
+import { existsSync, realpathSync } from "node:fs";
+import { git, GIT_STATE } from "./git.js";
+import { isDir, isFile, read } from "./fs-ops.js";
+import { listHeader } from "./scan.js";
+import { absorbCommand, findWorkspace, pointerPath, projectAt, projectState, readWorkspace, linkPlan, shadowDirOf } from "./workspace.js";
+import { deliveryBlockers, deliveryChanges, listDeliveries, rankProjects, readDelivery, releaseBoxes } from "./delivery.js";
+import { cdThen, qarg, qpath } from "./shell.js";
+
+// THE WORKSPACE ROOT IS WHERE THE PLANNER WORKS (change 0230).
+//
+// `prime` knew it: at a workspace root it printed the orchestrator's primer.
+// Every other orientation command answered as if the directory were an empty
+// project — `next` told the planner to run `doctrina init` there, which
+// would have created a project inside the workspace, and `handoff`, `status`,
+// `validate` and `context` refused with "not a Doctrina project". The planner
+// lost exactly the commands AGENTS.md says to reach for before compaction and
+// when unsure what comes next. This module decides what each of them says at
+// the root; the commands render it (ADR 0025).
+
+/**
+ * The workspace this directory is the ROOT of — reached by the directory or
+ * $DOCTRINA_WORKSPACE, with no `.doctrina/` of its own. A project inside a
+ * workspace keeps its own answers; only the pointer route is never a root.
+ * @returns {string | null}
+ */
+export function workspaceRootAt(cwd) {
+  if (existsSync(path.join(cwd, ".doctrina"))) return null;
+  const found = findWorkspace(cwd);
+  return found && found.via !== "pointer" ? found.dir : null;
+}
+
+/**
+ * Where the workspace stands: every project with its state, every open
+ * delivery with its changes and what keeps it open.
+ */
+export function workspaceSnapshot(wsDir) {
+  const ws = readWorkspace(wsDir);
+  const projects = ws.projects.map((p) => ({ project: p, ...projectState(wsDir, p) }));
+  const deliveries = listDeliveries(wsDir).map((d) => readDelivery(wsDir, d.id));
+  const open = deliveries.filter((d) => d.status !== "closed").map((d) => ({
+    delivery: d,
+    rows: deliveryChanges(wsDir, ws, d),
+    blockers: deliveryBlockers(wsDir, ws, d),
+    release: releaseBoxes(d.text),
+  }));
+  return { ws, wsDir, projects, deliveries, open };
+}
+
+/**
+ * The next actions at the workspace root, in the order they unblock work:
+ * a missing repository first, then a project that cannot be routed to, then
+ * each open delivery's next step, then — with nothing open — a new delivery.
+ * @returns {Array<{ text: string, command: string }>}
+ */
+export function workspaceActions(snap) {
+  const out = [];
+  for (const p of snap.projects.filter((x) => x.state === "missing")) {
+    out.push({ text: `${p.project.name}'s repository is not at its path — re-link it`, command: `doctrina workspace attach ${p.project.name} --path <dir>` });
+  }
+  for (const p of snap.projects.filter((x) => x.state === "pending")) {
+    if (p.reason === "its shadow folder in the workspace is gone") {
+      out.push({ text: `${p.project.name}'s shadow projects/${p.project.name}/ is gone — restore it from the workspace's git, or scaffold it again`, command: absorbCommand(p.project, p.reason) });
+      continue;
+    }
+    out.push(p.reason === "intake not converted"
+      ? { text: `${p.project.name}'s absorb is under way (${p.reason}) — finish its playbook, then \`doctrina intake --converted\` there`, command: absorbCommand(p.project, p.reason) }
+      : { text: `${p.project.name} has no specs yet (${p.reason}) — absorb it before routing work to it`, command: absorbCommand(p.project, p.reason) });
+  }
+  for (const { delivery: d, rows, blockers } of snap.open) {
+    if (d.projects.length === 0) {
+      out.push({ text: `delivery ${d.id} is routed nowhere yet`, command: `doctrina delivery route ${d.id} <a,b>` });
+      continue;
+    }
+    let moved = false;
+    for (const row of rows) {
+      if (row.missing || row.absent) continue;
+      if (row.changes.length === 0 && row.abandoned?.length) {
+        const a = row.abandoned[row.abandoned.length - 1];
+        out.push({ text: `${row.project}'s change ${a.id} for ${d.id} was abandoned${a.reason ? ` (${a.reason})` : ""} — re-route the delivery without ${row.project}, or open a new change there`, command: `doctrina delivery route ${d.id} ${d.projects.filter((n) => n !== row.project).join(",") || "<a,b>"}` });
+        moved = true;
+        continue;
+      }
+      if (row.changes.length === 0) {
+        out.push({ text: `${row.project} carries no change for ${d.id}`, command: cdThen(row.path, `doctrina work ${qarg(d.title)} --delivery ${d.id}`) });
+        moved = true;
+        continue;
+      }
+      for (const ch of row.changes.filter((x) => !x.archived)) {
+        if (ch.placeholders > 0) {
+          out.push({ text: `${row.project}: ${ch.id} still holds the scaffold's placeholder tasks — write its delta and its tasks as cards before handing one out`, command: cdThen(row.path, `doctrina work --resume ${ch.id}`) });
+          moved = true;
+          continue;
+        }
+        out.push(ch.tasksDone < ch.tasksTotal
+          ? { text: `${row.project}: ${ch.id} has ${ch.tasksTotal - ch.tasksDone} task${ch.tasksTotal - ch.tasksDone === 1 ? "" : "s"} left — hand the next card to an executor`, command: cdThen(row.path, `doctrina change card ${ch.id}`) }
+          : { text: `${row.project}: ${ch.id} has every task ticked — review and close it`, command: cdThen(row.path, `doctrina close ${ch.id}`) });
+        moved = true;
+      }
+    }
+    if (moved) continue;
+    out.push(blockers.length === 0
+      ? { text: `delivery ${d.id} is ready to close`, command: `doctrina delivery close ${d.id}` }
+      : recordAction(d, blockers[0]));
+  }
+  if (snap.open.length === 0 && snap.projects.length > 0 && out.length === 0) {
+    out.push({ text: "no delivery is open — an item of work across repositories opens one", command: 'doctrina delivery new "<title>" --ref <id>' });
+  }
+  if (snap.projects.length === 0) {
+    out.push({ text: "the workspace registers no repository yet", command: "doctrina workspace add <path> --role <r> --about \"<what it is>\"" });
+  }
+  return out;
+}
+
+/** The step that clears a delivery's first record gap — the command for it, not the check. */
+function recordAction(d, blocker) {
+  const file = `deliveries/${d.id}/delivery.md`;
+  if (/^## Story/.test(blocker)) return { text: `delivery ${d.id}: copy the item's story and acceptance criteria, verbatim, under ## Story in ${file}`, command: `doctrina delivery check ${d.id}` };
+  if (/^## Release/.test(blocker)) return { text: `delivery ${d.id}: record the release evidence under ## Release and tick each claim`, command: `doctrina delivery tick ${d.id}` };
+  if (/^## Observability/.test(blocker)) return { text: `delivery ${d.id}: record what was watched after the release under ## Observability in ${file}`, command: `doctrina delivery check ${d.id}` };
+  return { text: `delivery ${d.id}: ${blocker}`, command: `doctrina delivery check ${d.id}` };
+}
+
+/**
+ * Structural findings about the workspace itself — the integrity
+ * `doctrina validate` checks at its root. Errors break routing or a close;
+ * warnings are worth knowing.
+ * @returns {{ errors: string[], warnings: string[] }}
+ */
+export function workspaceFindings(snap) {
+  const errors = [];
+  const warnings = [];
+  const names = new Set(snap.ws.projects.map((p) => p.name));
+  for (const p of snap.ws.projects) {
+    for (const dep of p.dependsOn ?? []) if (!names.has(dep)) errors.push(`project ${p.name} depends on "${dep}", which the workspace does not register`);
+  }
+  for (const p of snap.projects) {
+    if (p.state === "missing") errors.push(`project ${p.project.name}: ${p.reason} — \`doctrina workspace attach ${p.project.name} --path <dir>\``);
+    if (p.project.mode !== "shadow" || p.state === "missing") continue;
+    const shadow = shadowDirOf(snap.wsDir, p.project.name);
+    if (!isDir(shadow)) {
+      errors.push(`shadow ${p.project.name}: projects/${p.project.name}/ is gone — restore it from the workspace's git, or \`doctrina workspace attach ${p.project.name}\` scaffolds it again`);
+      continue;
+    }
+    const plan = linkPlan(shadow, p.project.path);
+    const unlinked = plan.filter((l) => l.action === "link");
+    const conflicts = plan.filter((l) => l.action === "conflict");
+    if (unlinked.length > 0) errors.push(`shadow ${p.project.name}: ${unlinked.length} link${unlinked.length === 1 ? "" : "s"} missing from the repository — \`doctrina workspace attach ${p.project.name}\``);
+    if (conflicts.length > 0) warnings.push(`shadow ${p.project.name}: the repository has its own ${conflicts.map((l) => l.rel).slice(0, 3).join(", ")} where a link would go`);
+  }
+  // An in-repo project owns its hook files, so the workspace does not write
+  // them (third audit, change 0234): say when they leave the declared tools
+  // unguarded for a session opened in that repository.
+  if (snap.ws.tools.length > 0) {
+    for (const p of snap.projects) {
+      if (p.project.mode !== "in-repo" || p.state === "missing") continue;
+      for (const [dir, file] of [[".cursor", "hooks.json"], [".claude", "settings.json"]]) {
+        if (!isDir(path.join(p.project.path, dir))) continue;
+        const f = path.join(p.project.path, dir, file);
+        if (!isFile(f) || !read(f).includes("doctrina workspace guard")) {
+          warnings.push(`project ${p.project.name} is in-repo and its ${dir}/${file} runs no \`doctrina workspace guard\` — the tools the workspace declares are unguarded in a session opened there; copy the guard entry from the workspace root's ${dir}/${file}`);
+        }
+      }
+    }
+  }
+  // A declared tool whose server no MCP configuration names (fourth audit,
+  // change 0235). The guard matches on the server's KEY in the agent's
+  // config; the preset guesses "atlassian", and a server the operator named
+  // "jira-cloud" made every call through it an undeclared one — allowed.
+  const servers = mcpServerNames([snap.wsDir, ...snap.ws.projects.map((p) => p.path)]);
+  if (servers.found) {
+    for (const tool of snap.ws.tools.filter((x) => x.enabled !== false)) {
+      if (servers.names.has(tool.server)) continue;
+      const near = [...servers.names].find((n) => n.toLowerCase() === String(tool.server).toLowerCase());
+      warnings.push(near
+        ? `tool ${tool.name} declares server "${tool.server}", but the MCP configuration names it "${near}" — the guard matches the exact key: \`doctrina workspace tool ${tool.name} --server ${near}\``
+        : `tool ${tool.name} declares server "${tool.server}", which no MCP configuration here names (${[...servers.names].sort().join(", ") || "none"}) — the guard never sees its calls: \`doctrina workspace tool ${tool.name} --server <the key in mcp.json>\``);
+    }
+  }
+  // A dependency the manifests declare and the registry does not (second
+  // audit, change 0233): `delivery route` orders projects by --depends-on, so
+  // a front end that imports the shared library's package but was registered
+  // without the edge could be changed before the library it builds on.
+  const pkgs = new Map(snap.ws.projects.map((p) => [p.name, packageFacts(p.path)]));
+  for (const p of snap.ws.projects) {
+    const mine = pkgs.get(p.name);
+    if (!mine) continue;
+    for (const other of snap.ws.projects) {
+      const theirs = pkgs.get(other.name);
+      if (other === p || !theirs?.name || !mine.deps.has(theirs.name) || (p.dependsOn ?? []).includes(other.name)) continue;
+      warnings.push(`project ${p.name}'s package.json depends on ${theirs.name}, which is ${other.name} — declare it so routing orders them: \`doctrina workspace attach ${p.name} --depends-on ${[...(p.dependsOn ?? []), other.name].join(",")}\``);
+    }
+  }
+  for (const d of snap.deliveries) {
+    const status = (listHeader(d.text, "Status") ?? "").trim().toLowerCase();
+    if (!["open", "closed"].includes(status)) errors.push(`delivery ${d.id}: Status must be open or closed (got "${status}")`);
+    for (const name of d.projects) if (!names.has(name)) errors.push(`delivery ${d.id} routes "${name}", which the workspace does not register`);
+    if (status === "closed" && !listHeader(d.text, "Closed")) warnings.push(`delivery ${d.id} is closed with no Closed date`);
+    // A change that names this delivery from a project it does not route
+    // (change 0234): no status, check or close of the delivery counts it.
+    const outside = snap.ws.projects.map((p) => p.name).filter((n) => !d.projects.includes(n));
+    for (const row of deliveryChanges(snap.wsDir, snap.ws, { ...d, projects: outside })) {
+      for (const ch of row.changes.filter((x) => !x.archived)) {
+        warnings.push(`${row.project}'s change ${ch.id} names delivery ${d.id}, which does not route ${row.project} — route it back (\`doctrina delivery route ${d.id} ${[...d.projects, row.project].join(",")}\`) or close the change outside it`);
+      }
+    }
+  }
+  if (!isFile(path.join(snap.wsDir, "AGENTS.md"))) warnings.push("the workspace has no AGENTS.md hub — any workspace write regenerates it");
+  return { errors, warnings };
+}
+
+/** The resume note for the next planner session — `handoff` at the root. */
+export function workspaceHandoff(snap, date) {
+  const L = [`# Doctrina workspace handoff — ${snap.ws.name} (${date})`, ""];
+  L.push("## Projects", "");
+  for (const p of snap.projects) {
+    const open = p.open.length ? ` · open: ${p.open.map((o) => o.id ?? o).join(", ")}` : "";
+    L.push(`- **${p.project.name}** (${p.project.mode}, ${p.state}${p.project.role ? `, ${p.project.role}` : ""}) — ${p.reason}${open} · \`${p.project.path}\``);
+  }
+  if (snap.projects.length === 0) L.push("- none registered");
+  L.push("", "## Open deliveries", "");
+  for (const { delivery: d, rows, blockers, release } of snap.open) {
+    L.push(`### ${d.id} — ${d.title}${d.ref && d.ref !== "—" ? ` (${d.ref})` : ""}`, "");
+    for (const row of rows) {
+      if (row.missing) { L.push(`- ${row.project}: ${row.missing}`); continue; }
+      if (row.changes.length === 0 && row.abandoned?.length) { L.push(`- ${row.project}: ${row.abandoned.map((a) => `${a.id} abandoned${a.reason ? ` (${a.reason})` : ""}`).join(", ")} — no change left`); continue; }
+      if (row.changes.length === 0) { L.push(`- ${row.project}: no change yet`); continue; }
+      for (const ch of row.changes) L.push(`- ${row.project}: ${ch.id} — ${ch.status}, tasks ${ch.tasksDone}/${ch.tasksTotal}`);
+    }
+    if (release.length) L.push(`- Release: ${release.filter((b) => b.checked).length}/${release.length} claims ticked`);
+    if (blockers.length) L.push(`- Before the close: ${blockers.length} — \`doctrina delivery check ${d.id}\``);
+    L.push("");
+  }
+  if (snap.open.length === 0) L.push("- none", "");
+  L.push("## Next actions", "");
+  workspaceActions(snap).slice(0, 8).forEach((a, i) => L.push(`${i + 1}. ${a.text} — \`${a.command}\``));
+  L.push("", "*Commit the workspace: it is the version history of every shadow's context. Regenerate with `doctrina handoff`.*");
+  return L;
+}
+
+/**
+ * The projects a task is most likely about — `context --for` at the root,
+ * which cannot read one repository's specs for all of them.
+ */
+export function contextRouting(snap, task) {
+  return rankProjects(snap.wsDir, snap.ws, task).map((r) => ({
+    name: r.project.name, path: r.project.path, score: r.score, shared: r.shared,
+    state: snap.projects.find((p) => p.project.name === r.project.name)?.state ?? "missing",
+  }));
+}
+
+/** One-glance status at the root — `status`. */
+export function workspaceStatus(snap) {
+  const ready = snap.projects.filter((p) => p.state === "ready").length;
+  const openChanges = snap.projects.reduce((n, p) => n + p.open.length, 0);
+  return {
+    name: snap.ws.name,
+    projects: snap.projects.length, ready,
+    pending: snap.projects.filter((p) => p.state === "pending").map((p) => p.project.name),
+    missing: snap.projects.filter((p) => p.state === "missing").map((p) => p.project.name),
+    openChanges,
+    deliveries: { open: snap.open.length, closed: snap.deliveries.length - snap.open.length },
+    tools: snap.ws.tools.length,
+  };
+}
+
+/**
+ * For `prime` inside a project of a workspace: the workspace it belongs to
+ * and the open deliveries routed to it — an executor or a session opened in
+ * the repository otherwise never learns a delivery is waiting on it.
+ * @returns {{ name: string, dir: string, project: string, deliveries: Array<{ id: string, title: string, changes: string[], open: number }> } | null}
+ */
+export function projectWorkspaceLine(projectRoot) {
+  const found = findWorkspace(projectRoot);
+  if (!found) return null;
+  let ws;
+  try {
+    ws = readWorkspace(found.dir);
+  } catch {
+    return null;
+  }
+  const project = projectAt(ws, projectRoot);
+  if (!project) return null;
+  const deliveries = [];
+  for (const d of listDeliveries(found.dir)) {
+    const full = readDelivery(found.dir, d.id);
+    if (full.status === "closed" || !full.projects.includes(project.name)) continue;
+    const row = deliveryChanges(found.dir, ws, full).find((r) => r.project === project.name);
+    const changes = row?.changes ?? [];
+    deliveries.push({ id: full.id, title: full.title, changes: changes.map((ch) => `${ch.id} ${ch.status}`), open: changes.filter((ch) => !ch.archived).length });
+  }
+  return { name: ws.name, dir: found.dir, project: project.name, deliveries };
+}
+
+/** The package name a repository publishes and the names it depends on — from its root package.json. */
+function packageFacts(dir) {
+  const file = path.join(dir, "package.json");
+  if (!isFile(file)) return null;
+  try {
+    const pkg = JSON.parse(read(file));
+    const deps = new Set(["dependencies", "devDependencies", "peerDependencies", "optionalDependencies"]
+      .flatMap((k) => Object.keys(pkg?.[k] ?? {})));
+    return { name: typeof pkg?.name === "string" ? pkg.name : null, deps };
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * A clone of a SHADOWED repository at another path (third audit, change
+ * 0234): it has no `.doctrina/` — the links live in the registered clone —
+ * so every command answered "run `doctrina init`", which would plant a
+ * `.doctrina/` in a repository that may not carry one. Matched by the git
+ * remote: the clone's origin is the registered clone, or both share an origin.
+ * The registered repository itself, with its links gone, is returned with
+ * `same: true`: `attach` alone links it again.
+ * @returns {{ wsDir: string, name: string, path: string, same?: boolean } | null}
+ */
+export function shadowedCloneAt(cwd) {
+  if (existsSync(path.join(cwd, ".doctrina"))) return null;
+  // The pointer route finds a workspace only for a REGISTERED path; a clone
+  // elsewhere is exactly what it cannot match, so the pointer is read here.
+  const pointed = isFile(pointerPath()) ? read(pointerPath()).trim() : "";
+  const found = findWorkspace(cwd) ?? (pointed && isFile(path.join(pointed, "workspace.json")) ? { dir: pointed } : null);
+  if (!found) return null;
+  const origin = (/** @type {string} */ dir) => {
+    const r = git(dir, ["remote", "get-url", "origin"]);
+    return r.state === GIT_STATE.OK ? r.stdout.trim().replace(/\.git$/, "").replace(/\/+$/, "") : null;
+  };
+  const real = (/** @type {string} */ p) => {
+    try {
+      return realpathSync(p);
+    } catch {
+      return path.resolve(p);
+    }
+  };
+  let ws;
+  try {
+    ws = readWorkspace(found.dir);
+  } catch {
+    return null;
+  }
+  // The registered repository itself, its links gone (change 0235): attach.
+  const same = ws.projects.find((x) => x.mode === "shadow" && real(x.path) === real(cwd));
+  if (same) return { wsDir: found.dir, name: same.name, path: same.path, same: true };
+  const mine = origin(cwd);
+  if (!mine) return null;
+  for (const p of ws.projects.filter((x) => x.mode === "shadow")) {
+    const theirs = isDir(p.path) ? origin(p.path) : null;
+    const local = !/^[a-z][a-z0-9+.-]*:\/\/|^[^/\\]+@[^:]+:/i.test(mine) && isDir(path.resolve(cwd, mine)) && real(path.resolve(cwd, mine)) === real(p.path);
+    if (local || (theirs && theirs === mine)) return { wsDir: found.dir, name: p.name, path: p.path };
+  }
+  return null;
+}
+
+/**
+ * The MCP server keys the agents' configurations declare: each folder's
+ * `.cursor/mcp.json` and `.mcp.json`, the user's `~/.cursor/mcp.json`, and
+ * `~/.claude.json` (its own servers and each project's). `found` is false
+ * when no configuration could be read — then nothing can be said.
+ * @param {string[]} dirs
+ */
+export function mcpServerNames(dirs, home = os.homedir()) {
+  const names = new Set();
+  let found = false;
+  const take = (/** @type {unknown} */ servers) => {
+    if (servers && typeof servers === "object") for (const k of Object.keys(servers)) names.add(k);
+  };
+  const files = [...dirs.flatMap((d) => [path.join(d, ".cursor", "mcp.json"), path.join(d, ".mcp.json")]),
+    path.join(home, ".cursor", "mcp.json"), path.join(home, ".claude.json")];
+  for (const file of files) {
+    if (!isFile(file)) continue;
+    let json;
+    try {
+      json = JSON.parse(read(file));
+    } catch {
+      continue;
+    }
+    found = true;
+    take(json?.mcpServers);
+    if (json?.projects && typeof json.projects === "object") for (const p of Object.values(json.projects)) take(p?.mcpServers);
+  }
+  return { found, names };
+}
+
+/** The command that links a shadowed repository's context into `cwd`. */
+export function attachCommand(clone, cwd) {
+  return cdThen(clone.wsDir, clone.same ? `doctrina workspace attach ${clone.name}` : `doctrina workspace attach ${clone.name} --path ${qpath(cwd)}`);
+}