doctrina-cli 0.20.0 → 0.22.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,13 @@ 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";
+import { cliVersion } from "../lib/version.js";
+import { installsOnPath, runningPackageDir } from "../lib/install.js";
+import { missingAttributes, configuredDriver } from "../lib/merge-setup.js";
+import { isRepo } from "../lib/git.js";
+import { shadowRootOf } from "../lib/workspace.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 +50,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();
   }
@@ -256,9 +281,9 @@ export async function run(_positional, _flags) {
           " (run `doctrina verify` to execute)";
         if (stale > 0) {
           const parts = [];
-          if (so.expired) parts.push(`${so.expired} expired`);
-          if (so.unverifiable) parts.push(`${so.unverifiable} unverifiable`);
-          if (so.pending) parts.push(`${so.pending} unsigned`);
+          if (so?.expired) parts.push(`${so.expired} expired`);
+          if (so?.unverifiable) parts.push(`${so.unverifiable} unverifiable`);
+          if (so?.pending) parts.push(`${so.pending} unsigned`);
           row("warn", "verify config", `${detail} — ${parts.join(", ")}`,
             "doctrina verify   (each names the re-sign command)");
           warningsTotal += 1;
@@ -286,7 +311,7 @@ export async function run(_positional, _flags) {
       if (cfg.errors.length > 0) {
         row("fail", "config", cfg.errors[0], "fix .doctrina/config.json, then `doctrina validate`");
       } else if (cfg.unknown.length > 0) {
-        row("warn", "config", `${summary}; unknown key${cfg.unknown.length === 1 ? "" : "s"} ${cfg.unknown.map((k) => `"${k}"`).join(", ")} ignored`, "the keys are language, context_budget, rules");
+        row("warn", "config", `${summary}; unknown key${cfg.unknown.length === 1 ? "" : "s"} ${cfg.unknown.map((k) => `"${k}"`).join(", ")} ignored`, "the keys are language, context_budget, rules, surface");
         warningsTotal += 1;
       } else {
         row("ok", "config", summary);
@@ -296,6 +321,45 @@ export async function run(_positional, _flags) {
       }
     },
 
+    // 9b. The CLI that is running, and the one a bare `doctrina` finds.
+    cli: () => {
+      const version = cliVersion();
+      const installs = installsOnPath();
+      const first = installs[0];
+      const here = runningPackageDir();
+      const others = installs.filter((i) => !i.running);
+      const label = (/** @type {{ bin: string, version: string | null }} */ i) => `${i.bin} (${i.version ?? "version unknown"})`;
+      if (first && !first.running) {
+        row("warn", "cli", `${version} is running from ${here}, but \`doctrina\` on the PATH is ${label(first)} — the hooks and every bare \`doctrina\` run that one`,
+          `remove or update the other install (npm uninstall -g doctrina-cli under the Node that owns it), or put this one first on the PATH`);
+        warningsTotal += 1;
+      } else if (others.length > 0) {
+        row("warn", "cli", `${version} at ${first.bin}; ${others.length} more on the PATH: ${others.map(label).join(", ")}`,
+          "remove the copies you do not use — a shell whose PATH orders them differently runs another version");
+        warningsTotal += 1;
+      } else if (!first && callsDoctrinaByName(projectRoot)) {
+        row("warn", "cli", `${version} is running from ${here}, and no \`doctrina\` is on the PATH — this project's agent hooks call it by name`,
+          "npm install -g doctrina-cli   (or add its bin directory to the PATH)");
+        warningsTotal += 1;
+      } else {
+        row("ok", "cli", first ? `${version} at ${first.bin} — the only one on the PATH` : `${version}, run from ${here} (no \`doctrina\` on the PATH)`);
+      }
+    },
+
+    // 9c. Whether two branches that each close a change merge by themselves.
+    merges: () => {
+      if (!isRepo(projectRoot) || shadowRootOf(projectRoot) !== null) return;
+      const attributes = missingAttributes(projectRoot).length === 0;
+      const driver = configuredDriver(projectRoot) !== null;
+      if (attributes && driver) {
+        row("ok", "merges", "index.json and the ledger merge by themselves (driver and .gitattributes in place)");
+        return;
+      }
+      const missing = !attributes && !driver ? "nothing is set up" : !attributes ? ".gitattributes lacks the two lines" : "this clone has no merge driver";
+      row("warn", "merges", `${missing} — two branches that each close a change stop on index.json and the ledger`, "doctrina hooks install   (once per clone; commit .gitattributes)");
+      warningsTotal += 1;
+    },
+
     // 10. Which of the catalog's operations have never been reached for —
     //     but ONLY when the operator turned the log on. `lib/usage.js` was
     //     built to instrument the surface before shrinking it, and the only
@@ -357,6 +421,14 @@ export async function run(_positional, _flags) {
   return 0;
 }
 
+/** Does an agent hook in this project call `doctrina` by its bare name? */
+function callsDoctrinaByName(projectRoot) {
+  return [".cursor/hooks.json", ".claude/settings.json"].some((rel) => {
+    const file = path.join(projectRoot, rel);
+    return isFile(file) && /"(command)":\s*"doctrina /.test(read(file));
+  });
+}
+
 export const help = `
 Usage: doctrina doctor
 
@@ -371,6 +443,12 @@ exact remediation command.
            enums. Reports membership only; a rejected value is never
            printed, so this is safe to run and to paste.
 
+Two rows read the machine and the clone, not the artifacts: \`cli\` names
+the install that is running and any other \`doctrina\` the PATH holds — the
+agent hooks call it by name, so the first one found is the one they run —
+and \`merges\` says whether \`doctrina hooks install\` has set this clone up
+to merge index.json and the ledger without a manual step.
+
 A driver over the same collections the gates themselves render; it adds
 no checks of its own, so it can never disagree with the gates it fronts,
 and it runs entirely in this process — no subprocess, no re-parsing of

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/hooks.js

@@ -11,6 +11,9 @@ import { flagBool } from "../lib/args.js";
 import { c } from "../lib/colors.js";
 import { suggest } from "../lib/suggest.js";
 import { EXIT } from "../lib/exit-codes.js";
+import { writeAttributes, configureDriver, configuredDriver } from "../lib/merge-setup.js";
+import { shadowRootOf } from "../lib/workspace.js";
+import { gitPathOf, repoPrefix } from "../lib/git.js";
 
 const SUBCOMMANDS = ["install"];
 
@@ -33,16 +36,49 @@ export async function run(positional, flags) {
   const force = flagBool(flags, "force", false);
   const projectRoot = process.cwd();
 
-  if (!exists(path.join(projectRoot, ".git"))) {
+  // Asked of git, not of `.git/` (seventh audit, change 0250). In a worktree
+  // and in a submodule `.git` is a file, so `mkdir .git/hooks` crashed with
+  // ENOTDIR after the attributes were already written; and a project in a
+  // subfolder of its repository has no `.git` beside it at all, so it was
+  // told to `git init` inside a repository — while `doctor` kept sending it
+  // back here.
+  const prefix = repoPrefix(projectRoot);
+  const hooksDir = prefix === null ? null : gitPathOf(projectRoot, "hooks");
+  if (prefix === null || hooksDir === null) {
     // A PRECONDITION, not a gate: nothing was measured and found wanting,
     // the place to put the hook simply does not exist yet. Class 1 told an
     // agent to fix its work and retry the same command, which never clears.
-    console.error(c.red("error:") + " not a git repository (no .git/ in cwd)");
+    console.error(c.red("error:") + " not a git repository — git does not answer for this folder");
     console.error(c.gray("hint: ") + "run `git init` here, then `doctrina hooks install`");
     return EXIT.PRECONDITION;
   }
 
-  const hooksDir = path.join(projectRoot, ".git", "hooks");
+  // The CLI that installed this, pinned by path (change 0116). `.git/` is
+  // local to the clone, so an absolute path is the right thing to write;
+  // a bare `doctrina` ran whichever release was on the PATH — a global
+  // 0.15.0 under a 0.15.1 tree rewrote the stamp backwards on every commit.
+  // `DOCTRINA=` in the environment overrides it for the hook.
+  const entry = path.resolve(here, "..", "index.js").replaceAll("\\", "/");
+  const bin = `node \"${entry}\"`;
+
+  // How the artifacts merge (change 0242). Before the hook, and whatever
+  // becomes of it: a pre-commit hook somebody else owns is no reason for
+  // two branches to stop on index.json. A shadowed repository keeps its
+  // `.doctrina/` out of its own git, so there is nothing of it to merge here.
+  if (shadowRootOf(projectRoot) === null) {
+    const added = writeAttributes(projectRoot);
+    if (added > 0) console.log(c.green("wrote") + ` .gitattributes — ${added} line${added === 1 ? "" : "s"}: index.json merges as data, the ledger as a list (commit it)`);
+    const before = configuredDriver(projectRoot);
+    const command = `node "${entry}"`;
+    if (before !== `${command} index merge %O %A %B`) {
+      if (configureDriver(projectRoot, command)) {
+        console.log(c.green("set") + "   the index merge driver in this clone's git config (every clone runs `doctrina hooks install` once)");
+      } else {
+        console.log(c.yellow("warn:") + " git refused the merge driver; two branches that close changes will stop on index.json — `doctrina index rebuild` resolves it");
+      }
+    }
+  }
+
   mkdirp(hooksDir);
 
   const target = path.join(hooksDir, "pre-commit");
@@ -53,13 +89,13 @@ export async function run(positional, flags) {
 
   const templatesDir = locateTemplatesDir();
   const tplPath = path.join(templatesDir, "hooks", "pre-commit.sample");
-  // The hook pins the CLI that installed it (change 0116). `.git/hooks/` is
-  // local to the clone, so an absolute path is the right thing to write;
-  // a bare `doctrina` ran whichever release was on the PATH — a global
-  // 0.15.0 under a 0.15.1 tree rewrote the stamp backwards on every commit.
-  // `DOCTRINA=` in the environment overrides it.
-  const entry = path.resolve(here, "..", "index.js").replaceAll("\\", "/");
-  const body = substitute(read(tplPath), { DOCTRINA_BIN: `node \"${entry}\"` });
+  let body = substitute(read(tplPath), { DOCTRINA_BIN: bin });
+  // git runs a hook from the top of the repository. A project that lives
+  // below it is entered first, or `validate` would answer for a folder that
+  // is not a Doctrina project.
+  if (prefix !== "") {
+    body = body.replace(/^DOCTRINA=/m, `# This Doctrina project lives below the repository root.\ncd "${prefix}" || exit 1\n\nDOCTRINA=`);
+  }
   write(target, body, { force: true });
   chmodSync(target, 0o755);
   console.log(c.green("installed") + ` ${relPath(projectRoot, target)}`);
@@ -72,7 +108,16 @@ export async function run(positional, flags) {
 export const help = `
 Usage: doctrina hooks install [--force]
 
-Install the Doctrina pre-commit hook into .git/hooks/pre-commit.
+Set the repository up for commits and merges:
+
+  - .gitattributes gains two lines (commit them): index.json merges through
+    \`doctrina index merge\`, as a list of artifacts, and the ledger through
+    git's own \`union\`, so two branches that each closed a change merge
+    without conflict markers in either file;
+  - this clone's git config gains the index merge driver, pinned to the CLI
+    that installed it — every clone runs \`doctrina hooks install\` once;
+  - .git/hooks/pre-commit gains the Doctrina hook.
+
 The hook runs \`doctrina validate --fix\`: it regenerates index.json
 from the tree (healing the most common gate failure — a hand-edited
 header that drifted the index — and re-staging the repaired index)

package/src/commands/index-rebuild.js

@@ -10,8 +10,10 @@ import { c } from "../lib/colors.js";
 import { suggest } from "../lib/suggest.js";
 import { notADoctrinaProject } from "../lib/exit-codes.js";
 import { planSkillExport, applySkillExport } from "../lib/skill-export.js";
+import { mergeIndex } from "../lib/index-merge.js";
+import { readFileSync, writeFileSync } from "node:fs";
 
-const SUBCOMMANDS = ["rebuild"];
+const SUBCOMMANDS = ["rebuild", "merge"];
 
 // Flags this command accepts. Declared HERE, with the command, so
 // adding a command never requires editing the entrypoint — the gap that
@@ -20,6 +22,7 @@ export const flags = { boolean: ["json", "check", "staged"], string: [] };
 
 export async function run(positional, flags) {
   const sub = positional[0];
+  if (sub === "merge") return merge(positional.slice(1));
   if (sub !== "rebuild") {
     console.error(c.red("error:") + ` unknown index subcommand "${sub ?? ""}"`);
     const guess = suggest(sub, SUBCOMMANDS);
@@ -98,6 +101,43 @@ function rebuild(flags) {
   return 0;
 }
 
+// The merge driver git calls for `.doctrina/index.json` (change 0242):
+// `doctrina index merge %O %A %B`. It writes the merged index over <ours>
+// and exits 0, which is how a driver tells git there is nothing to resolve.
+// A side that is not JSON is the one case it leaves to git, with exit 1.
+function merge(args) {
+  const [basePath, oursPath, theirsPath] = args;
+  if (!basePath || !oursPath || !theirsPath) {
+    console.error(c.red("error:") + " index merge takes three files: <base> <ours> <theirs>");
+    console.error(c.gray("hint: ") + "git calls it as a merge driver — `doctrina hooks install` sets it up");
+    return 2;
+  }
+  const load = (/** @type {string} */ file, /** @type {string} */ side) => {
+    let text = "";
+    try {
+      text = readFileSync(file, "utf8");
+    } catch {
+      if (side === "base") return {};
+      throw new Error(`cannot read the ${side} index at ${file}`);
+    }
+    if (text.trim() === "") return {};
+    try {
+      return JSON.parse(text);
+    } catch (err) {
+      throw new Error(`the ${side} index is not valid JSON (${err.message})`);
+    }
+  };
+  let merged;
+  try {
+    merged = mergeIndex(load(basePath, "base"), load(oursPath, "ours"), load(theirsPath, "theirs"));
+  } catch (err) {
+    console.error(c.red("error:") + ` ${err.message} — left for a manual merge; \`doctrina index rebuild\` derives it from the tree afterwards`);
+    return 1;
+  }
+  writeFileSync(oursPath, JSON.stringify(merged, null, 2) + "\n");
+  return 0;
+}
+
 // The drift check, asked of what git will record. `index.json` is derived
 // from the WHOLE tree, so it cannot describe a subset of it: stage part of
 // `.doctrina/` and the index riding along names artifacts the commit does
@@ -135,6 +175,12 @@ export const help = `
 Usage: doctrina index <subcommand>
 
 Subcommands:
+  merge <base> <ours> <theirs>
+                    The merge driver git runs for index.json once
+                    \`doctrina hooks install\` has set it up: two branches
+                    that each closed a change merge as lists of artifacts,
+                    so the file never stops a merge with conflict markers.
+                    Writes the result over <ours>.
   rebuild           Regenerate .doctrina/index.json from the artifacts on
                     disk (spec headers, ADR headers, change proposals,
                     archive folders, skill frontmatter). The files are the