doctrina-cli 0.18.0 → 0.20.0

package/src/commands/delivery.js

@@ -0,0 +1,238 @@
+// @ts-check
+import process from "node:process";
+import { relPath, write } from "../lib/fs-ops.js";
+import { flagString } from "../lib/args.js";
+import { c } from "../lib/colors.js";
+import { suggest } from "../lib/suggest.js";
+import { 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 {
+  deliveryBlockers, deliveryChanges, deliveryPath, dependencyOrder, listDeliveries, nextDeliveryId,
+  rankProjects, readDelivery, resolveDeliveryId, setDeliveryHeader, daysBetween, recordBlockers,
+} from "../lib/delivery.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"];
+
+export const flags = { boolean: ["json"], string: ["ref", "projects", "date"] };
+
+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"));
+  if (sub === "status") return deliveryStatus(wsDir, ws, id);
+  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 };
+}
+
+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;
+  }
+  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_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) {
+  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;
+  }
+  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)"));
+  console.log("");
+  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}`));
+  }
+  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) {
+  const d = readDelivery(wsDir, id);
+  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}`));
+    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}`));
+    }
+  }
+  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;
+}
+
+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|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>]
+      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>
+      Set the projects (dependencies first) and print the \`work\` line for each.
+  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.
+  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.
+
+<id> is the folder name or its number (\`1\`, \`0001\`).
+`;
+

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

@@ -14,6 +14,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 = [
@@ -409,6 +410,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)}`);
   }

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();
@@ -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");
@@ -151,6 +155,42 @@ 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,
+  });
+  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`);
+  console.log("");
+  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.`
+      : "",
+  });
+  return EXIT.OK;
+}
+
 export const help = `
 Usage: doctrina intake [<file>] [--text "<description>"] [--force]
 
@@ -168,11 +208,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

package/src/commands/metrics.js

@@ -98,6 +98,9 @@ export async function run(_positional, flags) {
       printDelta("revert rate", previous.revert_rate, snapshot.revert_rate);
       printDelta("fix share", previous.fix_share, snapshot.fix_share);
       printDelta(`${REEDIT_WINDOW_DAYS}-day re-edit rate`, previous.reedit_rate, snapshot.reedit_rate);
+      if (typeof previous.change_adherence === "number" && typeof snapshot.change_adherence === "number") {
+        printDelta("commits with a change", previous.change_adherence, snapshot.change_adherence);
+      }
     }
   }
   return 0;
