doctrina-cli 0.20.0 → 0.22.0

package/src/commands/workspace.js

@@ -5,7 +5,7 @@ import { spawnSync } from "node:child_process";
 import { readFileSync } from "node:fs";
 import { fileURLToPath } from "node:url";
 import { exists, isDir, mkdirp, relPath, write } from "../lib/fs-ops.js";
-import { flagString } from "../lib/args.js";
+import { flagString, flagGivenWithoutValue } from "../lib/args.js";
 import { c } from "../lib/colors.js";
 import { suggest } from "../lib/suggest.js";
 import { EXIT, PreconditionError } from "../lib/exit-codes.js";
@@ -14,8 +14,11 @@ import {
   findWorkspace, isWorkspaceDir, linkPlan, projectAt, projectState, readWorkspace, removeLinks,
   shadowDirOf, writeExclude, writePointer, writeWorkspace, gitInit,
 } from "../lib/workspace.js";
-import { TOOL_PRESETS, guardDecision, splitClaudeToolName, toolEntry } from "../lib/workspace-tools.js";
+import { TOOL_PRESETS, toolEntry } from "../lib/workspace-tools.js";
+import { workspaceGuard } from "../lib/workspace-guard.js";
 import { writeOrchestratorFiles } from "../lib/workspace-agents.js";
+import { cdThen } from "../lib/shell.js";
+import { mcpServerNames } from "../lib/workspace-view.js";
 
 // `doctrina workspace` — the context of several repositories in one place
 // (ADR 0029). The decisions live in lib/workspace.js; this module renders
