doctrina-cli 0.20.0 → 0.21.0

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)}`);
+}

package/src/lib/workspace.js

@@ -4,11 +4,11 @@ import {
   realpathSync, rmdirSync, statSync, symlinkSync, unlinkSync, copyFileSync,
 } from "node:fs";
 import path from "node:path";
-import os from "node:os";
 import { isDir, isFile, read, toPosix, write } from "./fs-ops.js";
 import { listHeader } from "./scan.js";
 import { openChanges } from "./snapshot.js";
 import { git as runGit, GIT_STATE } from "./git.js";
+import { cdThen } from "./shell.js";
 
 // A WORKSPACE holds the context of several repositories in one place (ADR
 // 0029): which projects exist, what each one is, how they depend on each
@@ -24,148 +24,49 @@ import { git as runGit, GIT_STATE } from "./git.js";
 // the repository, because from its working directory `.doctrina/` is simply
 // there.
 
-export const WORKSPACE_FILE = "workspace.json";
-export const WORKSPACE_SCHEMA = 1;
-export const PROJECT_MODES = ["in-repo", "shadow"];
-export const PROJECT_NAME = /^[a-z0-9][a-z0-9._-]*$/;
-export const EXCLUDE_BEGIN = "# doctrina:workspace:begin — managed by `doctrina workspace attach`; edits inside are overwritten";
-export const EXCLUDE_END = "# doctrina:workspace:end";
-
-/** A fresh workspace document. */
-export function blankWorkspace(name) {
-  return {
-    doctrina_workspace: WORKSPACE_SCHEMA,
-    name,
-    projects: [],
-    tools: [],
-    agents: { planner: { model: "inherit" }, executor: { model: "inherit" } },
-  };
-}
-
-export function isWorkspaceDir(dir) {
-  const p = path.join(dir, WORKSPACE_FILE);
-  if (!isFile(p)) return false;
-  try {
-    return JSON.parse(read(p)).doctrina_workspace !== undefined;
-  } catch {
-    return false;
-  }
-}
-
-/** The workspace document, with every optional list present. */
-export function readWorkspace(dir) {
-  const ws = JSON.parse(read(path.join(dir, WORKSPACE_FILE)));
-  ws.projects = Array.isArray(ws.projects) ? ws.projects : [];
-  ws.tools = Array.isArray(ws.tools) ? ws.tools : [];
-  ws.agents = ws.agents && typeof ws.agents === "object" ? ws.agents : {};
-  return ws;
-}
-
-export function writeWorkspace(dir, ws) {
-  write(path.join(dir, WORKSPACE_FILE), JSON.stringify(ws, null, 2) + "\n", { force: true });
-}
-
-/** Where the CLI keeps its per-user state: `$DOCTRINA_HOME`, else `~/.doctrina`. */
-export function doctrinaHome(env = process.env) {
-  return env.DOCTRINA_HOME && env.DOCTRINA_HOME.trim() !== ""
-    ? path.resolve(env.DOCTRINA_HOME)
-    : path.join(os.homedir(), ".doctrina");
-}
-
-/** The pointer `workspace init` leaves, so an in-repo project can find its workspace. */
-export function pointerPath(env = process.env) {
-  return path.join(doctrinaHome(env), "workspace");
-}
-
-export function writePointer(dir, env = process.env) {
-  write(pointerPath(env), path.resolve(dir) + "\n", { force: true });
-}
-
-function ancestors(start) {
-  const out = [];
-  let cur = path.resolve(start);
-  for (;;) {
-    out.push(cur);
-    const up = path.dirname(cur);
-    if (up === cur) return out;
-    cur = up;
-  }
-}
-
-/**
- * The workspace this directory belongs to, or null. In order:
- *   1. `$DOCTRINA_WORKSPACE`;
- *   2. the directory or an ancestor holding `workspace.json` (the orchestrator
- *      runs at the workspace root);
- *   3. the real path of `./.doctrina` — a shadow project's link points into
- *      its workspace;
- *   4. the pointer `workspace init` wrote, when the workspace lists this
- *      directory as a project.
- * @returns {{ dir: string, via: string } | null}
- */
-export function findWorkspace(cwd, env = process.env) {
-  if (env.DOCTRINA_WORKSPACE && env.DOCTRINA_WORKSPACE.trim() !== "") {
-    const dir = path.resolve(env.DOCTRINA_WORKSPACE);
-    return isWorkspaceDir(dir) ? { dir, via: "DOCTRINA_WORKSPACE" } : null;
-  }
-  for (const dir of ancestors(cwd)) {
-    if (isWorkspaceDir(dir)) return { dir, via: "directory" };
-  }
-  const local = path.join(cwd, ".doctrina");
-  if (existsSync(local)) {
-    try {
-      const real = realpathSync(local);
-      if (real !== path.resolve(local)) {
-        for (const dir of ancestors(path.dirname(real))) {
-          if (isWorkspaceDir(dir)) return { dir, via: "shadow link" };
-        }
-      }
-    } catch { /* an unreadable link is no workspace */ }
-  }
-  const pointer = pointerPath(env);
-  if (isFile(pointer)) {
-    const dir = read(pointer).trim();
-    if (dir && isWorkspaceDir(dir) && projectAt(readWorkspace(dir), cwd)) return { dir, via: "pointer" };
-  }
-  return null;
-}
-
-/** The registered project whose path is `dir`, or null. */
-export function projectAt(ws, dir) {
-  const want = safeReal(dir);
-  return ws.projects.find((p) => safeReal(p.path) === want) ?? null;
-}
-
-function safeReal(p) {
-  try {
-    return realpathSync(p);
-  } catch {
-    return path.resolve(p);
-  }
-}
-
-export function shadowDirOf(wsDir, name) {
-  return path.join(wsDir, "projects", name);
-}
-
-/** The directory whose `.doctrina/` holds this project's artifacts. */
-export function artifactRootOf(wsDir, project) {
-  return project.mode === "shadow" ? shadowDirOf(wsDir, project.name) : project.path;
-}
+export {
+  WORKSPACE_FILE, WORKSPACE_SCHEMA, PROJECT_MODES, PROJECT_NAME, EXCLUDE_BEGIN, EXCLUDE_END,
+  blankWorkspace, isWorkspaceDir, readWorkspace, writeWorkspace, doctrinaHome, pointerPath, writePointer,
+  findWorkspace, projectAt, shadowDirOf, artifactRootOf,
+} from "./workspace-locate.js";
+import {
+  EXCLUDE_BEGIN, EXCLUDE_END, isWorkspaceDir, readWorkspace, writeWorkspace, findWorkspace, projectAt,
+  shadowDirOf, artifactRootOf, WORKSPACE_FILE, doctrinaHome, pointerPath, blankWorkspace, writePointer, PROJECT_NAME, PROJECT_MODES, WORKSPACE_SCHEMA, safeReal,
+} from "./workspace-locate.js";
 
 /**
  * Where a project stands. `missing` when its repository path is gone;
  * `pending` while it has no spec or its intake is unconverted — the
  * project still has to be absorbed; `ready` otherwise.
  */
+const INTAKE_PENDING = "intake not converted";
+// A shadow's folder in the workspace is gone (change 0235): `attach` restores it.
+const SHADOW_GONE = "its shadow folder in the workspace is gone";
+
+/**
+ * The command that moves a pending project on (second audit, change 0233).
+ * `--from-code` starts an absorb and refuses once the inventory is stored —
+ * every surface still named it for a project whose absorb was under way. A
+ * stored, pending intake reprints its playbook with a bare `doctrina intake`.
+ * @param {{ path: string, name?: string }} project
+ * @param {string} reason  projectState's reason
+ */
+export function absorbCommand(project, reason) {
+  if (reason === SHADOW_GONE) return `doctrina workspace attach ${project.name ?? "<name>"}`;
+  return reason === INTAKE_PENDING
+    ? cdThen(project.path, "doctrina intake")
+    : cdThen(project.path, "doctrina intake --from-code");
+}
+
 export function projectState(wsDir, project) {
   if (!isDir(project.path)) return { state: "missing", reason: `path not found: ${project.path}`, open: [] };
   const root = artifactRootOf(wsDir, project);
   const doctrina = path.join(root, ".doctrina");
+  if (project.mode === "shadow" && !isDir(doctrina)) return { state: "pending", reason: SHADOW_GONE, open: [] };
   if (!isDir(doctrina)) return { state: "pending", reason: "no .doctrina/ yet", open: [] };
   const intake = path.join(doctrina, "intake.md");
   if (isFile(intake) && /pending/i.test(listHeader(read(intake), "Status") ?? "")) {
-    return { state: "pending", reason: "intake not converted", open: openChanges(root) };
+    return { state: "pending", reason: INTAKE_PENDING, open: openChanges(root) };
   }
   const specs = path.join(doctrina, "specs");
   const count = isDir(specs) ? readdirSync(specs).filter((d) => isFile(path.join(specs, d, "spec.md"))).length : 0;
@@ -274,6 +175,57 @@ export function applyLinks(plan, shadowDir, repoDir) {
   return done;
 }
 
+/**
+ * The shadow folder a repository's `.doctrina/` links to, or null when the
+ * repository owns its `.doctrina/` (change 0238).
+ * @param {string} projectRoot
+ */
+export function shadowRootOf(projectRoot) {
+  const link = path.join(projectRoot, ".doctrina");
+  try {
+    if (!lstatSync(link).isSymbolicLink()) return null;
+    return path.dirname(realpathSync(link));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Re-link a shadowed repository after its shadow gained or lost files
+ * (change 0238): a link for each new file, the links to removed files taken
+ * out, and the exclude block rewritten. A command that writes an adapter
+ * file for a shadowed repository writes it in the shadow and calls this —
+ * written in the repository it was a stray, untracked file.
+ * @param {string} projectRoot
+ * @param {Array<{ rel: string, content: string }>} gone  the files the shadow lost, with what they held
+ * @returns {{ linked: string[], unlinked: string[] } | null}  null for a repository that is not a shadow
+ */
+export function relinkShadow(projectRoot, gone = []) {
+  const shadow = shadowRootOf(projectRoot);
+  if (!shadow) return null;
+  const unlinked = [];
+  for (const { rel, content } of gone) {
+    const at = path.join(projectRoot, rel);
+    let st;
+    try {
+      st = lstatSync(at);
+    } catch {
+      continue;
+    }
+    // A symlink to the removed file, or the hard link or copy a platform
+    // without symlinks got instead — still holding what the shadow held.
+    if (st.isSymbolicLink() || (st.isFile() && readFileSync(at, "utf8").replace(/\r\n/g, "\n").trim() === content.replace(/\r\n/g, "\n").trim())) {
+      unlinkSync(at);
+      unlinked.push(toPosix(rel));
+      pruneEmpty(path.dirname(at), projectRoot);
+    }
+  }
+  const plan = linkPlan(shadow, projectRoot);
+  const linked = applyLinks(plan, shadow, projectRoot).map((d) => d.rel);
+  writeExclude(projectRoot, excludeEntries(plan, projectRoot));
+  return { linked, unlinked };
+}
+
 /**
  * Remove every link the shadow put in the repository — the link, never what
  * it points at: `fs-ops.remove` follows a directory link and would empty

package/templates/AGENTS.md.template

@@ -64,7 +64,7 @@ canonical templates and syncs `index.json`. Flags: `doctrina <cmd> --help`.
 - `doctrina verify` — the project's declared typecheck/test/build checks. *When:* the real build gate must run.
 - `doctrina close <id...>` — the whole closing sequence in one attested pass. *When:* a change is implemented and ready to finish.
 - `doctrina doctor` — aggregate diagnostic with per-finding remedies. *When:* something looks wrong and you do not know which gate to ask.
-**Orchestrate** (triggers: `doctrina <command> --help`) — `doctrina workspace init|add|attach|detach|list|tool|guard` · `doctrina delivery new|route|list|status|check|close`
+**Orchestrate** (triggers: `doctrina <command> --help`) — `doctrina workspace init|add|attach|detach|list|tool|guard` · `doctrina delivery new|route|list|status|tick|check|close`
 **Maintain** (triggers: `doctrina <command> --help`) — `doctrina templates list` · `doctrina hooks install` · `doctrina index rebuild` · `doctrina watch` · `doctrina metrics` · `doctrina completion` · `doctrina upgrade --write` · `doctrina ci --emit github`
 <!-- doctrina:surface:end -->
 

package/templates/README.md

@@ -27,6 +27,7 @@ replace. No conditionals, loops, or includes.
 | `{{AGENTS_MD_PATH}}` | Path to root `AGENTS.md` from the adapter location | per adapter |
 | `{{DELIVERY_ID}}` | Delivery folder identifier (`NNNN-slug`) | required in `delivery` |
 | `{{DELIVERY_TITLE}}` | The delivery's title | required in `delivery` |
+| `{{DELIVERY_TITLE_ARG}}` | The delivery's title quoted as one shell argument, for a command line | optional in the `delivery` playbook |
 | `{{DELIVERY_REF}}` | The tracker item it comes from | `—` |
 | `{{DELIVERY_PROJECTS}}` | The routed projects, dependencies first | `—` |
 
@@ -107,7 +108,7 @@ adapters/
   claude/.claude/commands/doctrina-*.md.template   native slash commands (core loop)
   codex/README.md
   cursor/.cursor/rules/00-doctrina.mdc.template
-  cursor/.cursor/commands/doctrina-*.md.template   native slash commands (core loop)
+  cursor/.cursor/skills/doctrina-*/SKILL.md.template   the core loop as skills (explicit `/` invocation)
   copilot/.github/copilot-instructions.md.template
   gemini/GEMINI.md.template
   aider/CONVENTIONS.md.template