doctrina-cli 0.17.0 → 0.20.0

package/src/commands/work.js

@@ -8,13 +8,16 @@ import * as idx from "../lib/index-json.js";
 import { c } from "../lib/colors.js";
 import { assessBrief } from "../lib/clarity.js";
 import { locateTemplatesDir, substitute } from "../lib/templates.js";
+import { findWorkspace, projectAt, readWorkspace } from "../lib/workspace.js";
+import { readDelivery, resolveDeliveryId } from "../lib/delivery.js";
 import { EXIT, notADoctrinaProject } from "../lib/exit-codes.js";
-import { changeNew, reindexChange } from "../lib/change-ops.js";
+import { changeNew, reindexChange, addAffectedSpec } from "../lib/change-ops.js";
 import { classify } from "../lib/triage-model.js";
 import { printPlaybookTemplate } from "../lib/playbook.js";
+import { specShape } from "../lib/spec-ops.js";
 import { changedFiles } from "../lib/git.js";
 import { slugFromPrompt, fold, CONFIDENT_MARGIN } from "../lib/lexicon.js";
-import { rankCapabilities, rankCapabilitiesByDiff } from "../lib/work-model.js";
+import { rankCapabilities, rankCapabilitiesByDiff, similarChanges, SIMILAR_CHANGE_DAYS } from "../lib/work-model.js";
 import { isChangeId, refuseChangeRef } from "../lib/project.js";
 export { rankCapabilities, rankCapabilitiesByDiff } from "../lib/work-model.js";
 
@@ -29,14 +32,50 @@ export { rankCapabilities, rankCapabilitiesByDiff } from "../lib/work-model.js";
 // Flags this command accepts. Declared HERE, with the command, so
 // adding a command never requires editing the entrypoint — the gap that
 // let six flags ship undeclared and silently swallow a positional (C3).
-export const flags = { boolean: ["json", "chore", "design", "force", "from-diff", "no-spec", "quiet"], string: ["capability", "id", "resume", "title"] };
+export const flags = { boolean: ["json", "chore", "design", "force", "from-diff", "no-spec", "quiet"], string: ["capability", "consolidate", "delivery", "id", "resume", "title"] };
 
 export async function run(positional, flags) {
-  const prompt = positional.join(" ").trim();
   const projectRoot = process.cwd();
   if (!exists(path.join(projectRoot, ".doctrina"))) {
     throw notADoctrinaProject();
   }
+  // --consolidate <cap> (change 0206): a spec only ever grew — every change
+  // appended, nothing took a requirement out — and a field review of 0.17
+  // asked for "a command to consolidate a spec from time to time". It is an
+  // ordinary change pinned to the capability, with its own playbook: the
+  // agent decides what is redundant or superseded (ADR 0005), and the ops
+  // take it out.
+  const consolidate = flags.has("consolidate") ? flagString(flags, "consolidate") : null;
+  if (consolidate !== null) {
+    if (!consolidate || /** @type {unknown} */ (consolidate) === true || !/^[a-z][a-z0-9-]*$/.test(consolidate)) {
+      console.error(c.red("error:") + " --consolidate needs the capability whose spec to consolidate");
+      return EXIT.USAGE;
+    }
+    if (!isFile(path.join(projectRoot, ".doctrina", "specs", consolidate, "spec.md"))) {
+      console.error(c.red("error:") + ` capability "${consolidate}" has no spec at .doctrina/specs/${consolidate}/spec.md`);
+      return EXIT.USAGE;
+    }
+    flags.set("capability", consolidate);
+    flags.set("force", true);
+    if (!flags.has("title")) flags.set("title", `consolidate ${consolidate}`);
+  }
+  const prompt = consolidate
+    ? `Consolidate the ${consolidate} spec: merge requirements and criteria that say the same thing, drop what a later one superseded — no behaviour changes.`
+    : positional.join(" ").trim();
+
+  // --delivery <id> (change 0222): the change is this repository's part of a
+  // workspace delivery. Checked BEFORE anything is scaffolded, so a typo or a
+  // repository the delivery was never routed to opens nothing.
+  let delivery = null;
+  if (flags.has("delivery")) {
+    const resolved = resolveDeliveryFor(projectRoot, flagString(flags, "delivery"));
+    if (resolved.error) {
+      console.error(c.red("error:") + ` ${resolved.error}`);
+      if (resolved.hint) console.error(c.gray("hint: ") + resolved.hint);
+      return resolved.code;
+    }
+    delivery = resolved.id;
+  }
 
   // --resume <id>: reprint the playbook for an existing open change rather than
   // open a new one (review G1 — `work "continue"` used to slug the word and
@@ -78,6 +117,29 @@ export async function run(positional, flags) {
     }
   }
 