@@ -26,7 +29,7 @@ const CLI_ENTRY = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..
 
 export const flags = {
   boolean: ["json", "no-git", "remove"],
-  string: ["name", "mode", "role", "about", "depends-on", "agent", "path", "server", "access", "for", "purpose", "hook"],
+  string: ["name", "mode", "role", "about", "depends-on", "agent", "path", "server", "access", "for", "purpose", "only", "hook"],
 };
 
 export async function run(positional, flags) {
@@ -140,22 +143,7 @@ function workspaceAdd(wsDir, pathArg, flags) {
     about: flagString(flags, "about") ?? "",
     dependsOn,
   };
-  if (mode === "shadow") {
-    const shadow = shadowDirOf(wsDir, name);
-    if (!isDir(path.join(shadow, ".doctrina"))) {
-      mkdirp(shadow);
-      const agent = flagString(flags, "agent") ?? "cursor";
-      const r = spawnSync(process.execPath, [CLI_ENTRY, "init", "--non-interactive",
-        "--project-name", name, "--project-description", project.about || `${name} (absorbed into a workspace)`,
-        "--agent", agent], { cwd: shadow, encoding: "utf8", env: { ...process.env, NO_COLOR: "1" } });
-      if (r.status !== 0) {
-        console.error(c.red("error:") + ` could not scaffold the shadow at ${shadow}`);
-        console.error(r.stderr.trim());
-        return EXIT.GATE;
-      }
-      console.log(c.green("created") + ` shadow ${relPath(wsDir, shadow)}/ (AGENTS.md, .doctrina/, ${agent} adapter)`);
-    }
-  }
+  if (mode === "shadow" && !scaffoldShadow(wsDir, project, flagString(flags, "agent") ?? "cursor")) return EXIT.GATE;
   ws.projects.push(project);
   writeWorkspace(wsDir, ws);
   console.log(c.green("registered") + ` ${name} (${mode}) → ${repo}`);
@@ -185,7 +173,7 @@ function printProjectNext(wsDir, project) {
   if (st.state === "pending") {
     console.log("");
     console.log(`Next: ${project.name} has no specs yet (${st.reason}) — absorb it from its code:`);
-    console.log("  " + c.cyan(`cd ${project.path} && doctrina intake --from-code`));
+    console.log("  " + c.cyan(cdThen(project.path, "doctrina intake --from-code")));
   }
 }
 
@@ -196,6 +184,23 @@ function findProject(ws, name) {
   throw Object.assign(new Error(`no project named "${name ?? ""}" in this workspace` + (guess ? ` — did you mean "${guess}"?` : "")), { exitCode: EXIT.USAGE });
 }
 
+/** Scaffold a shadow's AGENTS.md, .doctrina/ and adapter when they are not there. */
+function scaffoldShadow(wsDir, project, agent) {
+  const shadow = shadowDirOf(wsDir, project.name);
+  if (isDir(path.join(shadow, ".doctrina"))) return true;
+  mkdirp(shadow);
+  const r = spawnSync(process.execPath, [CLI_ENTRY, "init", "--non-interactive",
+    "--project-name", project.name, "--project-description", project.about || `${project.name} (absorbed into a workspace)`,
+    "--agent", agent], { cwd: shadow, encoding: "utf8", env: { ...process.env, NO_COLOR: "1" } });
+  if (r.status !== 0) {
+    console.error(c.red("error:") + ` could not scaffold the shadow at ${shadow}`);
+    console.error(r.stderr.trim());
+    return false;
+  }
+  console.log(c.green("created") + ` shadow ${relPath(wsDir, shadow)}/ (AGENTS.md, .doctrina/, ${agent} adapter)`);
+  return true;
+}
+
 function workspaceAttach(wsDir, name, flags) {
   const ws = readWorkspace(wsDir);
   const project = findProject(ws, name);
@@ -210,6 +215,20 @@ function workspaceAttach(wsDir, name, flags) {
     writeWorkspace(wsDir, ws);
     console.log(c.green("moved") + ` ${project.name} → ${repo}`);
   }
+  // --depends-on on a registered project (second audit, change 0233): the
+  // edge `delivery route` orders by could only be given at `add`, before the
+  // project it names was always registered.
+  if (flags.has("depends-on")) {
+    const dependsOn = (flagString(flags, "depends-on") ?? "").split(",").map((s) => s.trim()).filter(Boolean);
+    const unknown = dependsOn.filter((d) => d === project.name || !ws.projects.some((p) => p.name === d));
+    if (unknown.length > 0) {
+      console.error(c.red("error:") + ` --depends-on names no other registered project: ${unknown.join(", ")}`);
+      return EXIT.USAGE;
+    }
+    project.dependsOn = dependsOn;
+    writeWorkspace(wsDir, ws);
+    console.log(c.green("depends on") + ` ${project.name} → ${dependsOn.join(", ") || "nothing"}`);
+  }
   if (project.mode !== "shadow") {
     console.log(c.gray(`${project.name} is in-repo — its .doctrina/ is its own; nothing to link`));
     return EXIT.OK;
@@ -219,6 +238,14 @@ function workspaceAttach(wsDir, name, flags) {
     console.error(c.gray("hint: ") + `point it at the clone: \`doctrina workspace attach ${project.name} --path <dir>\``);
     return EXIT.PRECONDITION;
   }
+  // A shadow whose folder is gone (fourth audit, change 0235): attach
+  // crashed on ENOENT. A fresh, empty shadow is scaffolded and linked — the
+  // project is pending again, and says so; its history is the workspace's
+  // git, where a lost folder is restored from.
+  if (!isDir(path.join(shadowDirOf(wsDir, project.name), ".doctrina"))) {
+    console.log(c.yellow("warn") + ` ${project.name}'s shadow projects/${project.name}/ is gone — if the workspace's git has it, restore it (\`git checkout -- projects/${project.name}\`) before this; scaffolding an empty one`);
+    if (!scaffoldShadow(wsDir, project, flagString(flags, "agent") ?? "cursor")) return EXIT.GATE;
+  }
   attachShadow(wsDir, project);
   return EXIT.OK;
 }
@@ -263,11 +290,18 @@ function workspaceTool(wsDir, name, flags) {
     console.log(c.green("removed") + ` tool ${name}`);
     return EXIT.OK;
   }
+  // `--only` with nothing after it is not "no list": taking it for one
+  // removed the list a strict tool had, with exit 0 (change 0250).
+  if (flagGivenWithoutValue(flags, "only")) {
+    console.error(c.red("error:") + " --only needs the calls it allows, e.g. --only \"getJiraIssue,search*\" — or --only none to take the list away");
+    return EXIT.USAGE;
+  }
   let entry;
   try {
     entry = toolEntry(name, {
       server: flagString(flags, "server"), access: flagString(flags, "access"),
       for: flagString(flags, "for"), purpose: flagString(flags, "purpose"),
+      only: flags.has("only") ? flagString(flags, "only") ?? "" : undefined,
     }, at >= 0 ? ws.tools[at] : null);
   } catch (err) {
     console.error(c.red("error:") + ` ${err.message}`);
@@ -277,47 +311,20 @@ function workspaceTool(wsDir, name, flags) {
   else ws.tools.push(entry);
   writeWorkspace(wsDir, ws);
   console.log(c.green(at >= 0 ? "updated" : "declared") + ` ${entry.name} → MCP server "${entry.server}", ${entry.access === "write" ? "read/write (each write asks the human)" : "read-only"}, for ${(entry.for ?? []).join(", ") || "the planner"}`);
+  if (entry.only) console.log(c.gray(`only these calls pass through "${entry.server}": ${entry.only.join(", ")} — every other call is denied`));
   console.log(c.gray(`the server itself is configured in your agent (Cursor: .cursor/mcp.json; Claude Code: .mcp.json) under the name "${entry.server}"`));
+  // Said now, not only at the next validate (change 0235): a key that matches
+  // no configuration is a guard that never fires.
+  const servers = mcpServerNames([wsDir, ...ws.projects.map((p) => p.path)]);
+  if (servers.found && !servers.names.has(entry.server)) {
+    console.log(c.yellow("warn") + ` no MCP configuration here names a server "${entry.server}" (found: ${[...servers.names].sort().join(", ") || "none"}) — the guard only sees calls through the exact key; rerun with --server <that key>`);
+  }
   return EXIT.OK;
 }
 
 // Reads the agent's pre-call payload on stdin and answers in the agent's
 // own format. Never exits non-zero and never blocks on bad input: a broken
 // guard must not take the agent's tools away.
-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 = {};
-  }
-  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);
-  }
-  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,
-    } }));
-  }
-  return EXIT.OK;
-}
 
 function workspaceList(wsDir) {
   const ws = readWorkspace(wsDir);
@@ -340,22 +347,31 @@ function workspaceList(wsDir) {
   const pending = ws.projects.filter((p) => projectState(wsDir, p).state === "pending");
   if (pending.length > 0) {
     console.log("");
-    console.log(`Next: absorb ${pending.map((p) => p.name).join(", ")} — ` + c.cyan(`cd ${pending[0].path} && doctrina intake --from-code`));
+    console.log(`Next: absorb ${pending.map((p) => p.name).join(", ")} — ` + c.cyan(cdThen(pending[0].path, "doctrina intake --from-code")));
   }
   console.log("");
   if (ws.tools.length === 0) {
-    console.log(c.gray("no tool declared — `doctrina workspace tool jira` (presets: " + Object.keys(TOOL_PRESETS).join(", ") + ")"));
+    // Named generically (change 0228): which tools a team connects is the
+    // team's choice, and a hint that names one product reads as the default.
+    console.log(c.gray("no tool declared — `doctrina workspace tool <name> --server <mcp-server> --for <roles>` (presets: " + Object.keys(TOOL_PRESETS).join(", ") + ")"));
   } else {
     console.log(c.bold("Tools"));
     for (const t of ws.tools) {
       console.log(`  ${c.cyan(t.name.padEnd(12))} ${t.server.padEnd(12)} ${t.access.padEnd(6)} ${(t.for ?? []).join(", ").padEnd(16)} ${c.gray(t.purpose ?? "")}`);
+      if (t.only?.length) console.log(c.gray(`  ${"".padEnd(12)} only: ${t.only.join(", ")}`));
     }
   }
+  // The orchestrator files carry what changes without a workspace write — a
+  // project absorbed in its own repository turns ready, an executor model
+  // edited into workspace.json (change 0228). The hub kept saying "pending"
+  // and the subagent kept `model: inherit` until the next add or tool.
+  // Listing refreshes them; only a file whose content differs is written.
+  regenerate(wsDir);
   return EXIT.OK;
 }
 
 export const help = `
-Usage: doctrina workspace <init|add|attach|detach|list> [options]
+Usage: doctrina workspace <init|add|attach|detach|list|tool|guard> [options]
 
 The context of several repositories in one place (ADR 0029). Keep the
 workspace directory as a PRIVATE git repository: it versions the
@@ -373,35 +389,42 @@ artifacts of repositories that cannot carry .doctrina/ themselves.
       scaffolded under projects/<name>/, linked into the repository, and
       hidden from its git through .git/info/exclude.
 
-  attach <name> [--path <dir>]
+  attach <name> [--path <dir>] [--depends-on <a,b>]
       Re-create a shadow's links (after cloning the workspace on another
-      machine, or with --path after the repository moved).
+      machine, or with --path after the repository moved). --depends-on
+      replaces the projects it builds on — the order \`delivery route\` uses.
 
   detach <name>
       Remove a shadow's links and its exclude block; the shadow stays.
 
   list
       Every project with its mode, state (ready / pending / missing) and
-      open changes, then the declared tools.
+      open changes, then the declared tools; refreshes the orchestrator
+      files when a project's state or workspace.json changed since.
 
   tool <name> [--server <mcp-name>] [--access read|write] [--for <roles>]
-              [--purpose "<what for>"] [--remove]
+              [--purpose "<what for>"] [--only "<calls>"] [--remove]
       Declare (or update, or --remove) a tool the work uses. Presets:
       jira, confluence, figma, playwright, datadog, databricks, sql.
       Roles: planner, executor, qa, observer, reviewer. Access defaults
       to read: the guard refuses a write through a read-only tool and
       makes a declared write wait for the human.
+      --only "getJiraIssue,search*" lists the calls the tool may make,
+      by MCP tool name (\`*\` for any run of characters): every other
+      call through its server is denied, instead of being judged by the
+      verb in its name. --only none takes the list away.
 
   guard --hook cursor|claude
       The pre-call hook the workspace installs (Cursor beforeMCPExecution,
       Claude Code PreToolUse): reads the call on stdin and answers allow,
       deny or ask from the declared access. Never blocks on bad input.
 
-Every write (init, add, attach, detach, tool) regenerates the orchestrator
-files at the workspace root: AGENTS.md, .cursor/rules/00-doctrina-
-workspace.mdc, .cursor/hooks.json and .claude/settings.json (merged),
-.claude/agents/doctrina-*.md (read by Claude Code and Cursor) and
-<name>.code-workspace, which opens every repository in one window.
+Every write (init, add, attach, detach, tool) and every list regenerates
+the orchestrator files at the workspace root: AGENTS.md,
+.cursor/rules/00-doctrina-workspace.mdc, .cursor/hooks.json and
+.claude/settings.json (merged), .claude/agents/doctrina-*.md (read by
+Claude Code and Cursor) and <name>.code-workspace, which opens every
+repository in one window.
 
 The workspace is found from $DOCTRINA_WORKSPACE, the current directory
 or an ancestor holding ${WORKSPACE_FILE}, a shadow's .doctrina link, or

package/src/index.js

@@ -11,54 +11,54 @@ import { EXIT, exitCodeHelp } from "./lib/exit-codes.js";
 import { recordUsage, operationOf } from "./lib/usage.js";
 import { wantsJson, emitJson, captureOutput, stripAnsi, setDeprecation, deferJson, flushJson } from "./lib/json-out.js";
 
-import * as init from "./commands/init.js";
-import * as spec from "./commands/spec.js";
-import * as change from "./commands/change.js";
-import * as decision from "./commands/decision.js";
-import * as validate from "./commands/validate.js";
-import * as hooks from "./commands/hooks.js";
-import * as analyze from "./commands/analyze.js";
-import * as clarify from "./commands/clarify.js";
-import * as templates from "./commands/templates.js";
-import * as skill from "./commands/skill.js";
-import * as indexCmd from "./commands/index-rebuild.js";
-import * as next from "./commands/next.js";
-import * as metrics from "./commands/metrics.js";
-import * as context from "./commands/context.js";
-import * as search from "./commands/search.js";
-import * as intake from "./commands/intake.js";
-import * as work from "./commands/work.js";
-import * as coverage from "./commands/coverage.js";
-import * as verify from "./commands/verify.js";
-import * as contract from "./commands/contract.js";
-import * as trace from "./commands/trace.js";
-import * as status from "./commands/status.js";
-import * as close from "./commands/close.js";
-import * as review from "./commands/review.js";
-import * as watch from "./commands/watch.js";
-import * as why from "./commands/why.js";
-import * as prime from "./commands/prime.js";
-import * as handoff from "./commands/handoff.js";
-import * as show from "./commands/show.js";
-import * as doctor from "./commands/doctor.js";
-import * as report from "./commands/report.js";
-import * as completion from "./commands/completion.js";
-import * as intent from "./commands/intent.js";
-import * as upgrade from "./commands/upgrade.js";
-import * as adapter from "./commands/adapter.js";
-import * as triage from "./commands/triage.js";
-import * as ci from "./commands/ci.js";
-import * as workspace from "./commands/workspace.js";
-import * as delivery from "./commands/delivery.js";
 
+// Each command is loaded when it is the one invoked (fifth audit, change
+// 0236): the 39 static imports cost ~150 ms before any command ran, and
+// `workspace guard` runs on EVERY MCP call an agent makes — a Playwright
+// session's hundred clicks paid it a hundred times.
+/** @type {Record<string, () => Promise<any>>} */
 const COMMANDS = {
-  init, spec, change, decision, validate, hooks, analyze, clarify,
-  templates, skill, index: indexCmd, next, metrics, context, search,
-  intake, work, coverage, verify, contract, trace,
-  status, close, review, watch, why,
-  prime, handoff, show, doctor, report, completion,
-  intent, upgrade, adapter, triage, ci,
-  workspace, delivery,
+  init: () => import("./commands/init.js"),
+  spec: () => import("./commands/spec.js"),
+  change: () => import("./commands/change.js"),
+  decision: () => import("./commands/decision.js"),
+  validate: () => import("./commands/validate.js"),
+  hooks: () => import("./commands/hooks.js"),
+  analyze: () => import("./commands/analyze.js"),
+  clarify: () => import("./commands/clarify.js"),
+  templates: () => import("./commands/templates.js"),
+  skill: () => import("./commands/skill.js"),
+  index: () => import("./commands/index-rebuild.js"),
+  next: () => import("./commands/next.js"),
+  metrics: () => import("./commands/metrics.js"),
+  context: () => import("./commands/context.js"),
+  search: () => import("./commands/search.js"),
+  intake: () => import("./commands/intake.js"),
+  onboard: () => import("./commands/onboard.js"),
+  ui: () => import("./commands/ui.js"),
+  work: () => import("./commands/work.js"),
+  coverage: () => import("./commands/coverage.js"),
+  verify: () => import("./commands/verify.js"),
+  contract: () => import("./commands/contract.js"),
+  trace: () => import("./commands/trace.js"),
+  status: () => import("./commands/status.js"),
+  close: () => import("./commands/close.js"),
+  review: () => import("./commands/review.js"),
+  watch: () => import("./commands/watch.js"),
+  why: () => import("./commands/why.js"),
+  prime: () => import("./commands/prime.js"),
+  handoff: () => import("./commands/handoff.js"),
+  show: () => import("./commands/show.js"),
+  doctor: () => import("./commands/doctor.js"),
+  report: () => import("./commands/report.js"),
+  completion: () => import("./commands/completion.js"),
+  intent: () => import("./commands/intent.js"),
+  upgrade: () => import("./commands/upgrade.js"),
+  adapter: () => import("./commands/adapter.js"),
+  triage: () => import("./commands/triage.js"),
+  ci: () => import("./commands/ci.js"),
+  workspace: () => import("./commands/workspace.js"),
+  delivery: () => import("./commands/delivery.js"),
 };
 
 const TOP_HELP = `Usage: doctrina <command> [options]      (\`doctrina <command> --help\` for its flags)
@@ -71,6 +71,15 @@ ${exitCodeHelp()}
 `;
 
 async function main(argv) {
+  // The MCP guard's own door (fifth audit, change 0236): it answers before
+  // every tool call an agent makes, so it loads the guard and its registry
+  // reader only. `--help` and `--json` take the ordinary path.
+  if (argv[0] === "workspace" && argv[1] === "guard" && !argv.some((a) => /^(--help|-h|--json|--debug)$/.test(a))) {
+    const at = argv.indexOf("--hook");
+    const hook = at >= 0 ? argv[at + 1] : argv.find((a) => a.startsWith("--hook="))?.slice("--hook=".length);
+    const { runGuard } = await import("./lib/workspace-guard.js");
+    return runGuard(hook);
+  }
   // `--version` is only "print the CLI version" when NO command is given.
   // With a command it is that command's flag to consume — the old global
   // intercept made `doctrina spec set x --version 0.10.0` print the CLI
@@ -89,7 +98,8 @@ async function main(argv) {
   // Declarations now live with the command, so a new command cannot
   // reintroduce the gap by forgetting to edit this file.
   const bootstrap = parseArgs(argv, { boolean: [...GLOBAL_FLAGS.boolean] });
-  const commandModule = COMMANDS[bootstrap.positional[0]];
+  const loader = Object.hasOwn(COMMANDS, bootstrap.positional[0] ?? "") ? COMMANDS[bootstrap.positional[0]] : null;
+  const commandModule = loader ? await loader() : null;
   const spec = commandModule?.flags;
   const { positional, flags } = parseArgs(argv, {
     boolean: [...GLOBAL_FLAGS.boolean, ...(spec?.boolean ?? [])],
@@ -102,12 +112,20 @@ async function main(argv) {
   }
 
   if (positional.length === 0) {
+    // In a terminal, `doctrina` alone opens the console (change 0257): a
+    // person who typed the name and nothing else is asking where to start.
+    // A pipe, a script or an agent still gets the help it always got.
+    if (argv.length === 0 && process.stdin.isTTY && process.stdout.isTTY) {
+      const ui = await COMMANDS.ui();
+      return ui.run([], new Map());
+    }
     process.stdout.write(TOP_HELP);
     return 0;
   }
 
   const commandName = positional[0];
-  const command = COMMANDS[commandName];
+  const command = commandName === bootstrap.positional[0] ? commandModule
+    : (Object.hasOwn(COMMANDS, commandName) ? await COMMANDS[commandName]() : null);
   const removed = removalFor(positional);
   if (removed) {
     const name = removed === removalFor([commandName]) ? commandName : positional.slice(0, 2).join(" ");
@@ -207,12 +225,13 @@ async function main(argv) {
       ? command.jsonNative(positional.slice(1))
       : command.jsonNative === true;
     if (wantsJson(flags) && !jsonNative) {
-      const { code, stdout, stderr } = await captureOutput(
+      const { code, stdout, stderr, error } = await captureOutput(
         () => command.run(positional.slice(1), flags),
       );
       emitJson(operationName(positional), {
         stdout: stdout.map(stripAnsi),
         stderr: stderr.map(stripAnsi),
+        ...(error ? { error: String(error.message ?? error) } : {}),
       }, { ok: code === EXIT.OK, exitCode: code, args: operationArgs(positional) });
       return code;
     }
@@ -222,27 +241,53 @@ async function main(argv) {
     if (wantsJson(flags)) {
       deferJson();
       let code = EXIT.OK;
+      let thrown = null;
       try {
         code = (await command.run(positional.slice(1), flags)) ?? EXIT.OK;
-      } finally {
-        flushJson(code);
+      } catch (err) {
+        thrown = err;
+        code = err.exitCode ?? EXIT.GATE;
+      }
+      // A native command that failed before building its payload still
+      // answers in JSON (third audit, change 0234): "not a Doctrina project"
+      // or an unknown delivery printed English only, and a loop parsing the
+      // payload read nothing at all.
+      if (!flushJson(code)) {
+        emitJson(operationName(positional), {
+          error: thrown ? String(thrown.message) : "the command stopped before it built its payload — stderr says why",
+          ...(thrown?.remedy ? { remedy: thrown.remedy } : {}),
+        }, { ok: code === EXIT.OK, exitCode: code, args: operationArgs(positional) });
       }
+      if (thrown) await reportError(thrown, flags);
       return code;
     }
     return await command.run(positional.slice(1), flags);
   } catch (err) {
-    console.error(c.red("error:") + ` ${err.message}`);
-    if (err.remedy) {
-      console.error(c.gray("hint: ") + `run ${c.cyan(err.remedy)} first, then retry`);
-    }
-    if (flags.get("debug") && err.stack) {
-      console.error(c.gray(err.stack));
-    }
-    // A typed error carries its own class (precondition vs environment).
-    // An untyped throw is an unexpected failure of the work itself, which
-    // is the GATE class: something is wrong here, fix it and retry (C7).
-    return err.exitCode ?? EXIT.GATE;
+    return await reportError(err, flags);
+  }
+}
+
+/** The human report of a thrown error, and the exit class it carries. */
+async function reportError(err, flags) {
+  console.error(c.red("error:") + ` ${err.message}`);
+  // A clone of a shadowed repository is not a project to init (change 0234).
+  // Loaded only on this error path, like the commands (change 0236).
+  const view = /^not a Doctrina project/.test(String(err.message)) ? await import("./lib/workspace-view.js") : null;
+  const clone = view ? view.shadowedCloneAt(process.cwd()) : null;
+  if (clone) {
+    console.error(c.gray("hint: ") + (clone.same
+      ? `this repository is the workspace's shadowed "${clone.name}" and its links are missing; never \`doctrina init\` here — link them again: ${c.cyan(view?.attachCommand(clone, process.cwd()))}`
+      : `this repository is the workspace's shadowed "${clone.name}" (registered at ${clone.path}); never \`doctrina init\` here — to work from this clone, link its context from the workspace: ${c.cyan(view?.attachCommand(clone, process.cwd()))}`));
+  } else if (err.remedy) {
+    console.error(c.gray("hint: ") + `run ${c.cyan(err.remedy)} first, then retry`);
+  }
+  if (flags.get("debug") && err.stack) {
+    console.error(c.gray(err.stack));
   }
+  // A typed error carries its own class (precondition vs environment).
+  // An untyped throw is an unexpected failure of the work itself, which
+  // is the GATE class: something is wrong here, fix it and retry (C7).
+  return err.exitCode ?? EXIT.GATE;
 }
 
 // The OPERATION an invocation names, and the arguments it carries — the two

package/src/lib/actions.js

@@ -1,13 +1,17 @@
 // @ts-check
 import path from "node:path";
+import { conflictedArtifacts } from "./conflict-markers.js";
 import { readdirSync } from "node:fs";
 import { isDir, isFile, read, relPath, walk } from "./fs-ops.js";
 import * as idx from "./index-json.js";
 import { deriveIndex, indexesMatch, listHeader, specHeader } from "./scan.js";
+import { checklistProgress } from "./doc-model.js";
 import { collectRuntimeFindings } from "./runtime.js";
 import { FIX_SHAPED } from "./lexicon.js";
 import { summarize as coverageSummary } from "./coverage-model.js";
 import { summarize as traceSummary } from "./trace-model.js";
+import { projectWorkspaceLine } from "./workspace-view.js";
+import { cdThen, qarg } from "./shell.js";
 
 // What comes next, as DATA (change 0032).
 //
@@ -95,6 +99,24 @@ export function computeActions(projectRoot, gates = {}) {
   /** @type {Action[]} */
   const actions = [];
 
+  // A MERGE THAT STOPPED INSIDE AN ARTIFACT comes before everything (change
+  // 0250): every action below is computed from files that hold both halves
+  // of a conflict, and the next thing an agent does with a spec is read it.
+  try {
+    const conflicted = conflictedArtifacts(projectRoot);
+    if (conflicted.length > 0) {
+      const first = path.relative(projectRoot, conflicted[0].file).split(path.sep).join("/");
+      actions.push(action({
+        id: "merge-conflict",
+        command: "validate",
+        gate: "structure",
+        runnable: false,
+        why: `${conflicted.length} artifact${conflicted.length === 1 ? " carries" : "s carry"} git's merge conflict markers (first: ${first}:${conflicted[0].line})`,
+        text: `resolve the merge conflict in ${first} (line ${conflicted[0].line})${conflicted.length > 1 ? ` and ${conflicted.length - 1} more` : ""} — keep what both branches meant and delete the marker lines; \`doctrina validate\` names each file`,
+      }));
+    }
+  } catch { /* an unreadable tree is reported by the checks below */ }
+
   // RUNTIME FIRST (change 0029). A declared wiring that does not hold is
   // not a queue item — it is the reason the last run lied. After a job goes
   // green having executed nothing, "open a change on the observability
@@ -214,9 +236,19 @@ export function computeActions(projectRoot, gates = {}) {
         continue;
       }
       const tasksPath = path.join(changesDir, id, "tasks.md");
-      const unchecked = isFile(tasksPath)
-        ? (read(tasksPath).match(/^-\s+\[ \]/gm) ?? []).length
-        : 0;
+      const progress = isFile(tasksPath) ? checklistProgress(read(tasksPath)) : { total: 0, done: 0, open: [], placeholders: 0 };
+      const unchecked = progress.total - progress.done;
+      if (progress.placeholders > 0) {
+        // Scaffold boxes are not open work (third audit, change 0234): "complete 3
+        // open tasks" sent an agent to do work no one had written down.
+        actions.push(action({
+          id: "change-tasks-unwritten",
+          command: "work",
+          args: ["--resume", id],
+          why: `write the ${unchecked} open task${unchecked === 1 ? "" : "s"} in .doctrina/changes/${id}/tasks.md first — ${progress.placeholders === unchecked ? (unchecked === 1 ? "it is" : "all are") : `${progress.placeholders} are`} still the scaffold's placeholder${progress.placeholders === 1 ? "" : "s"}, and the delta with them`,
+        }));
+        continue;
+      }
       if (unchecked > 0) {
         // Deliberately NOT runnable, and deliberately without a command:
         // the only thing that clears this is doing the work. `change tick`
@@ -253,6 +285,33 @@ export function computeActions(projectRoot, gates = {}) {
     }
   }
 
+  // A delivery open on this repository (second audit, change 0233). `prime`
+  // named it, `next` did not: after the close of this repository's part,
+  // "Next: doctrina next" answered with this project's own chores, and the
+  // planner lost the delivery that was still going on at the workspace.
+  let inWorkspace = null;
+  try {
+    inWorkspace = projectWorkspaceLine(projectRoot);
+  } catch {
+    inWorkspace = null;
+  }
+  for (const d of inWorkspace?.deliveries ?? []) {
+    if (d.changes.length === 0) {
+      actions.push(action({
+        id: "delivery-change-missing",
+        why: `delivery ${d.id} is routed to this repository and has no change here yet`,
+        text: `doctrina work ${qarg(d.title)} --delivery ${d.id} — delivery ${d.id} is routed to this repository and has no change here yet`,
+      }));
+    } else if (d.open === 0) {
+      actions.push(action({
+        id: "delivery-continues-at-workspace",
+        severity: "advisory",
+        why: `this repository's part of delivery ${d.id} is closed; the delivery goes on at the workspace`,
+        text: `${cdThen(inWorkspace?.dir ?? "", "doctrina next")} — this repository's part of delivery ${d.id} is closed; the delivery goes on at the workspace`,
+      }));
+    }
+  }
+
   // ADRs stuck in proposed need a human decision; accepted-but-bare ADRs are
   // the rot the review flagged — a decision with nothing behind it (no Evidence,
   // no Landed) is drift waiting to be superseded. Surface the proposed ones