doctrina-cli 0.18.0 → 0.21.0

package/src/commands/delivery.js

@@ -0,0 +1,356 @@
+// @ts-check
+import process from "node:process";
+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 { 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", "tick", "check", "close"];
+
+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];
+  if (!SUBCOMMANDS.includes(sub)) {
+    console.error(c.red("error:") + ` unknown delivery subcommand "${sub ?? ""}"`);
+    const guess = suggest(sub, SUBCOMMANDS);
+    console.error(c.gray("hint: ") + (guess ? `did you mean \`doctrina delivery ${guess}\`?` : `available: ${SUBCOMMANDS.join(", ")}`));
+    return EXIT.USAGE;
+  }
+  const found = findWorkspace(process.cwd());
+  if (!found) {
+    throw new PreconditionError("a delivery lives in a workspace, and none was found here", "doctrina workspace init <dir>");
+  }
+  const wsDir = found.dir;
+  const ws = readWorkspace(wsDir);
+  if (sub === "new") return deliveryNew(wsDir, ws, positional.slice(1).join(" ").trim(), flags);
+  if (sub === "list") return deliveryList(wsDir, ws);
+  const id = resolveDeliveryId(wsDir, positional[1]);
+  if (!id) {
+    console.error(c.red("error:") + ` no delivery "${positional[1] ?? ""}" in this workspace`);
+    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"), 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);
+}
+
+function parseProjects(ws, raw) {
+  const names = String(raw ?? "").split(",").map((s) => s.trim()).filter(Boolean);
+  const unknown = names.filter((n) => !ws.projects.some((p) => p.name === n));
+  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");
+    console.error(c.gray("hint: ") + 'doctrina delivery new "Login screen" --ref SHOP-123');
+    return EXIT.USAGE;
+  }
+  if (ws.projects.length === 0) {
+    throw new PreconditionError("the workspace has no project to deliver into", "doctrina workspace add <path>");
+  }
+  const { names, unknown } = parseProjects(ws, flagString(flags, "projects"));
+  if (unknown.length > 0) {
+    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);
+  const tpl = readTemplate(wsDir, "delivery.md.template");
+  const file = deliveryPath(wsDir, id);
+  write(file, substitute(tpl.body, {
+    DELIVERY_ID: id, DELIVERY_TITLE: title, DATE: flagString(flags, "date") ?? today(),
+    DELIVERY_REF: ref, DELIVERY_PROJECTS: ordered.length ? ordered.join(", ") : "—",
+  }));
+  console.log(c.green("created") + ` ${relPath(wsDir, file)}`);
+  console.log("");
+  console.log(renderPlaybook(wsDir, "delivery", playbookTokens(wsDir, ws, readDelivery(wsDir, id))));
+  return EXIT.OK;
+}
+
+function playbookTokens(wsDir, ws, delivery) {
+  const ranked = rankProjects(wsDir, ws, `${delivery.title} ${delivery.ref}`);
+  const routing = delivery.projects.length > 0
+    ? `       routed: ${dependencyOrder(ws, delivery.projects).join(" → ")} — route again to change it`
+    : ranked.map(({ project, score, shared }) =>
+      `       ${c.cyan(project.name.padEnd(16))} ${score > 0 ? `shares ${shared.join(", ")}` : c.gray("no shared term")}`
+      + c.gray(` · ${project.role || "no role"}${project.dependsOn?.length ? ` · depends on ${project.dependsOn.join(", ")}` : ""}`)).join("\n");
+  const tools = ws.tools.filter((t) => t.enabled !== false);
+  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,
+    TOOLS: tools.length === 0 ? "" : "   Tools this workspace declares:\n" + tools.map((t) =>
+      `       ${c.cyan(t.name.padEnd(12))} ${t.access === "write" ? "read/write (writes need the human)" : "read-only"} — ${t.purpose || t.server}`).join("\n"),
+  };
+}
+
+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");
+    console.error(c.gray("hint: ") + `doctrina delivery route ${id} back-end,front-core`);
+    return EXIT.USAGE;
+  }
+  if (unknown.length > 0) {
+    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);
+    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;
+}
+
+function deliveryList(wsDir, ws) {
+  const all = listDeliveries(wsDir);
+  if (all.length === 0) {
+    console.log(c.gray("no delivery yet — `doctrina delivery new \"<title>\" --ref <tracker-id>`"));
+    return EXIT.OK;
+  }
+  for (const d of all) {
+    const rows = deliveryChanges(wsDir, ws, d);
+    const changes = rows.flatMap((r) => r.changes);
+    const closed = changes.filter((ch) => ch.archived).length;
+    const colour = d.status === "closed" ? c.green : c.yellow;
+    const days = daysBetween(d.date, d.status === "closed" ? d.closed : today());
+    const age = days === null ? "" : d.status === "closed" ? `, lead time ${days}d` : `, open ${days}d`;
+    console.log(`  ${c.cyan(d.id.padEnd(30))} ${colour(d.status.padEnd(7))} ${d.ref.padEnd(12)} ${d.projects.join(", ") || "—"}` +
+      c.gray(`  ${closed}/${changes.length} changes closed${age}`));
+  }
+  const leads = all.filter((d) => d.status === "closed").map((d) => daysBetween(d.date, d.closed)).filter((n) => n !== null).sort((a, b) => a - b);
+  if (leads.length > 0) {
+    console.log("");
+    console.log(c.gray(`${leads.length} closed · median lead time ${leads[Math.floor((leads.length - 1) / 2)]}d · longest ${leads[leads.length - 1]}d`));
+  }
+  return EXIT.OK;
+}
+
+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}`));
+    // 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")}`);
+    for (const r of record) console.log(c.yellow("    ") + r);
+  }
+  const blockers = deliveryBlockers(wsDir, ws, d);
+  console.log("");
+  console.log(blockers.length === 0
+    ? c.green("ready to close") + ` — doctrina delivery close ${d.id}`
+    : c.gray(`${blockers.length} thing${blockers.length === 1 ? "" : "s"} before the close — doctrina delivery check ${d.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);
+  if (blockers.length === 0) {
+    console.log(c.green("ok") + ` ${id} is ready to close: doctrina delivery close ${id}`);
+    return EXIT.OK;
+  }
+  for (const b of blockers) console.log(c.red("✗ ") + b);
+  console.log("");
+  console.log(c.red("fail") + ` ${blockers.length} blocker${blockers.length === 1 ? "" : "s"}`);
+  return EXIT.GATE;
+}
+
+function deliveryClose(wsDir, ws, id, flags) {
+  const d = readDelivery(wsDir, id);
+  if (d.status === "closed") {
+    console.log(c.gray(`${id} is already closed (${d.closed ?? "?"})`));
+    return EXIT.OK;
+  }
+  if (deliveryCheck(wsDir, ws, id) !== EXIT.OK) return EXIT.GATE;
+  const date = flagString(flags, "date") ?? today();
+  setDeliveryHeader(wsDir, id, "Status", "closed");
+  setDeliveryHeader(wsDir, id, "Closed", date);
+  console.log(c.green("closed") + ` ${id}`);
+  console.log(`Tell the human: delivery ${id} is closed — ${d.projects.length} project${d.projects.length === 1 ? "" : "s"} (${d.projects.join(", ")}); record at ${relPath(wsDir, deliveryPath(wsDir, id))}. Commit the workspace.`);
+  return EXIT.OK;
+}
+
+export const help = `
+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
+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>] [--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> [--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,
+      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> [--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/index-rebuild.js

@@ -9,6 +9,7 @@ import { flagBool } from "../lib/args.js";
 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";
 
 const SUBCOMMANDS = ["rebuild"];
 
@@ -56,6 +57,23 @@ function rebuild(flags) {
     console.log(c.yellow("warn:") + ` ${state.unreadable} — rebuilding from scratch`);
   }
 
+  // The skills, where the agents look for them (change 0212). Exported on
+  // every rebuild; under --check a stale export is a NOTE, never a failure —
+  // the index gate is about the index, and a project upgrading Doctrina must
+  // not go red in CI before its first rebuild.
+  const exportPlan = planSkillExport(projectRoot);
+  const exportChanges = exportPlan.writes.length + exportPlan.removes.length;
+  if (exportChanges > 0) {
+    if (check) {
+      console.log(c.gray("note:  ") + `${exportChanges} skill export${exportChanges === 1 ? " is" : "s are"} out of date — ` +
+        "`doctrina index rebuild` regenerates them");
+    } else {
+      applySkillExport(projectRoot, exportPlan);
+      for (const w of exportPlan.writes) console.log(c.green("export ") + ` ${w.rel}`);
+      for (const r of exportPlan.removes) console.log(c.green("removed") + ` ${r} (its skill is gone)`);
+    }
+  }
+
   if (state.ok) {
     console.log(c.green("ok") + " index.json matches the tree (nothing to do)");
     return 0;
@@ -131,6 +149,11 @@ Subcommands:
                     both, because the index is derived from the whole tree.
                     Exits 0 when nothing relevant is staged.
 
+Every rebuild also exports .doctrina/skills/ as SKILL.md folders where the
+agents discover skills on their own: .agents/skills/ (Cursor, Codex) and,
+with the claude adapter installed, .claude/skills/. The exports are marked
+as generated; edit the source. Under --check a stale export is a note only.
+
 Fields with no on-disk source (project name, framework_version, product
 metadata) are carried over from the existing index.
 `;

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";
@@ -14,6 +15,7 @@ import { flagBool, flagString, flagGivenWithoutValue } from "../lib/args.js";
 import { c } from "../lib/colors.js";
 import { EXIT } from "../lib/exit-codes.js";
 import { ask, isInteractive } from "../lib/prompt.js";
+import { mergeJson } from "../lib/adapters.js";
 import { looksLikePath, writeIntakeFile, printBootstrapPlaybook, warnIfThinIntake, nextStepAfterInit } from "../lib/intake-model.js";
 
 const SUPPORTED_AGENTS = [
@@ -40,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();
 
@@ -409,6 +420,20 @@ function installAdapter(templatesDir, projectRoot, agent, tokens, opts) {
       ...tokens,
       AGENTS_MD_PATH: adapterAgentsMdRelativePath(entry.relativePath),
     };
+    // A shared settings file the project already has (`.claude/settings.json`)
+    // is merged, never overwritten (change 0211) — the same rule `adapter add`
+    // follows, so `init` in an existing repository keeps the user's keys.
+    const dest = path.join(projectRoot, entry.relativePath.replace(/\.template$/, ""));
+    if (dest.endsWith(".json") && isFile(dest)) {
+      try {
+        const merged = mergeJson(JSON.parse(read(dest)), JSON.parse(substitute(entry.body, adapterTokens)));
+        write(dest, JSON.stringify(merged, null, 2) + "\n", { force: true });
+        console.log(c.green(`adapter[${agent}]`) + ` ${relPath(projectRoot, dest)} (merged)`);
+      } catch {
+        console.log(c.yellow(`adapter[${agent}]`) + ` ${relPath(projectRoot, dest)} left alone (not valid JSON)`);
+      }
+      continue;
+    }
     const written = materialiseEntry(entry, projectRoot, adapterTokens, opts);
     console.log(c.green(`adapter[${agent}]`) + ` ${relPath(projectRoot, written)}`);
   }
@@ -439,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

@@ -10,6 +10,9 @@ import { today } from "../lib/dates.js";
 import { flagBool, flagString } from "../lib/args.js";
 import { c } from "../lib/colors.js";
 import { looksLikePath, markIntakeConverted, printBootstrapPlaybook, warnIfThinIntake, writeIntakeFile } from "../lib/intake-model.js";
+import { inventory, inventoryMarkdown } from "../lib/code-inventory.js";
+import { printPlaybookTemplate } from "../lib/playbook.js";
+import { findWorkspace } from "../lib/workspace.js";
 
 // `init --intake` performs the same operations; they live in
 // lib/intake-model.js so neither command imports out of the other (F7).
@@ -26,7 +29,7 @@ import { EXIT, notADoctrinaProject } from "../lib/exit-codes.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", "force", "converted"], string: ["text"] };
+export const flags = { boolean: ["json", "force", "converted", "from-code"], string: ["text"] };
 
 export async function run(positional, flags) {
   const projectRoot = process.cwd();
@@ -40,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
@@ -72,6 +75,7 @@ export async function run(positional, flags) {
   }
 
   const force = flagBool(flags, "force", false);
+  if (flagBool(flags, "from-code", false)) return intakeFromCode(projectRoot, force);
   const inlineText = flagString(flags, "text");
   const sourceFile = positional[0];
   const intakePath = path.join(projectRoot, ".doctrina", "intake.md");
@@ -91,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;
   }
 
@@ -151,6 +160,48 @@ export async function run(positional, flags) {
 }
 
 
+// An existing codebase becomes specs (change 0221). The intake is the code
+// INVENTORY — facts read from manifests and file counts — and the playbook
+// asks the agent to describe what the system does today, leaving what the
+// code cannot tell to the human as open questions.
+function intakeFromCode(projectRoot, force) {
+  const intakePath = path.join(projectRoot, ".doctrina", "intake.md");
+  if (exists(intakePath)) {
+    const status = (listHeader(read(intakePath), "Status") ?? "pending").toLowerCase();
+    if (status === "converted") {
+      console.error(c.red("error:") + " the intake is already converted — the specs are the source of truth now");
+      console.error(c.gray("hint: ") + "a change of behaviour: `doctrina work \"<prompt>\"`");
+      return EXIT.PRECONDITION;
+    }
+    if (!force) {
+      console.error(c.red("error:") + ` ${relPath(projectRoot, intakePath)} already exists (pass --force to replace it with the code inventory)`);
+      return EXIT.PRECONDITION;
+    }
+  }
+  const name = projectName(projectRoot);
+  const inv = inventory(projectRoot);
+  writeIntakeFile(projectRoot, {
+    body: inventoryMarkdown(inv, name),
+    source: "code inventory (`doctrina intake --from-code`)",
+    projectName: name, date: today(), force: true,
+  });
+  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
+      ? `\n10. This project belongs to the workspace at ${ws.dir} — confirm it reads\n    ready: ${c.cyan("doctrina workspace list")}, and commit the workspace.`
+      : "",
+  });
+}
+
 export const help = `
 Usage: doctrina intake [<file>] [--text "<description>"] [--force]
 
@@ -168,11 +219,17 @@ Forms:
                                       existing pending intake
   doctrina intake --converted         Close the bootstrap: flip the stored
                                       intake's Status to converted
+  doctrina intake --from-code         An EXISTING codebase: store its code
+                                      inventory as the intake and print the
+                                      absorb playbook
 
 Options:
   --text "<description>"   Inline description instead of a file
   --force                  Overwrite an existing .doctrina/intake.md; with
                            --converted, convert although validate fails
+  --from-code              Inventory the code (stack, tests, CI, env names,
+                           candidate areas, build commands) instead of a
+                           description; --force replaces a pending intake
   --converted              Mark the stored intake converted (ends the
                            bootstrap; nothing else writes that header).
                            Refuses (exit 1) while validate reports an error