doctrina-cli 0.20.0 → 0.22.0

package/src/commands/init.js

@@ -1,13 +1,16 @@
 // @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";
 import {
-  surfaceBlock, findSurfaceBlock, agentChangelogBlock, findAgentChangelogBlock,
+  surfaceBlock, findSurfaceBlock, agentChangelogBlock, findAgentChangelogBlock, SURFACE_PROFILES,
 } from "../lib/commands.js";
 import * as idx from "../lib/index-json.js";
 import { scaffoldConfig } from "../lib/config.js";
+import { applyPreset, describePreset, planPreset, readPreset } from "../lib/preset.js";
+import { deriveIndex } from "../lib/scan.js";
 import { today } from "../lib/dates.js";
 import { cliVersion } from "../lib/version.js";
 import { flagBool, flagString, flagGivenWithoutValue } from "../lib/args.js";
@@ -30,17 +33,27 @@ const SUPPORTED_AGENTS = [
   "devin",
   "factory",
   "jules",
+  "kiro",
 ];
 
 export const flags = {
   boolean: ["json", "force", "non-interactive", "overwrite-content"],
-  string: ["project-name", "project-description", "agent", "intake", "intake-text", "from", "date"],
+  string: ["project-name", "project-description", "agent", "intake", "intake-text", "from", "date", "surface", "preset"],
 };
 
 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();
 
@@ -132,6 +145,30 @@ export async function run(_positional, flags) {
     }
   }
 
+  // Which commands AGENTS.md lists (change 0251). A new project is born with
+  // the session loop only — `core` — and the rest one `--help` away; the
+  // choice is written into config.json, where `upgrade` reads it.
+  // The organisation's preset (change 0253), read BEFORE anything is
+  // written: a folder that is not one stops the init with nothing scaffolded.
+  let preset = null;
+  if (flags.has("preset")) {
+    try {
+      const dir = flagString(flags, "preset");
+      if (!dir) throw new Error("--preset needs the preset's folder");
+      preset = readPreset(dir);
+    } catch (err) {
+      console.error(c.red("error:") + ` ${/** @type {Error} */ (err).message}`);
+      return 2;
+    }
+  }
+  // The preset's surface is the default when the flag names none: the block
+  // is generated once, from the profile the project will keep.
+  const surface = flagString(flags, "surface") ?? preset?.config.surface ?? "core";
+  if (!SURFACE_PROFILES.includes(surface) || flagGivenWithoutValue(flags, "surface")) {
+    console.error(c.red("error:") + ` --surface takes ${SURFACE_PROFILES.join(" or ")}${flagGivenWithoutValue(flags, "surface") ? "" : ` (got "${surface}")`}`);
+    return 2;
+  }
+
   let agentSelector = flagString(flags, "agent");
   // Interactive wizard step: when no --agent was given and we are on a real
   // terminal, offer the adapter install instead of silently skipping it —
