doctrina-cli 0.20.0 → 0.21.0

package/src/lib/workspace-agents.js

@@ -2,7 +2,8 @@
 import path from "node:path";
 import { isFile, read, relPath, toPosix, write } from "./fs-ops.js";
 import { mergeJson } from "./adapters.js";
-import { projectState } from "./workspace.js";
+import { absorbCommand, projectState, shadowDirOf } from "./workspace.js";
+import { isDir } from "./fs-ops.js";
 
 // The ORCHESTRATOR's files, generated at the workspace root from
 // workspace.json (change 0223, ADR 0031) — what Cursor or Claude Code read
@@ -116,7 +117,9 @@ export function workspaceHub(ws, wsDir, states) {
   L.push("the analyst: they bring the item of work and approve; you read it, plan it,");
   L.push("delegate it, review it and close it (ADR 0030).", "");
   L.push("## Session start", "");
-  L.push("`doctrina prime` here: the projects, their state and the open deliveries.", "");
+  L.push("`doctrina prime` here: the projects, their state and the open deliveries.");
+  L.push("Unsure what comes next: `doctrina next`. Before a compaction or a handover:");
+  L.push("`doctrina handoff`. Both answer for the whole workspace from here.", "");
   L.push("## Projects", "");
   L.push("| Project | Mode | State | Role | Depends on | Path | What it is |");
   L.push("|---|---|---|---|---|---|---|");
@@ -126,12 +129,12 @@ export function workspaceHub(ws, wsDir, states) {
   }
   if (ws.projects.length === 0) L.push("| — | | | | | | register one: `doctrina workspace add <path>` |");
   L.push("");
-  L.push("A `pending` project has no specs yet: `cd <path> && doctrina intake --from-code`");
+  L.push("A `pending` project has no specs yet: `cd <path> && doctrina intake --from-code` (once its inventory is stored, a bare `doctrina intake` reprints the playbook)");
   L.push("and run the absorb playbook before routing work to it.", "");
   L.push("## Tools", "");
   if (ws.tools.length === 0) {
-    L.push("None declared. Declare each MCP server the work uses, e.g.");
-    L.push("`doctrina workspace tool jira` · `doctrina workspace tool datadog`.");
+    L.push("None declared. Declare each MCP server the work uses:");
+    L.push("`doctrina workspace tool <name> --server <mcp-server> --for <roles>`.");
   } else {
     L.push("| Tool | MCP server | Access | Used by | For |");
     L.push("|---|---|---|---|---|");
@@ -151,8 +154,9 @@ export function workspaceHub(ws, wsDir, states) {
   L.push("   repository at a time.");
   L.push("4. Review with `doctrina-reviewer`, then close each change yourself:");
   L.push("   `doctrina close <id>`. Executors never close.");
-  L.push("5. Fill the delivery's Release and Observability, then");
-  L.push("   `doctrina delivery check <id>` → `doctrina delivery close <id>`.");
+  L.push("5. Record the release under the delivery's Release and tick each claim");
+  L.push("   (`doctrina delivery tick <id> <n>`), record what was watched under");
+  L.push("   Observability, then `doctrina delivery check <id>` → `doctrina delivery close <id>`.");
   L.push("6. Name the delivery id in your first sentence to the human, repeat the");
   L.push("   `Tell the human:` lines, and commit the workspace when a delivery closes.", "");
   L.push("## Rules", "");
@@ -195,8 +199,8 @@ export function workspacePrimer(ws, wsDir, open) {
   if (open.length === 0) L.push("  none");
   L.push("", `Tools  ${ws.tools.length ? ws.tools.map((t) => `${t.name} (${t.access})`).join(" · ") : "none declared — doctrina workspace tool <name>"}`);
   L.push("", "Next");
-  const pending = ws.projects.filter((p) => projectState(wsDir, p).state === "pending");
-  if (pending.length) L.push(`  absorb ${pending[0].name} before routing work to it: cd ${toPosix(pending[0].path)} && doctrina intake --from-code`);
+  const pending = ws.projects.map((p) => ({ p, s: projectState(wsDir, p) })).filter((x) => x.s.state === "pending");
+  if (pending.length) L.push(`  absorb ${pending[0].p.name} before routing work to it: ${absorbCommand({ path: toPosix(pending[0].p.path), name: pending[0].p.name }, pending[0].s.reason)}`);
   if (open.length) L.push(`  continue ${open[0].id}: doctrina delivery status ${open[0].id}`);
   L.push("  new work across repositories: doctrina delivery new \"<title>\" --ref <tracker-id>");
   return L;
@@ -225,15 +229,41 @@ const CLAUDE_SETTINGS = {
   },
 };
 
-function mergedJson(file, ours) {
-  if (!isFile(file)) return JSON.stringify(ours, null, 2) + "\n";
-  let theirs;
-  try {
-    theirs = JSON.parse(read(file));
-  } catch {
-    return null; // an unreadable file the operator owns is left alone
+function mergedJson(file, ours, failClosed = false) {
+  let theirs = null;
+  if (isFile(file)) {
+    try {
+      theirs = JSON.parse(read(file));
+    } catch {
+      return null; // an unreadable file the operator owns is left alone
+    }
   }
-  return JSON.stringify(mergeJson(theirs, ours), null, 2) + "\n";
+  const merged = theirs === null ? structuredClone(ours) : mergeJson(theirs, ours);
+  // The guard's Cursor entry is OURS to shape (change 0238): replaced, never
+  // appended beside an older copy — a second entry would run it twice.
+  const mcp = merged?.hooks?.beforeMCPExecution;
+  if (Array.isArray(mcp)) {
+    const others = mcp.filter((h) => !(h && typeof h === "object" && h.command === GUARD_COMMAND));
+    if (others.length !== mcp.length || ours?.hooks?.beforeMCPExecution) {
+      merged.hooks.beforeMCPExecution = [...others, guardEntry(failClosed)];
+    }
+  }
+  return JSON.stringify(merged, null, 2) + "\n";
+}
+
+const GUARD_COMMAND = "doctrina workspace guard --hook cursor";
+
+/**
+ * The Cursor guard hook. With tools declared it fails CLOSED (change 0238):
+ * Cursor lets a call through when a hook crashes, times out or cannot start
+ * — `doctrina` missing from the PATH Cursor runs hooks with is enough — so a
+ * read-only tool would write with no guard, in silence. Failing closed turns
+ * a broken install into a refused call the human sees. With nothing
+ * declared, the guard has no opinion to enforce, and a broken install must
+ * not block the operator's other MCP servers.
+ */
+function guardEntry(failClosed) {
+  return failClosed ? { command: GUARD_COMMAND, failClosed: true } : { command: GUARD_COMMAND };
 }
 
 /**
@@ -251,9 +281,26 @@ export function writeOrchestratorFiles(ws, wsDir, states) {
   };
   put("AGENTS.md", workspaceHub(ws, wsDir, states));
   put(".cursor/rules/00-doctrina-workspace.mdc", CURSOR_RULE(ws));
-  put(".cursor/hooks.json", mergedJson(path.join(wsDir, ".cursor", "hooks.json"), CURSOR_HOOKS));
+  const failClosed = ws.tools.some((x) => x.enabled !== false);
+  put(".cursor/hooks.json", mergedJson(path.join(wsDir, ".cursor", "hooks.json"), CURSOR_HOOKS, failClosed));
   put(".claude/settings.json", mergedJson(path.join(wsDir, ".claude", "settings.json"), CLAUDE_SETTINGS));
   for (const role of agentRoles(ws)) put(`.claude/agents/doctrina-${role}.md`, agentFile(ws, role));
   put(`${ws.name}.code-workspace`, codeWorkspace(ws, wsDir));
+  // The guard inside every shadow too (third audit, change 0234). It was
+  // installed at the root only, and an executor works INSIDE the repository
+  // (ADR 0030): Cursor and Claude Code read that folder's own hook files, so
+  // every MCP call an executor made there went through no guard at all.
+  for (const p of ws.projects.filter((x) => x.mode === "shadow")) {
+    const shadow = shadowDirOf(wsDir, p.name);
+    const rel = relPath(wsDir, shadow);
+    if (isDir(path.join(shadow, ".cursor"))) put(`${rel}/.cursor/hooks.json`, mergedJson(path.join(shadow, ".cursor", "hooks.json"), GUARD_HOOKS.cursor, failClosed));
+    if (isDir(path.join(shadow, ".claude"))) put(`${rel}/.claude/settings.json`, mergedJson(path.join(shadow, ".claude", "settings.json"), GUARD_HOOKS.claude));
+  }
   return out;
 }
+
+/** The guard's own hook entries — what a shadow's hook files need beside their session hook. */
+export const GUARD_HOOKS = {
+  cursor: { version: 1, hooks: { beforeMCPExecution: CURSOR_HOOKS.hooks.beforeMCPExecution } },
+  claude: { hooks: { PreToolUse: CLAUDE_SETTINGS.hooks.PreToolUse } },
+};

package/src/lib/workspace-guard.js

@@ -0,0 +1,65 @@
+// @ts-check
+import { readFileSync } from "node:fs";
+import process from "node:process";
+import { c } from "./colors.js";
+import { EXIT } from "./exit-codes.js";
+import { findWorkspace, readWorkspace } from "./workspace-locate.js";
+import { guardDecision, splitClaudeToolName } from "./workspace-tools.js";
+
+// `doctrina workspace guard --hook cursor|claude` — the pre-call hook an
+// agent runs before EVERY MCP call (ADR 0031). It lives apart from the rest
+// of `workspace`, in lib/ so the entrypoint and the `workspace` command share
+// one door, and the entrypoint routes to it directly (fifth audit, change
+// 0236), so a call pays for the guard and not for the whole CLI. It is an
+// I/O adapter — stdin in, the agent's JSON out — around guardDecision.
+
+/** Run the guard from the current directory. */
+export function runGuard(hook) {
+  return workspaceGuard(findWorkspace(process.cwd())?.dir ?? null, hook);
+}
+
+export function workspaceGuard(wsDir, hook) {
+  if (hook !== "cursor" && hook !== "claude") {
+    console.error(c.red("error:") + ` --hook needs cursor or claude (got "${hook ?? ""}")`);
+    return EXIT.USAGE;
+  }
+  let call = {};
+  try {
+    call = JSON.parse(readFileSync(0, "utf8") || "{}");
+  } catch {
+    call = {};
+  }
+  // Cursor sets these for every hook it runs, its imported Claude ones included.
+  const cursorRuns = Boolean(process.env.CURSOR_VERSION && process.env.CURSOR_PROJECT_DIR);
+  let server = null;
+  let tool = null;
+  if (hook === "cursor") {
+    server = call.mcp_server_name ?? null;
+    tool = call.tool_name ?? null;
+  } else {
+    const split = splitClaudeToolName(call.tool_name ?? "");
+    if (split) ({ server, tool } = split);
+    // Cursor runs this Claude-format hook too, as its preToolUse (sixth
+    // audit, change 0237), with its own payload: read the server from it.
+    else if (cursorRuns && call.mcp_server_name) ({ mcp_server_name: server, tool_name: tool } = call);
+  }
+  const tools = wsDir ? readWorkspace(wsDir).tools : [];
+  const verdict = server && tool ? guardDecision(tools, server, tool, call.tool_input) : { decision: "none", reason: "" };
+  if (hook === "cursor") {
+    const permission = verdict.decision === "none" ? "allow" : verdict.decision;
+    const out = { permission };
+    if (permission !== "allow") Object.assign(out, { user_message: verdict.reason, agent_message: verdict.reason });
+    console.log(JSON.stringify(out));
+  } else if (verdict.decision !== "none") {
+    console.log(JSON.stringify({ hookSpecificOutput: {
+      hookEventName: "PreToolUse", permissionDecision: verdict.decision, permissionDecisionReason: verdict.reason,
+    } }));
+  } else if (cursorRuns) {
+    // preToolUse is a permission hook in Cursor: an answer that is not JSON
+    // blocks the call. With no opinion, the Claude-format allow — which
+    // Cursor translates — and never silence. (In Claude Code itself "allow"
+    // would skip the human's prompt, so it is printed only under Cursor.)
+    console.log(JSON.stringify({ hookSpecificOutput: { hookEventName: "PreToolUse", permissionDecision: "allow", permissionDecisionReason: "no Doctrina opinion" } }));
+  }
+  return EXIT.OK;
+}

package/src/lib/workspace-locate.js

@@ -0,0 +1,141 @@
+// @ts-check
+import { existsSync, realpathSync } from "node:fs";
+import path from "node:path";
+import os from "node:os";
+import process from "node:process";
+import { isFile, read, write } from "./fs-ops.js";
+
+// WHERE A WORKSPACE IS, and nothing else (fifth audit, change 0236). The
+// guard runs on every MCP call an agent makes, and it needs only this: find
+// the workspace, read its registry. It used to load lib/workspace.js, which
+// pulls the project snapshot and git in with it — ~90 ms a call. Everything
+// here is re-exported by lib/workspace.js, so callers keep one door.
+
+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;
+}
+
+export 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;
+}

package/src/lib/workspace-tools.js

@@ -53,35 +53,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;
 }
 
 /**