doctrina-cli 0.20.0 → 0.21.0

package/src/commands/delivery.js

@@ -1,25 +1,30 @@
 // @ts-check
 import process from "node:process";
-import { relPath, write } from "../lib/fs-ops.js";
-import { flagString } from "../lib/args.js";
+import { eolOf, read, relPath, withEol, write } from "../lib/fs-ops.js";
+import { flagBool, flagString } from "../lib/args.js";
 import { c } from "../lib/colors.js";
+import { emitJson } from "../lib/json-out.js";
 import { suggest } from "../lib/suggest.js";
 import { today } from "../lib/dates.js";
 import { EXIT, PreconditionError } from "../lib/exit-codes.js";
 import { readTemplate, substitute } from "../lib/templates.js";
 import { renderPlaybook } from "../lib/playbook.js";
-import { findWorkspace, readWorkspace } from "../lib/workspace.js";
+import { absorbCommand, findWorkspace, readWorkspace } from "../lib/workspace.js";
 import {
   deliveryBlockers, deliveryChanges, deliveryPath, dependencyOrder, listDeliveries, nextDeliveryId,
   rankProjects, readDelivery, resolveDeliveryId, setDeliveryHeader, daysBetween, recordBlockers,
+  releaseBoxes, tickRelease, unroutable, otherWriters,
 } from "../lib/delivery.js";
+import { cdThen, qarg } from "../lib/shell.js";
 
 // `doctrina delivery` — one item of work across repositories (ADR 0030).
 // Decisions in lib/delivery.js; this module renders them.
 
-const SUBCOMMANDS = ["new", "route", "list", "status", "check", "close"];
+const SUBCOMMANDS = ["new", "route", "list", "status", "tick", "check", "close"];
 
-export const flags = { boolean: ["json"], string: ["ref", "projects", "date"] };
+export const flags = { boolean: ["json", "all", "force"], string: ["ref", "projects", "date"] };
+// `delivery status` builds its own payload (change 0234); the rest answer in the envelope.
+export const jsonNative = (/** @type {string[]} */ args) => args[0] === "status";
 
 export async function run(positional, flags) {
   const sub = positional[0];
@@ -43,8 +48,9 @@ export async function run(positional, flags) {
     console.error(c.gray("hint: ") + "`doctrina delivery list` shows them");
     return EXIT.USAGE;
   }
-  if (sub === "route") return deliveryRoute(wsDir, ws, id, positional[2] ?? flagString(flags, "projects"));
-  if (sub === "status") return deliveryStatus(wsDir, ws, id);
+  if (sub === "route") return deliveryRoute(wsDir, ws, id, positional[2] ?? flagString(flags, "projects"), flags);
+  if (sub === "tick") return deliveryTick(wsDir, id, positional.slice(2), flags);
+  if (sub === "status") return deliveryStatus(wsDir, ws, id, flagBool(flags, "json", false));
   if (sub === "check") return deliveryCheck(wsDir, ws, id);
   return deliveryClose(wsDir, ws, id, flags);
 }
@@ -55,6 +61,20 @@ function parseProjects(ws, raw) {
   return { names, unknown };
 }
 