+  // DUPLICATE CHECK (change 0215). A request that mostly repeats a change
+  // already open, or archived in the last two weeks, is held before a second
+  // copy is scaffolded: an archived change is out of every default read, and
+  // a field review found the person asking for "the doctrina work" of work
+  // already closed. A term match can be wrong, so --force proceeds.
+  if (!fromDiff && !consolidate && prompt && !flagBool(flags, "force", false)) {
+    const similar = similarChanges(projectRoot, prompt);
+    if (similar.length > 0) {
+      console.error(c.yellow("hold:") + " this request reads like a change that already exists:");
+      for (const s of similar.slice(0, 3)) {
+        console.error(`  ${c.cyan(s.id)}  ${s.title}` + c.gray(` — ${s.where} (${s.path}); shared: ${s.shared.join(", ")}`));
+      }
+      console.error("");
+      const top = similar[0];
+      console.error(top.where === "archived"
+        ? `If it is the same work, it is done: tell the human it is archived at ${top.path}.`
+        : `If it is the same work, continue it: ${c.cyan(`doctrina work --resume ${top.id}`)}`);
+      console.error(c.gray("If it is new work, open it anyway: ") + c.cyan(`doctrina work --force "<request>"`) +
+        c.gray(` (open changes and the last ${SIMILAR_CHANGE_DAYS} days of the archive are compared)`));
+      return EXIT.PRECONDITION;
+    }
+  }
+
   // LANE CHECK (change 0029). `work` was the default answer to every
   // request, so a broken workflow or a suite that ran nothing became a
   // change with a proposal, tasks and a spec delta — ceremony spent on a
@@ -172,6 +234,9 @@ export async function run(positional, flags) {
     if (pinned) {
       updated = updated.replace(/^(-\s+\*\*Affects specs:\*\*).*$/m, `$1 ${pinned}`);
     }
+    if (delivery) {
+      updated = updated.replace(/^(-[ \t]+\*\*Lane:\*\*[^\r\n]*)/m, `$1\n- **Delivery:** ${delivery}`);
+    }
     if (updated !== txt) write(proposalPath, updated, { force: true });
   }
 