@@ -140,6 +143,7 @@ const LABELS = {
   revert_rate: "revert rate",
   fix_share: "fix share",
   reedit_rate: `${REEDIT_WINDOW_DAYS}-day re-edit rate`,
+  change_adherence: "commits with a change",
 };
 
 function printReport(s) {
@@ -148,6 +152,10 @@ function printReport(s) {
   console.log(`fix-typed commits      ${pct(s.fix_share)} of commits (Conventional Commits "fix")`);
   console.log(`${s.reedit_window_days}-day re-edit rate     ${pct(s.reedit_rate)} of commits touch a file edited in the prior ${s.reedit_window_days} days`);
   console.log(c.gray("                       (proxy for rework — iterative work also counts)"));
+  if (s.change_adherence !== null && s.change_adherence !== undefined) {
+    console.log(`commits with a change  ${pct(s.change_adherence)} of ${s.code_commits} code commits touched .doctrina/changes/ or named a change`);
+    console.log(c.gray("                       (workflow adherence — a one-line fix may rightly need none)"));
+  }
   if (s.top_churn.length > 0) {
     console.log("");
     console.log("top churn:");
@@ -200,6 +208,20 @@ function commandUsage() {
   for (const [op, n] of used) {
     console.log(`  ${String(n).padStart(5)}  ${c.cyan(op)}`);
   }
+  // The cycle, read off the sample (change 0218): did a change get its read
+  // and its close? A field review found `prime` and `work` used, `context`
+  // and `triage` skipped. Ratios, not verdicts — one context can serve two
+  // works, and a close can be retried.
+  const count = (op) => used.find(([o]) => o === op)?.[1] ?? 0;
+  const works = count("work");
+  if (works > 0) {
+    console.log("");
+    console.log(c.bold("Workflow") + c.gray(` — per \`work\` (${works})`));
+    console.log(`  context  ${(count("context") / works).toFixed(1)}   close  ${(count("close") / works).toFixed(1)}   prime  ${(count("prime") / works).toFixed(1)}`);
+    if (count("context") < works) {
+      console.log(c.gray("  fewer reads than changes: the pack is the spec, `prime` is only the state"));
+    }
+  }
   console.log("");
   console.log(c.gray(`${unused.length} of ${catalog.length} operations never invoked in this sample:`));
   for (let i = 0; i < unused.length; i += 4) {
@@ -216,12 +238,15 @@ export const help = `
 Usage: doctrina metrics [--since <days|date>] [--save] [--commands]
 
 Derive adoption metrics from LOCAL git history: commit count, revert
-count and rate, Conventional-Commit fix share, top-churn files, and a
-${REEDIT_WINDOW_DAYS}-day re-edit proxy rate. No network calls; nothing leaves the repo.
+count and rate, Conventional-Commit fix share, top-churn files, a
+${REEDIT_WINDOW_DAYS}-day re-edit proxy rate, and workflow adherence — the share of
+code commits that carried a change (touched .doctrina/changes/ or named
+one). No network calls; nothing leaves the repo.
 
 Flags:
   --commands         Report which operations were actually invoked, from the
-                     opt-in usage log. Recording is OFF unless DOCTRINA_USAGE_LOG
+                     opt-in usage log, and how many context, close and prime
+                     runs there were per work. Recording is OFF unless DOCTRINA_USAGE_LOG
                      names a file; only the operation is recorded, never
                      arguments, and nothing leaves the machine.
   --since <n|date>   Window: a day count (default 90), a calendar date

package/src/commands/prime.js

@@ -1,11 +1,15 @@
 // @ts-check
 import path from "node:path";
 import process from "node:process";
-import { exists } from "../lib/fs-ops.js";
-import { flagBool } from "../lib/args.js";
-import { notADoctrinaProject } from "../lib/exit-codes.js";
-import { collectSnapshot } from "../lib/snapshot.js";
-import { renderView } from "../lib/views.js";
+import { exists, 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 { flagBool, flagString } from "../lib/args.js";
+import { c } from "../lib/colors.js";
+import { EXIT, notADoctrinaProject } from "../lib/exit-codes.js";
+import { collectSnapshot, openChanges, recentlyClosed } from "../lib/snapshot.js";
+import { renderView, pulse } from "../lib/views.js";
 
 // Session primer: the ~40-line read that orients an agent at the start of a
 // session — where things stand, what the standing rules are, what work is
@@ -22,23 +26,77 @@ import { renderView } from "../lib/views.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", "rules"], string: [] };
+export const flags = { boolean: ["json", "rules", "pulse"], string: ["hook"] };
+
+// What an agent hook accepts on stdout (change 0211). Claude Code adds the
+// plain text of a SessionStart hook to the conversation; Cursor's
+// sessionStart reads `additional_context` from a JSON object. Both cap what
+// they keep — Claude at 10,000 characters — so the primer is cut short of
+// that rather than replaced by a file path the agent is never asked to read.
+const HOOK_AGENTS = ["claude", "cursor"];
+const HOOK_MAX_CHARS = 9000;
 
 export async function run(_positional, flags) {
   const projectRoot = process.cwd();
   if (!exists(path.join(projectRoot, ".doctrina"))) {
+    // At a workspace root the session belongs to the orchestrator (change
+    // 0223): the primer is the workspace's.
+    const found = findWorkspace(projectRoot);
+    if (found && found.via !== "pointer") return primeWorkspace(found.dir, flags);
     throw notADoctrinaProject();
   }
   // --rules: the standing rules in full, which is what the removed
   // `constitution` printed (changes 0049, 0175). The primer names the ADRs and counts the non-goals; this
   // prints both lists, from the same collection, so the two cannot disagree.
+  // --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)) {
+    for (const line of pulse(openChanges(projectRoot), recentlyClosed(projectRoot, { limit: 1 }))) console.log(line);
+    return 0;
+  }
+  if (flags.has("hook")) {
+    const agent = flagString(flags, "hook");
+    if (!agent || !HOOK_AGENTS.includes(agent)) {
+      console.error(c.red("error:") + ` --hook needs one of ${HOOK_AGENTS.join(", ")} (got "${agent ?? ""}")`);
+      return EXIT.USAGE;
+    }
+    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 }))]
+      .join("\n").replace(/\x1b\[[0-9;]*m/g, "").slice(0, HOOK_MAX_CHARS);
+    console.log(agent === "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);
   return 0;
 }
 
+function primeWorkspace(wsDir, flags) {
+  const ws = readWorkspace(wsDir);
+  const open = listDeliveries(wsDir).filter((d) => d.status !== "closed");
+  if (flagBool(flags, "pulse", false)) {
+    console.log(open.length === 0
+      ? "Doctrina workspace: no delivery is open — an item of work across repositories opens one with `doctrina delivery new \"<title>\" --ref <id>`."
+      : open.map((d) => `open delivery: ${d.id} — "${d.title}" (${d.projects.join(", ") || "not routed"}). Name it in your first sentence to the human; \`doctrina delivery status ${d.id}\`.`).join(" "));
+    return 0;
+  }
+  const lines = workspacePrimer(ws, wsDir, open);
+  if (flags.has("hook")) {
+    const agent = flagString(flags, "hook");
+    if (!agent || !HOOK_AGENTS.includes(agent)) {
+      console.error(c.red("error:") + ` --hook needs one of ${HOOK_AGENTS.join(", ")} (got "${agent ?? ""}")`);
+      return EXIT.USAGE;
+    }
+    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);
+    return 0;
+  }
+  for (const line of lines) console.log(line);
+  return 0;
+}
+
 export const help = `
-Usage: doctrina prime
+Usage: doctrina prime [--rules | --pulse | --hook claude|cursor]
 
 Print the session primer: gate digest, standing rules (accepted ADR
 titles + non-goal count), open work with task progress, and the top
@@ -51,6 +109,17 @@ collection of the tree, so they cannot disagree.
   --rules   Print the standing rules in full instead of the primer: every
             accepted ADR and every declared non-goal — what the removed
             \`doctrina constitution\` printed, from the same collection.
+  --pulse   One line for a per-prompt agent hook: the open change(s), or
+            that a request changing behaviour opens one with \`work\`.
+  --hook <agent>
+            The primer plus the pulse, as the agent's session-start hook
+            reads it: plain text for claude, {"additional_context"} JSON
+            for cursor; cut at 9,000 characters. \`doctrina adapter add
+            claude|cursor\` installs the hooks that call these.
+
+At a workspace root (no .doctrina/, a workspace.json) it is the
+orchestrator's primer: the projects and their state, the open deliveries,
+the tools — and with --hook, the workspace's AGENTS.md after it.
 
 Read-only; always exits 0. Deeper reads: \`doctrina context\`,
 \`doctrina why <cap>\`, \`doctrina show <ref>\`.

package/src/commands/upgrade.js

@@ -9,6 +9,7 @@ import { flagBool } from "../lib/args.js";
 import { c } from "../lib/colors.js";
 import { today } from "../lib/dates.js";
 import { notADoctrinaProject } from "../lib/exit-codes.js";
+import { planSkillExport, applySkillExport } from "../lib/skill-export.js";
 import { collectFindings } from "../lib/templates-model.js";
 import * as templates from "./templates.js";
 import * as validate from "./validate.js";
@@ -74,6 +75,11 @@ export async function run(_positional, flags) {
     console.log(c.gray("    fix: ") + (f.remedy ? c.cyan(f.remedy) : c.gray("manual repair — no command can fix this")));
   }
 
+  // The skill exports (change 0212) follow the index: regenerated by the
+  // write, reported by the preview.
+  const exportPlan = planSkillExport(projectRoot);
+  const exportChanges = exportPlan.writes.length + exportPlan.removes.length;
+
   // 3. Index: rebuild from the tree, which also migrates the framework stamp.
   console.log("");
   console.log(c.gray("──── 2/3 index + framework stamp"));
@@ -81,6 +87,15 @@ export async function run(_positional, flags) {
     const current = idx.load(projectRoot);
     const drifted = !indexesMatch(deriveIndex(projectRoot, current), current);
     const staleStamp = (current.framework_version ?? null) !== running;
+    if (exportChanges > 0) {
+      if (writeMode) {
+        applySkillExport(projectRoot, exportPlan);
+        console.log(c.green("export ") + ` ${exportChanges} skill file${exportChanges === 1 ? "" : "s"} where the agents discover skills`);
+      } else {
+        console.log(c.yellow("would  ") + `export ${exportChanges} skill file${exportChanges === 1 ? "" : "s"} where the agents discover skills`);
+        pending += 1;
+      }
+    }
     if (!drifted && !staleStamp) {
       console.log(c.green("ok") + " index.json matches the tree and the stamp is current");
     } else if (writeMode) {