+// A project with no spec, or whose repository is gone, cannot take a change
+// for the delivery yet (change 0226). Refused unless --force, naming the fix.
+function refuseUnroutable(wsDir, ws, names, flags) {
+  const blocked = unroutable(wsDir, ws, names);
+  if (blocked.length === 0 || flagBool(flags, "force", false)) return false;
+  for (const b of blocked) {
+    console.error(c.red("error:") + ` ${b.name} is ${b.state} (${b.reason}) — a change there would have no spec to change`);
+    console.error(c.gray("hint: ") + (b.state === "missing"
+      ? `point the workspace at the clone: \`doctrina workspace attach ${b.name} --path <dir>\``
+      : `absorb it first: \`${absorbCommand(b, b.reason)}\` — or route anyway with --force`));
+  }
+  return true;
+}
+
 function deliveryNew(wsDir, ws, title, flags) {
   if (!title) {
     console.error(c.red("error:") + " delivery new needs a title");
@@ -69,6 +89,7 @@ function deliveryNew(wsDir, ws, title, flags) {
     console.error(c.red("error:") + ` --projects names no registered project: ${unknown.join(", ")}`);
     return EXIT.USAGE;
   }
+  if (refuseUnroutable(wsDir, ws, names, flags)) return EXIT.PRECONDITION;
   const id = nextDeliveryId(wsDir, title);
   const ref = flagString(flags, "ref") ?? "—";
   const ordered = dependencyOrder(ws, names);
@@ -95,6 +116,7 @@ function playbookTokens(wsDir, ws, delivery) {
   return {
     DELIVERY_ID: delivery.id,
     DELIVERY_TITLE: delivery.title,
+    DELIVERY_TITLE_ARG: qarg(delivery.title),
     DELIVERY_REF: delivery.ref === "—" ? "(no --ref given: ask the human which item this is)" : delivery.ref,
     DELIVERY_FILE: relPath(wsDir, deliveryPath(wsDir, delivery.id)),
     ROUTING: routing,
@@ -103,7 +125,7 @@ function playbookTokens(wsDir, ws, delivery) {
   };
 }
 
-function deliveryRoute(wsDir, ws, id, raw) {
+function deliveryRoute(wsDir, ws, id, raw, flags) {
   const { names, unknown } = parseProjects(ws, raw);
   if (names.length === 0) {
     console.error(c.red("error:") + " delivery route needs the projects, comma-separated");
@@ -114,15 +136,35 @@ function deliveryRoute(wsDir, ws, id, raw) {
     console.error(c.red("error:") + ` no registered project named ${unknown.join(", ")}`);
     return EXIT.USAGE;
   }
+  if (refuseUnroutable(wsDir, ws, names, flags)) return EXIT.PRECONDITION;
+  // Routing a project OUT while it carries an open change for the delivery
+  // (third audit, change 0234) orphaned the change: it kept its Delivery
+  // header, the delivery stopped seeing it, and the delivery could close
+  // around work still in flight.
+  const before = readDelivery(wsDir, id);
+  const dropped = before.projects.filter((n) => !names.includes(n));
+  const carrying = deliveryChanges(wsDir, ws, { ...before, projects: dropped })
+    .flatMap((row) => row.changes.filter((ch) => !ch.archived).map((ch) => ({ project: row.project, id: ch.id })));
+  if (carrying.length > 0 && !flagBool(flags, "force", false)) {
+    for (const x of carrying) {
+      console.error(c.red("error:") + ` ${x.project} carries ${x.id} for ${id} — routing it out would orphan the change`);
+    }
+    console.error(c.gray("hint: ") + `close or abandon it there first (\`doctrina change abandon <id> --reason "<why>" --force\`), or pass --force to route it out anyway`);
+    return EXIT.PRECONDITION;
+  }
   const ordered = dependencyOrder(ws, names);
   setDeliveryHeader(wsDir, id, "Projects", ordered.join(", "));
   const d = readDelivery(wsDir, id);
   console.log(c.green("routed") + ` ${id} → ${ordered.join(" → ")}` + c.gray(" (dependencies first)"));
+  for (const x of carrying) console.log(c.yellow("warn") + ` ${x.project}'s ${x.id} still names ${id} in its Delivery header — routed out with --force`);
   console.log("");
+  const rows = deliveryChanges(wsDir, ws, d);
   console.log("Open one change in each, in this order:");
   for (const name of ordered) {
     const p = ws.projects.find((x) => x.name === name);
-    console.log("  " + c.cyan(`cd ${p?.path} && doctrina work "${d.title}" --delivery ${id}`));
+    const has = rows.find((r) => r.project === name)?.changes ?? [];
+    if (has.length > 0) console.log("  " + c.gray(`${name} already carries ${has.map((ch) => ch.id).join(", ")}`));
+    else console.log("  " + c.cyan(cdThen(p?.path ?? "", `doctrina work ${qarg(d.title)} --delivery ${id}`)));
   }
   return EXIT.OK;
 }
@@ -151,19 +193,47 @@ function deliveryList(wsDir, ws) {
   return EXIT.OK;
 }
 
-function deliveryStatus(wsDir, ws, id) {
+function deliveryStatus(wsDir, ws, id, json = false) {
   const d = readDelivery(wsDir, id);
+  // A structured payload for the planner's loop (third audit, change 0234):
+  // the envelope's text lines were all an agent got to branch on.
+  if (json) {
+    emitJson("delivery status", {
+      id: d.id, title: d.title, ref: d.ref, status: d.status, date: d.date ?? null, projects: d.projects,
+      rows: deliveryChanges(wsDir, ws, d).map((r) => ({
+        project: r.project, path: r.path ?? null, missing: r.missing ?? null, absent: r.absent ?? false,
+        changes: r.changes, abandoned: r.abandoned ?? [],
+      })),
+      otherWriters: otherWriters(wsDir, ws, d),
+      release: releaseBoxes(d.text).map(({ ordinal, checked, text }) => ({ ordinal, checked, text })),
+      blockers: deliveryBlockers(wsDir, ws, d),
+    });
+    return EXIT.OK;
+  }
   console.log(c.bold(`Delivery ${d.id}`) + ` — ${d.title}` + c.gray(` (${d.status}, ref ${d.ref}, opened ${d.date ?? "?"})`));
   console.log("");
   for (const row of deliveryChanges(wsDir, ws, d)) {
     console.log(`  ${c.cyan(row.project)}${row.path ? c.gray(" " + row.path) : ""}`);
     if (row.missing) console.log(c.red(`    ${row.missing}`));
-    else if (row.changes.length === 0) console.log(c.yellow("    no change yet") + c.gray(` — cd ${row.path} && doctrina work "${d.title}" --delivery ${d.id}`));
+    // A repository that moved: a `cd` into its old path fails (change 0234).
+    else if (row.absent) console.log(c.red("    repository not at its path") + c.gray(` — doctrina workspace attach ${row.project} --path <dir>`));
+    else if (row.changes.length === 0 && row.abandoned?.length) console.log(c.yellow(`    abandoned ${row.abandoned.map((a) => a.id).join(", ")}`) + c.gray(` — re-route without ${row.project}, or ${cdThen(row.path, `doctrina work ${qarg(d.title)} --delivery ${d.id}`)}`));
+    else if (row.changes.length === 0) console.log(c.yellow("    no change yet") + c.gray(` — ${cdThen(row.path, `doctrina work ${qarg(d.title)} --delivery ${d.id}`)}`));
     for (const ch of row.changes) {
       const colour = ch.archived ? c.green : c.yellow;
       console.log(`    ${colour(ch.status.padEnd(9))} ${ch.id}` + c.gray(`  tasks ${ch.tasksDone}/${ch.tasksTotal}`));
+      // The card is read from inside the repository (change 0226): from the
+      // workspace root there is no .doctrina/ to read it from.
+      if (!ch.archived && ch.placeholders > 0) console.log(c.gray(`              tasks not written yet (placeholders): ${cdThen(row.path, `doctrina work --resume ${ch.id}`)}`));
+      else if (!ch.archived && ch.tasksDone < ch.tasksTotal) console.log(c.gray(`              next card: ${cdThen(row.path, `doctrina change card ${ch.id}`)}`));
     }
   }
+  const others = otherWriters(wsDir, ws, d);
+  if (others.length > 0) {
+    console.log("");
+    console.log(c.yellow("  one writer per repository:") + c.gray(" these changes are open in the same repositories — sequence them, never two writers at once"));
+    for (const o of others) console.log(c.gray(`    ${o.project}: ${o.id}${o.delivery ? ` (delivery ${o.delivery})` : " (no delivery)"}`));
+  }
   const record = recordBlockers(d);
   if (record.length > 0) {
     console.log(`  ${c.cyan("record")}`);
@@ -177,6 +247,43 @@ function deliveryStatus(wsDir, ws, id) {
   return EXIT.OK;
 }
 
+// The Release claims are ticked through the CLI, like a change's boxes
+// (change 0226): Story, Sources, Plan and Observability are prose the planner
+// writes; a Release box is a claim `delivery check` holds it to.
+function deliveryTick(wsDir, id, args, flags) {
+  const file = deliveryPath(wsDir, id);
+  const text = read(file);
+  const boxes = releaseBoxes(text);
+  if (boxes.length === 0) {
+    console.log(c.gray(`${id} has no box under ## Release`));
+    return EXIT.OK;
+  }
+  const all = flagBool(flags, "all", false);
+  if (!all && args.length === 0) {
+    console.log(c.bold(`Release boxes in ${id}`) + c.gray(` (${boxes.filter((b) => !b.checked).length} of ${boxes.length} unticked):`));
+    for (const b of boxes) console.log(`  ${String(b.ordinal).padStart(2)}. [${b.checked ? "x" : " "}] ${b.text}`);
+    console.log(c.gray("tick: ") + c.cyan(`doctrina delivery tick ${id} <n...>`) + c.gray(" · all: ") + c.cyan(`doctrina delivery tick ${id} --all`));
+    return EXIT.OK;
+  }
+  const ordinals = all ? "all" : args.map(Number);
+  if (ordinals !== "all") {
+    const bad = args.filter((a, i) => !Number.isInteger(ordinals[i]) || ordinals[i] < 1 || ordinals[i] > boxes.length);
+    if (bad.length > 0) {
+      console.error(c.red("error:") + ` no Release box ${bad.join(", ")} (1..${boxes.length} — \`doctrina delivery tick ${id}\` lists them)`);
+      return EXIT.USAGE;
+    }
+  }
+  // Count what this call changes: a box already ticked, or named twice, is
+  // not news, and "ticked 2" for one new tick is a claim the file contradicts.
+  const fresh = boxes.filter((b) => !b.checked && (ordinals === "all" || ordinals.includes(b.ordinal)));
+  if (fresh.length > 0) write(file, withEol(tickRelease(text, ordinals), eolOf(text)), { force: true });
+  const n = fresh.length;
+  console.log(n === 0
+    ? c.gray(`nothing to tick in ${id} — every named Release box is already ticked`)
+    : c.green("ticked") + ` ${n} Release box${n === 1 ? "" : "es"} in ${id}`);
+  return EXIT.OK;
+}
+
 function deliveryCheck(wsDir, ws, id) {
   const d = readDelivery(wsDir, id);
   const blockers = deliveryBlockers(wsDir, ws, d);
@@ -206,7 +313,7 @@ function deliveryClose(wsDir, ws, id, flags) {
 }
 
 export const help = `
-Usage: doctrina delivery <new|route|list|status|check|close> [options]
+Usage: doctrina delivery <new|route|list|status|tick|check|close> [options]
 
 One item of work across repositories (ADR 0030) — a story, a screen, a fix.
 It lives in the workspace's deliveries/ and holds what no single repository
@@ -214,24 +321,35 @@ owns. Each project it touches gets ONE change, opened there with
 \`doctrina work "<title>" --delivery <id>\`; the delivery's state is read
 from those changes, never copied into it.
 
-  new "<title>" [--ref <tracker-id>] [--projects <a,b>]
+  new "<title>" [--ref <tracker-id>] [--projects <a,b>] [--force]
       Create deliveries/<NNNN-slug>/delivery.md and print the orchestration
       playbook: read the story, route, open one change per repository,
       delegate the task cards, close each change, release, watch, close.
       Without --projects it ranks the workspace's projects against the title.
-  route <id> <a,b>
+  route <id> <a,b> [--force]
       Set the projects (dependencies first) and print the \`work\` line for each.
+      A project still pending (no spec) or missing is refused — absorb it with
+      \`doctrina intake --from-code\` first, or pass --force.
+      Dropping a project that carries an open change for the delivery is
+      refused too — close or abandon the change there first, or --force.
   list
       Every delivery with its status, ref, closed/total changes and age —
       lead time once closed, with the median over the closed ones.
   status <id>
-      Per project: the changes carrying this delivery, their state and tasks.
+      Per project: the changes carrying this delivery, their state and tasks,
+      the command that reads the next task card, and any other open change
+      in the same repository — one writer per repository at a time.
+      --json: the same as a payload (rows, release boxes, blockers).
+  tick <id> [<n>... | --all]
+      List the ## Release boxes, or tick them: they are claims the check
+      holds you to, so they are ticked through the CLI.
   check <id>
       Exit 1 while a routed project has no change for it or one still open,
       while ## Story is empty, a ## Release box is unticked, or
       ## Observability records nothing.
-  close <id>
-      The check, then Status: closed and the Closed date.
+  close <id> [--date <YYYY-MM-DD>]
+      The check, then Status: closed and the Closed date (--date overrides
+      today, as it does for the Date that \`new\` writes).
 
 <id> is the folder name or its number (\`1\`, \`0001\`).
 `;

package/src/commands/doctor.js

@@ -8,7 +8,7 @@ import { c } from "../lib/colors.js";
 import { flagBool } from "../lib/args.js";
 import { collectRuntimeFindings, checkLocalEnv } from "../lib/runtime.js";
 import { sequence, stepRerun } from "../lib/gates.js";
-import { notADoctrinaProject } from "../lib/exit-codes.js";
+import { EXIT, notADoctrinaProject } from "../lib/exit-codes.js";
 import { agentsMdBudget, collectValidation } from "../lib/validation-model.js";
 import { collectIndexDrift } from "../lib/scan.js";
 import { collectReproducibility } from "../lib/reproducibility.js";
@@ -17,6 +17,8 @@ import { USAGE_ENV, summarise } from "../lib/usage.js";
 import { OPERATIONS } from "../lib/commands.js";
 
 import { coverageLabel } from "../lib/views.js";
+import { workspaceFindings, workspaceRootAt, workspaceSnapshot } from "../lib/workspace-view.js";
+import { cdThen } from "../lib/shell.js";
 
 // How many never-invoked operations the usage row names before pointing at
 // `metrics --commands` for the rest. The spec states this number, so it is
@@ -43,6 +45,24 @@ export const flags = { boolean: ["json", "env"], string: [] };
 
 export async function run(_positional, _flags) {
   const projectRoot = process.cwd();
+  // At the workspace root (fourth audit, change 0235): the planner reaches
+  // for doctor when something looks wrong, and was told to `doctrina init`
+  // — a project inside the workspace. The root's diagnosis is the
+  // workspace's own integrity; each repository diagnoses itself.
+  const wsRoot = workspaceRootAt(projectRoot);
+  if (wsRoot) {
+    const snap = workspaceSnapshot(wsRoot);
+    const { errors, warnings } = workspaceFindings(snap);
+    console.log(c.bold("Doctrina doctor") + c.gray(` — workspace "${snap.ws.name}" (read-only):`));
+    console.log("");
+    for (const e of errors) console.log(`  ${c.red("error")} ${e}`);
+    for (const w of warnings) console.log(`  ${c.yellow("warn ")} ${w}`);
+    if (errors.length + warnings.length === 0) console.log(`  ${c.green("ok   ")} the workspace is consistent`);
+    console.log("");
+    console.log("Each repository diagnoses itself:");
+    for (const p of snap.projects.filter((x) => x.state !== "missing")) console.log("  " + c.cyan(cdThen(p.project.path, "doctrina doctor")));
+    return errors.length > 0 ? EXIT.GATE : EXIT.OK;
+  }
   if (!exists(path.join(projectRoot, ".doctrina"))) {
     throw notADoctrinaProject();
   }

package/src/commands/handoff.js

@@ -6,6 +6,8 @@ import { c } from "../lib/colors.js";
 import { notADoctrinaProject } from "../lib/exit-codes.js";
 import { collectSnapshot } from "../lib/snapshot.js";
 import { renderView } from "../lib/views.js";
+import { contextRouting, workspaceActions, workspaceFindings, workspaceHandoff, workspaceRootAt, workspaceSnapshot, workspaceStatus } from "../lib/workspace-view.js";
+import { today } from "../lib/dates.js";
 
 // Session handoff note: everything the NEXT session (a fresh agent, a
 // teammate, tomorrow's you) needs to resume without re-reading the tree —
@@ -27,10 +29,14 @@ export const flags = { boolean: ["json"], string: [] };
 
 export async function run(_positional, _flags) {
   const projectRoot = process.cwd();
-  if (!exists(path.join(projectRoot, ".doctrina"))) {
+  const wsRoot = workspaceRootAt(projectRoot);
+  if (!wsRoot && !exists(path.join(projectRoot, ".doctrina"))) {
     throw notADoctrinaProject();
   }
-  for (const line of renderView("handoff", collectSnapshot(projectRoot))) console.log(line);
+  // At a workspace root: the planner's resume note — projects, open
+  // deliveries and their changes, the next actions (change 0230).
+  const lines = wsRoot ? workspaceHandoff(workspaceSnapshot(wsRoot), today()) : renderView("handoff", collectSnapshot(projectRoot));
+  for (const line of lines) console.log(line);
   if (process.stdout.isTTY) {
     console.log("");
     console.log(c.gray("tip: pipe it — `doctrina handoff > note.md` — or paste it as the first message of the next session"));
@@ -46,6 +52,9 @@ with its task-by-task progress and the exact resume command, and the
 prioritised next actions. Made to be pasted as the first message of the
 next agent session (or piped to a file).
 
+At a workspace root it is the planner's note instead: projects and
+their state, open deliveries with each repository's changes, next actions.
+
 The same view as \`doctrina status --view handoff\`; both render one
 collection of the tree.
 

package/src/commands/init.js

@@ -1,5 +1,6 @@
 // @ts-check
 import path from "node:path";
+import { attachCommand, shadowedCloneAt } from "../lib/workspace-view.js";
 import process from "node:process";
 import { exists, isDir, isFile, read, relPath, write } from "../lib/fs-ops.js";
 import { locateTemplatesDir, loadTemplateTree, materialiseEntry, substitute } from "../lib/templates.js";
@@ -41,6 +42,15 @@ export async function run(_positional, flags) {
   const force = flagBool(flags, "force", false);
   const nonInteractive = flagBool(flags, "non-interactive", false);
   const projectRoot = process.cwd();
+  // A clone of a shadowed repository (third audit, change 0234): its context
+  // lives in the workspace, and a .doctrina/ planted here is one the
+  // repository may not carry — and one the workspace would never see.
+  const clone = force ? null : shadowedCloneAt(projectRoot);
+  if (clone && !path.resolve(projectRoot).startsWith(path.resolve(clone.wsDir) + path.sep)) {
+    console.error(c.red("error:") + ` this repository is the workspace's shadowed "${clone.name}" (registered at ${clone.path}) — its context lives in the workspace, not here`);
+    console.error(c.gray("hint: ") + `link it here instead: \`${attachCommand(clone, projectRoot)}\` — or pass --force to init a separate project anyway`);
+    return EXIT.PRECONDITION;
+  }
   const projectName = flagString(flags, "project-name") ?? path.basename(projectRoot);
   const date = flagString(flags, "date") ?? today();
 
@@ -454,6 +464,8 @@ Options:
   --from <path>                  Local conventions directory; if it contains AGENTS.md and/or
                                  .doctrina/product.md, the content is folded into the new project
   --date <YYYY-MM-DD>            Override the system date
-  --force                        Overwrite existing files
+  --force                        Overwrite existing files that are still untouched scaffolds;
+                                 also init a second clone of a repository a workspace shadows
+  --overwrite-content            With --force, also overwrite an authored AGENTS.md or product.md
   --non-interactive              Fail instead of prompting for missing values
 `;

package/src/commands/intake.js

@@ -43,7 +43,7 @@ export async function run(positional, flags) {
   // a bootstrap that was already done.
   if (flagBool(flags, "converted", false)) {
     ensureDoctrinaProject(projectRoot);
-    // Converting is the claim that the bootstrap is done — step 6 of the
+    // Converting is the claim that the bootstrap is done — step 8 of the
     // playbook, "fix everything the gates report", made checkable (change
     // 0194). It used to convert over a tree `validate` failed, so the specs
     // became "the source of truth" while an error still said they were not
@@ -95,7 +95,12 @@ export async function run(positional, flags) {
       console.log(c.gray("hint: ") + "start implementation with `doctrina work \"<brief prompt>\"`");
       return 0;
     }
-    printBootstrapPlaybook(projectRoot);
+    // An intake written by `--from-code` is a code inventory, and the
+    // playbook that reads it is the absorb (second audit, change 0233). The
+    // bootstrap one — "fill every product.md section from the intake" —
+    // handed a resuming agent the inventory as if it were the product's intent.
+    if (/code inventory/i.test(listHeader(read(intakePath), "Source") ?? "")) printAbsorbPlaybook(projectRoot);
+    else printBootstrapPlaybook(projectRoot);
     return 0;
   }
 
@@ -180,15 +185,21 @@ function intakeFromCode(projectRoot, force) {
     source: "code inventory (`doctrina intake --from-code`)",
     projectName: name, date: today(), force: true,
   });
-  console.log(c.green("created") + ` ${relPath(projectRoot, intakePath)} — ${inv.files} files read: ${inv.stack.join(", ") || "no manifest"}; ${inv.tests.files} test files; ${inv.areas.length} candidate areas`);
+  const plural = (/** @type {number} */ n, /** @type {string} */ word) => `${n} ${word}${n === 1 ? "" : "s"}`;
+  console.log(c.green("created") + ` ${relPath(projectRoot, intakePath)} — ${plural(inv.files, "file")} read: ${inv.stack.join(", ") || "no manifest"}; ${plural(inv.tests.files, "test file")}; ${plural(inv.areas.length, "candidate area")}`);
   console.log("");
+  printAbsorbPlaybook(projectRoot);
+  return EXIT.OK;
+}
+
+/** The absorb playbook — printed by `--from-code`, and again by a bare `intake` while it is pending. */
+function printAbsorbPlaybook(projectRoot) {
   const ws = findWorkspace(projectRoot);
   printPlaybookTemplate(projectRoot, "absorb", {
     WORKSPACE_STEP: ws
-      ? `\n8. This project belongs to the workspace at ${ws.dir} — confirm it reads\n   ready: ${c.cyan("doctrina workspace list")}, and commit the workspace.`
+      ? `\n10. This project belongs to the workspace at ${ws.dir} — confirm it reads\n    ready: ${c.cyan("doctrina workspace list")}, and commit the workspace.`
       : "",
   });
-  return EXIT.OK;
 }
 
 export const help = `

package/src/commands/metrics.js

@@ -12,6 +12,8 @@ import { notADoctrinaProject } from "../lib/exit-codes.js";
 import { USAGE_ENV, summarise } from "../lib/usage.js";
 import { OPERATIONS } from "../lib/commands.js";
 import { REEDIT_WINDOW_DAYS, sinceWindow, computeSnapshot, parseLog, readSeries, latestSnapshot, trend, round } from "../lib/metrics-model.js";
+import { workspaceRootAt, workspaceSnapshot } from "../lib/workspace-view.js";
+import { cdThen } from "../lib/shell.js";
 
 // Local-only adoption metrics derived from git history. No network calls,
 // no telemetry: the numbers stay in the repository, versioned like any
@@ -24,6 +26,19 @@ export const flags = { boolean: ["json", "save", "commands", "trend"], string: [
 
 export async function run(_positional, flags) {
   const projectRoot = process.cwd();
+  // At the workspace root (change 0235): adoption is measured per repository;
+  // the deliveries' own lead time is `delivery list`.
+  const wsRoot = workspaceRootAt(projectRoot);
+  if (wsRoot && !flagBool(flags, "commands", false)) {
+    const snap = workspaceSnapshot(wsRoot);
+    console.log(c.bold("Doctrina metrics") + c.gray(` — workspace "${snap.ws.name}"`));
+    console.log("");
+    console.log(`Deliveries  ${snap.open.length} open · ${snap.deliveries.length - snap.open.length} closed — lead time per delivery: ${c.cyan("doctrina delivery list")}`);
+    console.log("");
+    console.log("Adoption is measured in each repository:");
+    for (const p of snap.projects.filter((x) => x.state !== "missing")) console.log("  " + c.cyan(cdThen(p.project.path, "doctrina metrics")));
+    return EXIT.OK;
+  }
   if (!exists(path.join(projectRoot, ".doctrina"))) {
     throw notADoctrinaProject();
   }

package/src/commands/next.js

@@ -8,6 +8,7 @@ import { c } from "../lib/colors.js";
 import { emitJson } from "../lib/json-out.js";
 import { EXIT } from "../lib/exit-codes.js";
 import { action, computeActions, invocation } from "../lib/actions.js";
+import { attachCommand, contextRouting, shadowedCloneAt, workspaceActions, workspaceFindings, workspaceHandoff, workspaceRootAt, workspaceSnapshot, workspaceStatus } from "../lib/workspace-view.js";
 
 // `next` answers "what now?". The ANSWER lives in `lib/actions.js` as
 // records; this module renders them and, under `--run`, executes one
@@ -22,18 +23,48 @@ import { action, computeActions, invocation } from "../lib/actions.js";
 // wrap it in the generic envelope.
 export const jsonNative = true;
 
+// How many actions `next` prints at a workspace root.
+const ROOT_ACTIONS_SHOWN = 10;
+
 export const flags = { boolean: ["json", "run"], string: [] };
 
 export async function run(_positional, flags) {
   const projectRoot = process.cwd();
   const json = flagBool(flags, "json", false);
+  // At a workspace root the planner's next step is the workspace's — never
+  // `init`, which would create a project inside the workspace (change 0230).
+  const wsRoot = workspaceRootAt(projectRoot);
+  if (wsRoot) {
+    const actions = workspaceActions(workspaceSnapshot(wsRoot));
+    if (json) emitJson("next", { workspace: wsRoot, actions });
+    else {
+      console.log(c.bold("Next actions in the workspace") + c.gray(" (in priority order):"));
+      console.log("");
+      // The first actions, not all of them (fifth audit, change 0236): forty
+      // open deliveries printed 162 lines into the planner's context. The
+      // order already puts what unblocks most first; --json keeps every one.
+      actions.slice(0, ROOT_ACTIONS_SHOWN).forEach((a, i) => console.log(`${i + 1}. ${a.text}\n     ${c.cyan(a.command)}`));
+      if (actions.length > ROOT_ACTIONS_SHOWN) {
+        console.log("");
+        console.log(c.gray(`… and ${actions.length - ROOT_ACTIONS_SHOWN} more — every delivery's state: \`doctrina delivery list\`; every action: \`doctrina next --json\``));
+      }
+    }
+    return 0;
+  }
   if (!exists(path.join(projectRoot, ".doctrina"))) {
-    const first = action({
-      id: "not-a-project",
-      command: "init",
-      runnable: false,
-      why: "this directory is not a Doctrina project yet",
-    });
+    const clone = shadowedCloneAt(projectRoot);
+    const first = clone
+      ? action({
+        id: "shadowed-clone",
+        why: `this repository is the workspace's shadowed "${clone.name}" at another path — link its context here, never init it`,
+        text: `${attachCommand(clone, projectRoot)} — this repository is the workspace's shadowed "${clone.name}"${clone.same ? " and its links are missing" : ` (registered at ${clone.path})`}; never \`doctrina init\` here`,
+      })
+      : action({
+        id: "not-a-project",
+        command: "init",
+        runnable: false,
+        why: "this directory is not a Doctrina project yet",
+      });
     if (json) emitJson("next", { actions: [first] });
     else console.log(`1. ${first.text}`);
     return 0;
@@ -154,6 +185,10 @@ proposed status, accepted ADRs with nothing proving them (cite Evidence
 or run "decision land"), a skill-capture nudge when a past fix went
 uncaptured, and index drift last.
 
+At a workspace root it lists the workspace's next actions instead —
+absorb, route, open, hand the next card, close, clear a delivery's
+record, close the delivery — and never names init there.
+
 Intended use: agents and humans run it to resume work without
 re-reading the whole tree.
 

package/src/commands/prime.js

@@ -1,10 +1,11 @@
 // @ts-check
 import path from "node:path";
 import process from "node:process";
-import { exists, read } from "../lib/fs-ops.js";
+import { exists, isFile, read } from "../lib/fs-ops.js";
 import { findWorkspace, readWorkspace } from "../lib/workspace.js";
 import { listDeliveries } from "../lib/delivery.js";
 import { workspacePrimer } from "../lib/workspace-agents.js";
+import { projectWorkspaceLine } from "../lib/workspace-view.js";
 import { flagBool, flagString } from "../lib/args.js";
 import { c } from "../lib/colors.js";
 import { EXIT, notADoctrinaProject } from "../lib/exit-codes.js";
@@ -51,6 +52,14 @@ export async function run(_positional, flags) {
   // --pulse: one line for a per-prompt hook — the open changes only, read
   // without collecting the gates, because it runs before every prompt.
   if (flagBool(flags, "pulse", false)) {
+    // Run by Cursor as the Claude adapter's UserPromptSubmit (sixth audit,
+    // change 0237): Cursor imports `.claude/settings.json` hooks and runs it
+    // as beforeSubmitPrompt, whose answer is `{"continue": …}` and cannot add
+    // context. The plain-text line Claude Code reads is not that.
+    if (underCursor()) {
+      console.log(JSON.stringify({ continue: true }));
+      return 0;
+    }
     for (const line of pulse(openChanges(projectRoot), recentlyClosed(projectRoot, { limit: 1 }))) console.log(line);
     return 0;
   }
@@ -60,17 +69,55 @@ export async function run(_positional, flags) {
       console.error(c.red("error:") + ` --hook needs one of ${HOOK_AGENTS.join(", ")} (got "${agent ?? ""}")`);
       return EXIT.USAGE;
     }
+    const as = hookFlavour(agent, projectRoot);
+    if (as === null) return 0;
     const text = ["Doctrina session primer (`doctrina prime`) — the project's gates, rules and open work:", "",
-      ...renderView("prime", collectSnapshot(projectRoot)), "", ...pulse(openChanges(projectRoot), recentlyClosed(projectRoot, { limit: 1 }))]
+      ...renderView("prime", collectSnapshot(projectRoot)), ...workspaceLines(projectRoot), "", ...pulse(openChanges(projectRoot), recentlyClosed(projectRoot, { limit: 1 }))]
       .join("\n").replace(/\x1b\[[0-9;]*m/g, "").slice(0, HOOK_MAX_CHARS);
-    console.log(agent === "cursor" ? JSON.stringify({ additional_context: text }) : text);
+    console.log(as === "cursor" ? JSON.stringify({ additional_context: text }) : text);
     return 0;
   }
   const view = flagBool(flags, "rules", false) ? "rules" : "prime";
   for (const line of renderView(view, collectSnapshot(projectRoot))) console.log(line);
+  if (view === "prime") for (const line of workspaceLines(projectRoot)) console.log(line);
   return 0;
 }
 
+// Cursor runs the hooks Claude Code's `.claude/settings.json` declares too
+// (its "third-party" import, on by default), and sets CURSOR_VERSION and
+// CURSOR_PROJECT_DIR for every hook it runs (sixth audit, change 0237).
+function underCursor(env = process.env) {
+  return Boolean(env.CURSOR_VERSION && env.CURSOR_PROJECT_DIR);
+}
+
+/**
+ * The format a session hook answers in, or null to answer nothing. The
+ * Claude adapter's SessionStart, run by Cursor, printed plain text where
+ * Cursor reads JSON — and beside the Cursor adapter's own sessionStart it
+ * put the primer in twice. Under Cursor it yields to that hook when the
+ * folder has one, and speaks Cursor's format when it has not.
+ * @returns {"claude" | "cursor" | null}
+ */
+function hookFlavour(agent, dir) {
+  if (agent !== "claude" || !underCursor()) return /** @type {"claude" | "cursor"} */ (agent);
+  const own = path.join(dir, ".cursor", "hooks.json");
+  return isFile(own) && /prime --hook cursor/.test(read(own)) ? null : "cursor";
+}
+
+// A project inside a workspace says so (change 0230): a session opened in
+// the repository — an executor's, or the human's — otherwise never learns a
+// delivery is open on it, or where its planner works.
+function workspaceLines(projectRoot) {
+  const w = projectWorkspaceLine(projectRoot);
+  if (!w) return [];
+  const out = ["", `Workspace  ${w.name} (${w.dir}) — this repository is "${w.project}"`];
+  for (const d of w.deliveries) {
+    out.push(`  open delivery ${d.id} — ${d.title}: ${d.changes.length ? `this project's change ${d.changes.join(", ")}` : "no change here yet"}`);
+  }
+  if (w.deliveries.length === 0) out.push("  no open delivery routes here");
+  return out;
+}
+
 function primeWorkspace(wsDir, flags) {
   const ws = readWorkspace(wsDir);
   const open = listDeliveries(wsDir).filter((d) => d.status !== "closed");
@@ -87,8 +134,10 @@ function primeWorkspace(wsDir, flags) {
       console.error(c.red("error:") + ` --hook needs one of ${HOOK_AGENTS.join(", ")} (got "${agent ?? ""}")`);
       return EXIT.USAGE;
     }
+    const as = hookFlavour(agent, wsDir);
+    if (as === null) return 0;
     const text = [...lines, "", read(path.join(wsDir, "AGENTS.md"))].join("\n").replace(/\x1b\[[0-9;]*m/g, "").slice(0, HOOK_MAX_CHARS);
-    console.log(agent === "cursor" ? JSON.stringify({ additional_context: text }) : text);
+    console.log(as === "cursor" ? JSON.stringify({ additional_context: text }) : text);
     return 0;
   }
   for (const line of lines) console.log(line);