@@ -192,7 +229,7 @@ export async function run(_positional, flags) {
   // if the static template lags a release (ADR 0015).
   const agentsTemplatePath = path.join(templatesDir, "AGENTS.md.template");
   const agentsTemplateBody = read(agentsTemplatePath);
-  const projectAgents = refreshSurfaceBlock(substitute(agentsTemplateBody, tokens));
+  const projectAgents = refreshSurfaceBlock(substitute(agentsTemplateBody, tokens), surface);
 
   // --force used to mean "overwrite everything", which made it a content
   // shredder: the only way to add an adapter to an existing project was
@@ -275,11 +312,21 @@ export async function run(_positional, flags) {
   {
     const dest = path.join(doctrinaDir, "config.json");
     if (!isFile(dest) || force) {
-      write(dest, scaffoldConfig(), { force });
+      write(dest, scaffoldConfig({ surface }), { force });
       console.log(c.green("created") + ` ${relPath(projectRoot, dest)}`);
     }
   }
 
+  // The preset, over the scaffold: what it adds is indexed with the rest.
+  if (preset) {
+    const plan = planPreset(projectRoot, preset);
+    applyPreset(projectRoot, preset, plan);
+    for (const line of describePreset(preset, plan, true)) console.log(line);
+    const derived = deriveIndex(projectRoot, idx.load(projectRoot));
+    derived.last_updated = date;
+    idx.save(projectRoot, derived);
+  }
+
   // Adapters
   if (agentSelector) {
     const agents = agentSelector === "all" ? SUPPORTED_AGENTS : [agentSelector];
@@ -374,10 +421,10 @@ function normaliseScaffold(text) {
 // Replace the template's doctrina:surface span with the one generated from
 // the running CLI's catalog; pass the text through untouched when the
 // template carries no markers (older custom templates).
-function refreshSurfaceBlock(text) {
+function refreshSurfaceBlock(text, profile = "full") {
   const block = findSurfaceBlock(text);
   if (!block) return text;
-  let out = text.slice(0, block.start) + surfaceBlock() + text.slice(block.end);
+  let out = text.slice(0, block.start) + surfaceBlock(profile) + text.slice(block.end);
 
   // The agent-facing changelog is version-specific, so it is GENERATED at
   // init like the surface block — not carried in the template. Writing it
@@ -443,8 +490,15 @@ Scaffold AGENTS.md and the .doctrina/ skeleton in the current directory.
 Options:
   --project-name <name>          Override the project name (default: basename of cwd)
   --project-description <text>   One-sentence description
+  --surface core|full            Which commands AGENTS.md lists: core (default) is the session
+                                 loop, with the rest deferred to \`doctrina --help\`; full lists
+                                 every command. Stored in .doctrina/config.json.
+  --preset <dir>                 Lay an organisation's preset over the scaffold: a folder with
+                                 preset.json (name, config) and optional templates/, decisions/,
+                                 skills/ and verify.json. Additive — see \`doctrina upgrade --preset\`
+                                 for a project that already exists.
   --agent <name>                 Install adapter for one agent
-                                 (claude|codex|cursor|copilot|gemini|aider|windsurf|continue|amp|devin|factory|jules|all)
+                                 (claude|codex|cursor|copilot|gemini|aider|windsurf|continue|amp|devin|factory|jules|kiro|all)
   --intake <file>                Full project description; stored verbatim at .doctrina/intake.md,
                                  used to derive the one-line description when absent, and the
                                  bootstrap playbook is printed inline — no second command
@@ -454,6 +508,8 @@ Options:
   --from <path>                  Local conventions directory; if it contains AGENTS.md and/or
                                  .doctrina/product.md, the content is folded into the new project
   --date <YYYY-MM-DD>            Override the system date
-  --force                        Overwrite existing files
+  --force                        Overwrite existing files that are still untouched scaffolds;
+                                 also init a second clone of a repository a workspace shadows
+  --overwrite-content            With --force, also overwrite an authored AGENTS.md or product.md
   --non-interactive              Fail instead of prompting for missing values
 `;

package/src/commands/intake.js

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

package/src/commands/metrics.js

@@ -12,6 +12,8 @@ import { notADoctrinaProject } from "../lib/exit-codes.js";
 import { USAGE_ENV, summarise } from "../lib/usage.js";
 import { OPERATIONS } from "../lib/commands.js";
 import { REEDIT_WINDOW_DAYS, sinceWindow, computeSnapshot, parseLog, readSeries, latestSnapshot, trend, round } from "../lib/metrics-model.js";
+import { workspaceRootAt, workspaceSnapshot } from "../lib/workspace-view.js";
+import { cdThen } from "../lib/shell.js";
 
 // Local-only adoption metrics derived from git history. No network calls,
 // no telemetry: the numbers stay in the repository, versioned like any
@@ -24,6 +26,19 @@ export const flags = { boolean: ["json", "save", "commands", "trend"], string: [
 
 export async function run(_positional, flags) {
   const projectRoot = process.cwd();
+  // At the workspace root (change 0235): adoption is measured per repository;
+  // the deliveries' own lead time is `delivery list`.
+  const wsRoot = workspaceRootAt(projectRoot);
+  if (wsRoot && !flagBool(flags, "commands", false)) {
+    const snap = workspaceSnapshot(wsRoot);
+    console.log(c.bold("Doctrina metrics") + c.gray(` — workspace "${snap.ws.name}"`));
+    console.log("");
+    console.log(`Deliveries  ${snap.open.length} open · ${snap.deliveries.length - snap.open.length} closed — lead time per delivery: ${c.cyan("doctrina delivery list")}`);
+    console.log("");
+    console.log("Adoption is measured in each repository:");
+    for (const p of snap.projects.filter((x) => x.state !== "missing")) console.log("  " + c.cyan(cdThen(p.project.path, "doctrina metrics")));
+    return EXIT.OK;
+  }
   if (!exists(path.join(projectRoot, ".doctrina"))) {
     throw notADoctrinaProject();
   }
@@ -39,7 +54,7 @@ export async function run(_positional, flags) {
   if (flagBool(flags, "trend", false)) return printTrend(projectRoot);
   // The window is the invocation's: refused the same with or without history.
   const sinceRaw = flagString(flags, "since", "90");
-  const since = sinceWindow(sinceRaw);
+  const since = sinceWindow(sinceRaw ?? "90");
   if (since === null) {
     console.error(c.red("error:") + ` --since expects a day count, a date (YYYY-MM-DD) or "<n> <unit>s ago", got "${sinceRaw}"`);
     console.error(c.gray("hint: ") + "examples: --since 30 · --since 2026-01-01 · --since \"3 months ago\"");

package/src/commands/next.js

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

package/src/commands/onboard.js

@@ -0,0 +1,113 @@
+// @ts-check
+import process from "node:process";
+import { flagBool } from "../lib/args.js";
+import { c } from "../lib/colors.js";
+import { emitJson } from "../lib/json-out.js";
+import { EXIT } from "../lib/exit-codes.js";
+import { TRACKS } from "../lib/triage-model.js";
+import { firstTaskCandidates, onboardState, onboardSteps, tourLines } from "../lib/onboard.js";
+
+// `onboard` walks the whole cycle once, on this repository (change 0256).
+// It reads where the project stands and prints the walk; the agent is the
+// guide and the human the one being shown. It writes nothing and works
+// before `init`, because the first step is the install.
+
+export const jsonNative = true;
+
+export const flags = { boolean: ["json"], string: [] };
+
+export async function run(_positional, cmdFlags) {
+  const projectRoot = process.cwd();
+  const state = onboardState(projectRoot);
+  const { steps, current } = onboardSteps(state);
+  const wantsCandidates = current === "first-task" && state.installed;
+  const candidates = wantsCandidates ? firstTaskCandidates(projectRoot) : [];
+
+  if (flagBool(cmdFlags, "json", false)) {
+    emitJson("onboard", {
+      current,
+      steps: steps.map((s) => ({ id: s.id, title: s.title, done: s.done, run: s.run, ask: s.ask || null })),
+      candidates,
+      closed: state.closed,
+    });
+    return EXIT.OK;
+  }
+
+  console.log(c.bold("Doctrina onboarding") + c.gray(" — the whole cycle once, on this repository"));
+  console.log("");
+  console.log("You are the guide. Do the step marked →, say in one sentence what it did,");
+  console.log("stop where it says ASK, then run `doctrina onboard` again: it reads the tree.");
+  console.log("");
+  steps.forEach((s, i) => {
+    const mark = s.done ? c.green("✓") : (s.id === current ? c.cyan("→") : " ");
+    console.log(`  ${mark} ${i + 1}. ${s.done ? s.title.padEnd(31) + c.gray(s.evidence) : s.title}`);
+  });
+  console.log("");
+
+  if (current === null) {
+    console.log(c.bold("The cycle has run here") + c.gray(` — ${state.closed} change${state.closed === 1 ? "" : "s"} closed. For someone new to the project:`));
+    console.log("");
+    for (const line of tourLines(state)) console.log(`  ${line}`);
+    console.log("");
+    printTracks();
+    return EXIT.OK;
+  }
+
+  const at = steps.findIndex((s) => s.id === current);
+  const step = steps[at];
+  console.log(c.bold(`Step ${at + 1} — ${step.title}`));
+  console.log(`  ${c.gray("Tell the human:")} ${step.say}`);
+  if (wantsCandidates) {
+    console.log("");
+    if (candidates.length === 0) {
+      console.log(c.gray("  No candidate stands out in this repository (every criterion cites proof, no TODO in the code)."));
+    } else {
+      console.log("  Candidates read from this repository:");
+      for (const cand of candidates) console.log(`    - ${cand.where.padEnd(24)} ${cand.text}`);
+    }
+  }
+  const after_ = "askAfter" in step && step.askAfter === true;
+  if (step.ask && !after_) console.log(`  ${c.yellow("ASK")} the human ${step.ask}`);
+  console.log(step.ask && !after_ ? "  Then run:" : "  Run:");
+  for (const cmd of step.run) console.log(`    ${c.cyan(cmd)}`);
+  if (step.ask && after_) console.log(`  Then ${c.yellow("ASK")} the human ${step.ask}`);
+  if (current === "first-task") {
+    console.log("");
+    printTracks();
+  }
+  const after = steps[at + 1];
+  if (after) console.log(c.gray(`\nAfter it: step ${at + 2}, ${after.title.toLowerCase()} — \`doctrina onboard\` shows it.`));
+  return EXIT.OK;
+}
+
+function printTracks() {
+  console.log(c.gray("Not every edit is a change — the tracks, by what a request changes:"));
+  for (const t of TRACKS) console.log(c.gray(`  ${t.id.padEnd(7)} ${t.changes}`));
+}
+
+export const help = `
+Usage: doctrina onboard [--json]
+
+Walk the whole Doctrina cycle once, on this repository. Prints the six
+steps — install, describe the project, pick a first task and open it,
+write the delta and the tasks, implement and prove, close — each marked
+done when the tree says so, and for the first one that is not: what to
+tell the human, where to stop and ask, and the commands to run. Run it
+again after each step; it stores nothing and reads the tree every time.
+
+At "pick a first task" it lists candidates read from the repository: an
+acceptance criterion that cites no proof (or a proof that is missing),
+then a TODO or FIXME left in the code. They are suggestions; the human
+chooses, or names a task of their own.
+
+In a project that already closed a change, every step is done and it
+prints the tour for someone new to the project instead: the commands to
+read the project with, and the last closed change as a worked example.
+
+It works before \`doctrina init\` (the first step is the install) and
+writes nothing.
+
+Options:
+  --json    Machine-readable: the steps with their state, the current
+            step, and the first-task candidates
+`;

package/src/commands/prime.js

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

package/src/commands/review.js

@@ -6,6 +6,7 @@ import { exists, isDir, isFile, read } from "../lib/fs-ops.js";
 import { flagBool, flagString } from "../lib/args.js";
 import { c } from "../lib/colors.js";
 import { rankCapabilitiesByDiff } from "../lib/work-model.js";
+import { applyOps, extractOps } from "../lib/spec-ops.js";
 import { readLedger, churnByCapability } from "../lib/ledger.js";
 import { changedFiles, windowCutoff, historyState, refExists } from "../lib/git.js";
 import { dependentsOf, deltaCapabilities } from "../lib/scan.js";
@@ -67,6 +68,8 @@ export async function run(_positional, flags) {
   const changeId = flagString(flags, "change");
   /** @type {Set<string> | null} */
   let changeCaps = null;
+  /** @type {Map<string, string>} the change's delta text per capability */
+  const pending = new Map();
   if (changeId !== undefined) {
     const refused = refuseChangeRef(changeId);
     if (refused !== null) return refused;
@@ -76,6 +79,19 @@ export async function run(_positional, flags) {
       return EXIT.USAGE;
     }
     changeCaps = new Set(deltaCapabilities(changeDir));
+    // The specs as this change leaves them: an ops delta applied in memory,
+    // as `change check` dry-runs it; a delta without ops (a manual merge)
+    // read beside the spec, since nothing can apply it.
+    for (const cap of changeCaps) {
+      const delta = path.join(changeDir, "specs", cap, "delta.md");
+      const spec = path.join(projectRoot, ".doctrina", "specs", cap, "spec.md");
+      if (!isFile(delta)) continue;
+      const deltaText = read(delta);
+      const current = isFile(spec) ? read(spec) : "";
+      const ops = extractOps(deltaText);
+      const after = ops.length > 0 ? applyOps(current, ops) : null;
+      pending.set(cap, after && after.errors.length === 0 ? after.text : `${current}\n${deltaText}`);
+    }
   }
 
   const { all, sourceFiles } = reviewScope(projectRoot, against);
@@ -100,13 +116,21 @@ export async function run(_positional, flags) {
   //    capability whose spec.md itself changed.
   const specChanged = new Set(
     all.filter((f) => /(^|\/)\.doctrina\/specs\/[^/]+\/spec\.md$/.test(f.replace(/\\/g, "/")))
-      .map((f) => f.replace(/\\/g, "/").match(/\.doctrina\/specs\/([^/]+)\/spec\.md$/)[1]),
+      .map((f) => f.replace(/\\/g, "/").match(/\.doctrina\/specs\/([^/]+)\/spec\.md$/)?.[1] ?? ""),
   );
-  const ranked = rankCapabilitiesByDiff(projectRoot, sourceFiles, { limit: Infinity });
+  const ranked = rankCapabilitiesByDiff(projectRoot, sourceFiles, { limit: Infinity, pending });
   const touched = new Set([...specChanged, ...ranked.map((m) => m.id)]);
   const stale = ranked.map((m) => m.id).filter((id) => !specChanged.has(id) && !changeCaps?.has(id));
+  // Without --change, an OPEN change that carries a delta for the capability
+  // updates its spec at close (fifth audit, change 0236): the bare review
+  // reported "its spec was not updated" for exactly the work a planner had
+  // in flight — the real agent read it as a break and went to fix the spec.
+  const inFlight = changeCaps === null ? openDeltaOwners(projectRoot) : new Map();
   if (changeCaps === null) {
-    for (const id of stale) {
+    for (const id of stale.filter((x) => inFlight.has(x))) {
+      notes.push(`code under capability "${id}" changed; its spec is updated when ${inFlight.get(id)?.join(", ")} closes (\`doctrina review --change <id>\` reviews it as that close does)`);
+    }
+    for (const id of stale.filter((x) => !inFlight.has(x))) {
       breaks.push(`code under capability "${id}" changed, but its spec was not updated — confirm \`.doctrina/specs/${id}/spec.md\` still describes the code (update it, or note why not)`);
     }
   } else if (stale.length > 0) {
@@ -151,7 +175,7 @@ export async function run(_positional, flags) {
   //    file in the change. A review of an adapter change reported
   //    "Capabilities touched: docs" and said nothing about the adapter.
   const orphans = sourceFiles.filter(
-    (f) => rankCapabilitiesByDiff(projectRoot, [f], { limit: 1 }).length === 0,
+    (f) => rankCapabilitiesByDiff(projectRoot, [f], { limit: 1, pending }).length === 0,
   );
   if (orphans.length > 0) {
     const shown = orphans.slice(0, ORPHAN_LIST_LIMIT).map((f) => `\`${f}\``).join(", ");
@@ -274,3 +298,15 @@ from specs that declare no Source.
 Read-only. Exits 0 as a report; with --strict, exits 1 when any hard break
 exists (CI gate). Notes (advisory) never fail the gate.
 `;
+
+/** Capability → the open changes that carry a delta for it. */
+function openDeltaOwners(projectRoot) {
+  const out = new Map();
+  const changes = path.join(projectRoot, ".doctrina", "changes");
+  if (!isDir(changes)) return out;
+  for (const id of readdirSync(changes).sort()) {
+    if (id === "archive" || id.startsWith(".") || !isDir(path.join(changes, id))) continue;
+    for (const cap of deltaCapabilities(path.join(changes, id))) out.set(cap, [...(out.get(cap) ?? []), id]);
+  }
+  return out;
+}

package/src/commands/search.js

@@ -59,8 +59,8 @@ export async function run(positional, flags) {
   for (const cat of categories) {
     const files = cat.file
       ? [path.join(projectRoot, cat.file)].filter(exists)
-      : isDir(path.join(projectRoot, cat.dir))
-        ? walk(path.join(projectRoot, cat.dir)).filter((f) => f.endsWith(".md"))
+      : isDir(path.join(projectRoot, cat.dir ?? ""))
+        ? walk(path.join(projectRoot, cat.dir ?? "")).filter((f) => f.endsWith(".md"))
         : [];
 
     const findings = [];

package/src/commands/skill.js

@@ -455,7 +455,8 @@ knowledge loaded only when relevant.
 
 Subcommands:
   new <name>    Scaffold a new skill from the template and index
-                it. Name must match [a-z][a-z0-9-]*.
+                it. Name must match [a-z][a-z0-9-]*. --force
+                overwrites an existing skill.
   list          Print one line per skill with name + description.
                 Read-only.
   sync          Copy each skill's frontmatter description into