@@ -205,6 +270,12 @@ export async function run(positional, flags) {
     ? null
     : scaffoldDelta(projectRoot, { id, capability, guess, runnerUp: promptMatches[1] ?? null });
 
+  // A guessed delta names the capability as surely as a pinned one: the
+  // header says what the folder says (change 0207). It stayed empty for
+  // every unpinned `work`, so the proposal claimed no spec while its delta
+  // targeted one.
+  if (scaffolded) addAffectedSpec(projectRoot, id, scaffolded.capability);
+
   // The proposal is written in two passes — `changeNew` scaffolds it, the
   // lines above stamp the lane and the pinned specs — so its index entry is
   // re-derived HERE, from the finished file. Indexing at the end of the first
@@ -223,7 +294,9 @@ export async function run(positional, flags) {
   }
 
   console.log("");
-  if (chore) {
+  if (consolidate) {
+    printConsolidatePlaybook(projectRoot, { id, capability: consolidate });
+  } else if (chore) {
     printChorePlaybook(projectRoot, { id, prompt: effPrompt });
   } else {
     printPlaybook(projectRoot, {
@@ -231,6 +304,12 @@ export async function run(positional, flags) {
       fromDiff, diffMatches: fromDiff ? [] : diffMatches,
     });
   }
+  // The sentence the human needs (change 0214). A field review: the change
+  // existed only in the terminal, so the person asking saw code appear with
+  // no Doctrina trace — and later asked for "the doctrina work" of work
+  // already closed. The agent repeats this line; the CLI writes it.
+  console.log("");
+  console.log(c.bold("Tell the human: ") + `opened change ${id} — "${title}" (.doctrina/changes/${id}/)`);
   return 0;
 }
 
@@ -301,6 +380,28 @@ function laneRecord(verdict, { forced, chore, fromDiff }) {
   return line;
 }
 
+// The delivery a `--delivery` names, from this repository's workspace: it
+// must exist, and this repository must be one of the projects it was routed to.
+function resolveDeliveryFor(projectRoot, ref) {
+  const found = findWorkspace(projectRoot);
+  if (!found) {
+    return { error: "--delivery needs a workspace, and this repository belongs to none", hint: "register it: `doctrina workspace add <path>` from the workspace", code: EXIT.PRECONDITION };
+  }
+  const id = resolveDeliveryId(found.dir, ref);
+  if (!id) return { error: `no delivery "${ref ?? ""}" in the workspace at ${found.dir}`, hint: "`doctrina delivery list` from the workspace", code: EXIT.USAGE };
+  const ws = readWorkspace(found.dir);
+  const project = projectAt(ws, projectRoot);
+  const d = readDelivery(found.dir, id);
+  if (!project || !d.projects.includes(project.name)) {
+    return {
+      error: `delivery ${id} is not routed to ${project ? project.name : "this repository"} (routed: ${d.projects.join(", ") || "none"})`,
+      hint: `route it first, from the workspace: \`doctrina delivery route ${id} ${[...d.projects, project?.name ?? "<name>"].join(",")}\``,
+      code: EXIT.PRECONDITION,
+    };
+  }
+  return { id };
+}
+
 function writeLane(projectRoot, id, verdict, opts) {
   const line = laneRecord(verdict, opts);
   if (!line) return;
@@ -440,6 +541,21 @@ export function slugify(text) {
 // part that is not prose: computing the variable blocks. Each is PRE-RENDERED
 // into a token, so `substitute` stays a plain string map and the template
 // stays a document rather than a language with conditionals in it.
+// The consolidation playbook: the spec's shape, measured, then the steps.
+// Measuring is the CLI's part; deciding which requirement is redundant is
+// the agent's (ADR 0005).
+function printConsolidatePlaybook(projectRoot, { id, capability }) {
+  const text = read(path.join(projectRoot, ".doctrina", "specs", capability, "spec.md"));
+  const shape = specShape(text);
+  const sections = Object.entries(shape.sections).map(([k, n]) => `${k} ${n}`).join(" · ");
+  printPlaybookTemplate(projectRoot, "consolidate", {
+    CHANGE_ID: id,
+    CAPABILITY: capability,
+    SHAPE: `${shape.lines} lines · ${shape.requirements} requirements (${sections || "none"}) · ` +
+      `${shape.criteria} acceptance criteria`,
+  });
+}
+
 function printChorePlaybook(projectRoot, { id, prompt }) {
   printPlaybookTemplate(projectRoot, "chore", { CHANGE_ID: id, PROMPT: prompt });
 }
@@ -450,6 +566,9 @@ function printPlaybook(projectRoot, { id, prompt, pinned, matches, capability, c
     CHANGE_ID: id,
     PROMPT: prompt,
     CAPABILITY: capability ?? "<capability>",
+    // The read pack already cut to the task (change 0217): `--for` is what
+    // slices the spec, and an agent copying a step should copy the cut.
+    FOR: forQuery(prompt),
     FROM_DIFF_NOTE: fromDiff
       ? c.gray("Code-first: write the spec that describes what the working tree already does.")
       : "",
@@ -488,6 +607,13 @@ function printPlaybook(projectRoot, { id, prompt, pinned, matches, capability, c
   });
 }
 
+// The prompt as a `context --for` argument: one line, no double quotes, short
+// enough to read — the slicer only needs its content words.
+export function forQuery(prompt) {
+  const flat = String(prompt ?? "").replace(/["`]/g, "").replace(/\s+/g, " ").trim();
+  return flat.length > 80 ? flat.slice(0, 80).replace(/\s+\S*$/, "") : flat;
+}
+
 // Which capability the change is about, as far as the CLI can tell: pinned by
 // the operator, ranked by term overlap, or nothing — a hint in every case,
 // never a decision (ADR 0005).
@@ -543,6 +669,10 @@ Options:
   --resume <id>        Reprint the playbook for an open change; create nothing
   --from-diff          Backfill: scaffold from the working-tree changes (no
                        prompt needed) and print a code-first playbook (F8)
+  --consolidate <cap>  Open a change that consolidates <cap>'s spec — merge
+                       what says the same thing, remove what was superseded
+                       (remove-requirement / remove-criterion) — with its own
+                       playbook; no prompt needed, no behaviour changes
   --chore, --no-spec   Open a spec-less chore change (infra/docs/build) with a
                        playbook that skips the spec-delta steps (F9)
   --design             Also scaffold design.md, for a change with non-trivial
@@ -551,6 +681,10 @@ Options:
                        existing change folder, and proceed past the lane hold
                        below
 
+A request that mostly repeats a change already open, or archived in the
+last 14 days, is HELD the same way (exit 3), naming it: the same work is
+resumed, or reported as done where it is archived; --force opens it anyway.
+
 A prompt that reads as a RUNTIME problem — a workflow, an env value, a run
 that executed nothing — is HELD before anything is scaffolded, and pointed
 at \`doctrina triage\` instead (exit 3: a precondition, not a bad prompt).

package/src/commands/workspace.js

@@ -0,0 +1,409 @@
+// @ts-check
+import path from "node:path";
+import process from "node:process";
+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 { c } from "../lib/colors.js";
+import { suggest } from "../lib/suggest.js";
+import { EXIT, PreconditionError } from "../lib/exit-codes.js";
+import {
+  PROJECT_MODES, PROJECT_NAME, WORKSPACE_FILE, applyLinks, blankWorkspace, excludeEntries,
+  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 { writeOrchestratorFiles } from "../lib/workspace-agents.js";
+
+// `doctrina workspace` — the context of several repositories in one place
+// (ADR 0029). The decisions live in lib/workspace.js; this module renders
+// them and runs the one child process it needs (`init` inside a shadow).
+
+const SUBCOMMANDS = ["init", "add", "attach", "detach", "list", "tool", "guard"];
+const CLI_ENTRY = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "index.js");
+
+export const flags = {
+  boolean: ["json", "no-git", "remove"],
+  string: ["name", "mode", "role", "about", "depends-on", "agent", "path", "server", "access", "for", "purpose", "hook"],
+};
+
+export async function run(positional, flags) {
+  const sub = positional[0];
+  if (!SUBCOMMANDS.includes(sub)) {
+    console.error(c.red("error:") + ` unknown workspace subcommand "${sub ?? ""}"`);
+    const guess = suggest(sub, SUBCOMMANDS);
+    console.error(c.gray("hint: ") + (guess ? `did you mean \`doctrina workspace ${guess}\`?` : `available: ${SUBCOMMANDS.join(", ")}`));
+    return EXIT.USAGE;
+  }
+  if (sub === "init") return workspaceInit(positional[1], flags);
+  const found = findWorkspace(process.cwd());
+  // The guard answers an agent's pre-call hook, so it never fails the call
+  // for want of a workspace: no workspace, no opinion.
+  if (sub === "guard") return workspaceGuard(found?.dir ?? null, flagString(flags, "hook"));
+  if (!found) {
+    throw new PreconditionError(
+      "no workspace here (no workspace.json in this directory or above, and $DOCTRINA_WORKSPACE is unset)",
+      "doctrina workspace init <dir>",
+    );
+  }
+  let code;
+  if (sub === "add") code = workspaceAdd(found.dir, positional[1], flags);
+  else if (sub === "attach") code = workspaceAttach(found.dir, positional[1], flags);
+  else if (sub === "detach") code = workspaceDetach(found.dir, positional[1]);
+  else if (sub === "tool") code = workspaceTool(found.dir, positional[1], flags);
+  else return workspaceList(found.dir);
+  if (code === EXIT.OK) regenerate(found.dir);
+  return code;
+}
+
+function workspaceInit(dirArg, flags) {
+  const dir = path.resolve(process.cwd(), dirArg ?? ".");
+  if (isWorkspaceDir(dir)) {
+    console.error(c.red("error:") + ` ${dir} is already a workspace`);
+    console.error(c.gray("hint: ") + "add a project to it: `doctrina workspace add <path>`");
+    return EXIT.PRECONDITION;
+  }
+  const name = flagString(flags, "name") ?? path.basename(dir);
+  mkdirp(path.join(dir, "projects"));
+  mkdirp(path.join(dir, "deliveries"));
+  writeWorkspace(dir, blankWorkspace(name));
+  if (!exists(path.join(dir, ".gitignore"))) {
+    write(path.join(dir, ".gitignore"), "node_modules/\n.env\n.env.*\n*.log\n");
+  }
+  for (const keep of ["projects", "deliveries"]) {
+    if (!exists(path.join(dir, keep, ".gitkeep"))) write(path.join(dir, keep, ".gitkeep"), "");
+  }
+  console.log(c.green("created") + ` workspace "${name}" at ${dir}`);
+  if (!flags.get("no-git") && !exists(path.join(dir, ".git"))) {
+    console.log(gitInit(dir)
+      ? c.green("created") + " a git repository for it — keep it private: it versions the context of repositories that cannot carry their own"
+      : c.yellow("warn:") + " git is not available; the workspace is not versioned yet (`git init` it yourself)");
+  }
+  writePointer(dir);
+  regenerate(dir);
+  console.log("");
+  console.log("Next: register each repository the work touches —");
+  console.log("  " + c.cyan("doctrina workspace add <path> --role front|back|app|qa --about \"<what it is>\""));
+  console.log(c.gray("  A repository with its own .doctrina/ is registered in-repo; one without is shadowed: its"));
+  console.log(c.gray("  artifacts live here and are linked into it, invisible to its git."));
+  return EXIT.OK;
+}
+
+function workspaceAdd(wsDir, pathArg, flags) {
+  if (!pathArg) {
+    console.error(c.red("error:") + " workspace add needs the repository's path");
+    console.error(c.gray("hint: ") + "doctrina workspace add ../front-core --role front --about \"design system and shell\"");
+    return EXIT.USAGE;
+  }
+  const repo = path.resolve(process.cwd(), pathArg);
+  if (!isDir(repo)) {
+    console.error(c.red("error:") + ` not a directory: ${pathArg}`);
+    return EXIT.PRECONDITION;
+  }
+  const ws = readWorkspace(wsDir);
+  const name = flagString(flags, "name") ?? path.basename(repo).toLowerCase();
+  if (!PROJECT_NAME.test(name)) {
+    console.error(c.red("error:") + ` project name "${name}" must match ${PROJECT_NAME} — pass --name`);
+    return EXIT.USAGE;
+  }
+  if (ws.projects.some((p) => p.name === name)) {
+    console.error(c.red("error:") + ` a project named "${name}" is already registered`);
+    console.error(c.gray("hint: ") + `relink it with \`doctrina workspace attach ${name}\`, or pass another --name`);
+    return EXIT.PRECONDITION;
+  }
+  const already = projectAt(ws, repo);
+  if (already) {
+    console.error(c.red("error:") + ` ${repo} is already registered as "${already.name}"`);
+    return EXIT.PRECONDITION;
+  }
+  const hasOwn = isDir(path.join(repo, ".doctrina"));
+  const mode = flagString(flags, "mode") ?? (hasOwn ? "in-repo" : "shadow");
+  if (!PROJECT_MODES.includes(mode)) {
+    console.error(c.red("error:") + ` --mode must be one of ${PROJECT_MODES.join(", ")} (got "${mode}")`);
+    return EXIT.USAGE;
+  }
+  if (mode === "shadow" && hasOwn) {
+    console.error(c.red("error:") + " this repository already carries its own .doctrina/ — register it in-repo");
+    return EXIT.PRECONDITION;
+  }
+  const dependsOn = (flagString(flags, "depends-on") ?? "").split(",").map((s) => s.trim()).filter(Boolean);
+  const unknown = dependsOn.filter((d) => !ws.projects.some((p) => p.name === d));
+  if (unknown.length > 0) {
+    console.error(c.red("error:") + ` --depends-on names no registered project: ${unknown.join(", ")}`);
+    return EXIT.USAGE;
+  }
+  const project = {
+    name, path: repo, mode,
+    role: flagString(flags, "role") ?? "",
+    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)`);
+    }
+  }
+  ws.projects.push(project);
+  writeWorkspace(wsDir, ws);
+  console.log(c.green("registered") + ` ${name} (${mode}) → ${repo}`);
+  if (mode === "shadow") attachShadow(wsDir, project);
+  printProjectNext(wsDir, project);
+  return EXIT.OK;
+}
+
+function attachShadow(wsDir, project) {
+  const shadow = shadowDirOf(wsDir, project.name);
+  const plan = linkPlan(shadow, project.path);
+  const done = applyLinks(plan, shadow, project.path);
+  for (const d of done) {
+    console.log(c.green(d.how.padEnd(11)) + ` ${d.rel}` + (d.how === "copied" ? c.yellow("  (a copy: rerun attach after the shadow changes)") : ""));
+  }
+  for (const e of plan.filter((p) => p.action === "conflict")) {
+    console.log(c.yellow("kept       ") + ` ${e.rel} — the repository already has its own; the shadow's copy is not linked`);
+  }
+  const excludeFile = writeExclude(project.path, excludeEntries(plan, project.path));
+  console.log(excludeFile
+    ? c.gray(`hidden from the repository's git by ${relPath(project.path, excludeFile)} (never committed)`)
+    : c.yellow("warn:") + " not a git repository — nothing hides the links from version control");
+}
+
+function printProjectNext(wsDir, project) {
+  const st = projectState(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`));
+  }
+}
+
+function findProject(ws, name) {
+  const project = ws.projects.find((p) => p.name === name);
+  if (project) return project;
+  const guess = suggest(name ?? "", ws.projects.map((p) => p.name));
+  throw Object.assign(new Error(`no project named "${name ?? ""}" in this workspace` + (guess ? ` — did you mean "${guess}"?` : "")), { exitCode: EXIT.USAGE });
+}
+
+function workspaceAttach(wsDir, name, flags) {
+  const ws = readWorkspace(wsDir);
+  const project = findProject(ws, name);
+  const newPath = flagString(flags, "path");
+  if (newPath) {
+    const repo = path.resolve(process.cwd(), newPath);
+    if (!isDir(repo)) {
+      console.error(c.red("error:") + ` not a directory: ${newPath}`);
+      return EXIT.PRECONDITION;
+    }
+    project.path = repo;
+    writeWorkspace(wsDir, ws);
+    console.log(c.green("moved") + ` ${project.name} → ${repo}`);
+  }
+  if (project.mode !== "shadow") {
+    console.log(c.gray(`${project.name} is in-repo — its .doctrina/ is its own; nothing to link`));
+    return EXIT.OK;
+  }
+  if (!isDir(project.path)) {
+    console.error(c.red("error:") + ` ${project.name}'s repository is not at ${project.path}`);
+    console.error(c.gray("hint: ") + `point it at the clone: \`doctrina workspace attach ${project.name} --path <dir>\``);
+    return EXIT.PRECONDITION;
+  }
+  attachShadow(wsDir, project);
+  return EXIT.OK;
+}
+
+function workspaceDetach(wsDir, name) {
+  const ws = readWorkspace(wsDir);
+  const project = findProject(ws, name);
+  if (project.mode !== "shadow") {
+    console.log(c.gray(`${project.name} is in-repo — nothing was linked`));
+    return EXIT.OK;
+  }
+  const removed = isDir(project.path) ? removeLinks(shadowDirOf(wsDir, project.name), project.path) : [];
+  for (const r of removed) console.log(c.green("unlinked") + ` ${r}`);
+  if (isDir(project.path)) writeExclude(project.path, []);
+  console.log(c.gray(`the shadow stays in ${relPath(wsDir, shadowDirOf(wsDir, project.name))}/ — \`doctrina workspace attach ${project.name}\` links it again`));
+  return EXIT.OK;
+}
+
+// The orchestrator's files follow the registry on every write (change 0223).
+function regenerate(wsDir) {
+  const ws = readWorkspace(wsDir);
+  const states = new Map(ws.projects.map((p) => [p.name, projectState(wsDir, p).state]));
+  const written = writeOrchestratorFiles(ws, wsDir, states);
+  if (written.length > 0) console.log(c.gray(`orchestrator files: ${written.join(", ")}`));
+}
+
+function workspaceTool(wsDir, name, flags) {
+  if (!name) {
+    console.error(c.red("error:") + " workspace tool needs the tool's name");
+    console.error(c.gray("hint: ") + `presets: ${Object.keys(TOOL_PRESETS).join(", ")} — or --server <name in your agent's MCP config>`);
+    return EXIT.USAGE;
+  }
+  const ws = readWorkspace(wsDir);
+  const at = ws.tools.findIndex((t) => t.name === name);
+  if (flags.get("remove")) {
+    if (at < 0) {
+      console.error(c.red("error:") + ` no tool named "${name}"`);
+      return EXIT.USAGE;
+    }
+    ws.tools.splice(at, 1);
+    writeWorkspace(wsDir, ws);
+    console.log(c.green("removed") + ` tool ${name}`);
+    return EXIT.OK;
+  }
+  let entry;
+  try {
+    entry = toolEntry(name, {
+      server: flagString(flags, "server"), access: flagString(flags, "access"),
+      for: flagString(flags, "for"), purpose: flagString(flags, "purpose"),
+    }, at >= 0 ? ws.tools[at] : null);
+  } catch (err) {
+    console.error(c.red("error:") + ` ${err.message}`);
+    return EXIT.USAGE;
+  }
+  if (at >= 0) ws.tools[at] = entry;
+  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"}`);
+  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}"`));
+  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);
+  console.log(c.bold(`Workspace "${ws.name}"`) + c.gray(` — ${wsDir}`));
+  if (ws.projects.length === 0) {
+    console.log("");
+    console.log(c.gray("no project yet — `doctrina workspace add <path>`"));
+    return EXIT.OK;
+  }
+  console.log("");
+  for (const p of ws.projects) {
+    const st = projectState(wsDir, p);
+    const colour = st.state === "ready" ? c.green : st.state === "pending" ? c.yellow : c.red;
+    const open = st.open.length ? `, ${st.open.length} open change${st.open.length === 1 ? "" : "s"}` : "";
+    console.log(`  ${c.cyan(p.name.padEnd(16))} ${p.mode.padEnd(8)} ${colour(st.state.padEnd(8))} ${st.reason}${open}`);
+    const meta = [p.role && `role ${p.role}`, p.dependsOn?.length && `depends on ${p.dependsOn.join(", ")}`].filter(Boolean).join(" · ");
+    console.log(c.gray(`  ${"".padEnd(16)} ${p.path}${meta ? " · " + meta : ""}`));
+    if (p.about) console.log(c.gray(`  ${"".padEnd(16)} ${p.about}`));
+  }
+  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("");
+  if (ws.tools.length === 0) {
+    console.log(c.gray("no tool declared — `doctrina workspace tool jira` (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 ?? "")}`);
+    }
+  }
+  return EXIT.OK;
+}
+
+export const help = `
+Usage: doctrina workspace <init|add|attach|detach|list> [options]
+
+The context of several repositories in one place (ADR 0029). Keep the
+workspace directory as a PRIVATE git repository: it versions the
+artifacts of repositories that cannot carry .doctrina/ themselves.
+
+  init [<dir>] [--name <n>] [--no-git]
+      Create the workspace (workspace.json, projects/, deliveries/) and
+      \`git init\` it. Records it in $DOCTRINA_HOME (default ~/.doctrina)
+      so an in-repo project can find it.
+
+  add <path> [--name <n>] [--mode in-repo|shadow] [--role <r>]
+             [--about "<what it is>"] [--depends-on <a,b>] [--agent cursor]
+      Register a repository. One with its own .doctrina/ is in-repo. One
+      without is a SHADOW: its AGENTS.md, .doctrina/ and agent adapter are
+      scaffolded under projects/<name>/, linked into the repository, and
+      hidden from its git through .git/info/exclude.
+
+  attach <name> [--path <dir>]
+      Re-create a shadow's links (after cloning the workspace on another
+      machine, or with --path after the repository moved).
+
+  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.
+
+  tool <name> [--server <mcp-name>] [--access read|write] [--for <roles>]
+              [--purpose "<what for>"] [--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.
+
+  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.
+
+The workspace is found from $DOCTRINA_WORKSPACE, the current directory
+or an ancestor holding ${WORKSPACE_FILE}, a shadow's .doctrina link, or
+the pointer \`init\` wrote.
+`;