doctrina-cli 0.18.0 → 0.21.0

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();
   }
@@ -98,6 +113,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 +158,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 +167,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 +223,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 +253,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/next.js

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

package/src/commands/prime.js

@@ -1,11 +1,16 @@
 // @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, 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";
+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 +27,125 @@ 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)) {
+    // 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;
+  }
+  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 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)), ...workspaceLines(projectRoot), "", ...pulse(openChanges(projectRoot), recentlyClosed(projectRoot, { limit: 1 }))]
+      .join("\n").replace(/\x1b\[[0-9;]*m/g, "").slice(0, HOOK_MAX_CHARS);
+    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");
+  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 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(as === "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 +158,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/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);
@@ -102,11 +118,19 @@ export async function run(_positional, flags) {
     all.filter((f) => /(^|\/)\.doctrina\/specs\/[^/]+\/spec\.md$/.test(f.replace(/\\/g, "/")))
       .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/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

package/src/commands/status.js

@@ -11,6 +11,7 @@ import { renderView, VIEWS } from "../lib/views.js";
 import { draftAgentChangelog, renderDraft } from "../lib/agent-changelog.js";
 import { cliVersion } from "../lib/version.js";
 import { suggest } from "../lib/suggest.js";
+import { contextRouting, workspaceActions, workspaceFindings, workspaceHandoff, workspaceRootAt, workspaceSnapshot, workspaceStatus } from "../lib/workspace-view.js";
 
 // One-glance project health (review 2026-06-27 passive-user feature #1): a
 // dashboard that answers "where do things stand?" in a single read, so neither
@@ -38,6 +39,8 @@ const STATUS_VIEWS = [...VIEWS, "agent-changelog"];
 
 export async function run(_positional, flags) {
   const projectRoot = process.cwd();
+  const wsRoot = workspaceRootAt(projectRoot);
+  if (wsRoot) return workspaceStatusView(wsRoot, flags);
   if (!exists(path.join(projectRoot, ".doctrina"))) {
     throw notADoctrinaProject();
   }
@@ -90,6 +93,9 @@ signals (index drift, framework stamp, coverage %, trace anchors, whether
 verify is configured) and the artifact counts (specs by implementation
 state, open changes, decisions, skills). Read-only; always exits 0.
 
+At a workspace root it prints the workspace instead: projects ready,
+pending and missing, open changes, deliveries open and closed, tools.
+
 Flags:
   --view <name>   Render a different shape of the same snapshot:
                     dashboard  the default one-glance health board
@@ -116,3 +122,25 @@ It is a fast summary, not the authoritative gate: run \`doctrina validate\`
 and \`doctrina verify\` for the full structural and build checks, and
 \`doctrina next\` for the recommended next action.
 `;
+
+// At a workspace root: one glance at the workspace (change 0230).
+function workspaceStatusView(wsRoot, flags) {
+  const snap = workspaceSnapshot(wsRoot);
+  const st = workspaceStatus(snap);
+  if (flagBool(flags, "json", false)) {
+    emitJson("status", { workspace: wsRoot, ...st });
+    return 0;
+  }
+  console.log(c.bold(`Doctrina workspace "${st.name}"`) + c.gray(` — ${wsRoot}`));
+  console.log("");
+  console.log(`Projects    ${st.ready}/${st.projects} ready` + (st.pending.length ? c.yellow(` · pending: ${st.pending.join(", ")}`) : "")
+    + (st.missing.length ? c.red(` · missing: ${st.missing.join(", ")}`) : "") + ` · ${st.openChanges} open change${st.openChanges === 1 ? "" : "s"}`);
+  console.log(`Deliveries  ${st.deliveries.open} open · ${st.deliveries.closed} closed`);
+  console.log(`Tools       ${st.tools} declared`);
+  const first = workspaceActions(snap)[0];
+  if (first) {
+    console.log("");
+    console.log(c.gray("next: ") + `${first.text} — ` + c.cyan(first.command));
+  }
+  return 0;
+}

package/src/commands/upgrade.js

@@ -9,6 +9,10 @@ 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 { applyAdapterMigration, planAdapterMigration } from "../lib/adapters.js";
+import { projectName } from "../lib/project.js";
+import { relinkShadow, shadowRootOf } from "../lib/workspace.js";
 import { collectFindings } from "../lib/templates-model.js";
 import * as templates from "./templates.js";
 import * as validate from "./validate.js";
@@ -74,6 +78,13 @@ 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);
+  // Adapter files that moved (change 0238): Cursor's slash commands became skills.
+  const movePlan = planAdapterMigration(projectRoot, { PROJECT_NAME: projectName(projectRoot), PROJECT_DESCRIPTION: "", DATE: today() }, shadowRootOf(projectRoot) ?? 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 +92,28 @@ 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;
+      }
+    }
+    const moves = movePlan.writes.length + movePlan.removes.length;
+    if (moves > 0) {
+      if (writeMode) {
+        const gone = applyAdapterMigration(shadowRootOf(projectRoot) ?? projectRoot, movePlan);
+        relinkShadow(projectRoot, gone);
+        console.log(c.green("moved  ") + ` ${movePlan.writes.length} adapter file${movePlan.writes.length === 1 ? "" : "s"} to the skills the agent reads now` +
+          (movePlan.removes.length ? `, ${movePlan.removes.length} retired cop${movePlan.removes.length === 1 ? "y" : "ies"} removed` : ""));
+      } else {
+        console.log(c.yellow("would  ") + `move ${movePlan.removes.length || movePlan.writes.length} Cursor command${(movePlan.removes.length || movePlan.writes.length) === 1 ? "" : "s"} to .cursor/skills/ (Cursor reads skills now)`);
+        pending += 1;
+      }
+    }
+    for (const rel of movePlan.kept) console.log(c.yellow("kept   ") + ` ${rel} — edited since install; its skill replaces it, so move your edits and remove it`);
     if (!drifted && !staleStamp) {
       console.log(c.green("ok") + " index.json matches the tree and the stamp is current");
     } else if (writeMode) {

package/src/commands/validate.js

@@ -7,6 +7,7 @@ import { c } from "../lib/colors.js";
 import { emitJson } from "../lib/json-out.js";
 import { notADoctrinaProject } from "../lib/exit-codes.js";
 import { collectValidation } from "../lib/validation-model.js";
+import { contextRouting, workspaceActions, workspaceFindings, workspaceHandoff, workspaceRootAt, workspaceSnapshot, workspaceStatus } from "../lib/workspace-view.js";
 
 // The structural gate. The checks themselves live in lib/validation-model.js
 // so a driver can ASK for them instead of spawning this binary and parsing
@@ -27,6 +28,19 @@ export async function run(_positional, flags) {
   // Outside a Doctrina project this is a PRECONDITION, not a pile of
   // gate failures about missing files: the remedy is `doctrina init`,
   // not editing artifacts that do not exist yet (C7).
+  // At a workspace root: the workspace's own integrity — registry, shadow
+  // links, deliveries (change 0230). Each project validates inside itself.
+  const wsRoot = workspaceRootAt(projectRoot);
+  if (wsRoot) {
+    const { errors, warnings } = workspaceFindings(workspaceSnapshot(wsRoot));
+    for (const e of errors) console.log(c.red("error: ") + e);
+    for (const w of warnings) console.log(c.yellow("warn:  ") + w);
+    console.log("");
+    console.log(errors.length === 0
+      ? c.green("ok") + ` the workspace is consistent${warnings.length ? ` (${warnings.length} warning${warnings.length === 1 ? "" : "s"})` : ""} — each project validates inside itself: \`cd <path> && doctrina validate\``
+      : c.red("fail") + ` ${errors.length} workspace error${errors.length === 1 ? "" : "s"}`);
+    return errors.length > 0 || (flagBool(flags, "strict", false) && warnings.length > 0) ? 1 : 0;
+  }
   if (!isDir(path.join(projectRoot, ".doctrina"))) throw notADoctrinaProject();
 
   const { errors, warnings, fixes } = collectValidation(projectRoot, {
@@ -82,6 +96,10 @@ Run schema, artifact-existence, and structural checks against the
 .doctrina/ tree in the current working directory. Exits 0 if no errors
 (warnings allowed), 1 otherwise. With --strict, a warning fails it too.
 
+At a workspace root it checks the workspace instead — registered
+projects and their dependencies, shadow links, deliveries — and leaves
+each project's validation to \`cd <path> && doctrina validate\`.
+
 Two structural checks worth naming:
 
   Pipeline    a spec's optional "### Pipeline" block declares ordered

package/src/commands/verify.js

@@ -5,6 +5,7 @@ import { readdirSync } from "node:fs";
 import { wantsJson } from "../lib/json-out.js";
 import { spawn, spawnSync } from "node:child_process";
 import { exists, isDir, isFile, read, write, relPath } from "../lib/fs-ops.js";
+import { inventory } from "../lib/code-inventory.js";
 import { flagBool, flagString } from "../lib/args.js";
 import { today } from "../lib/dates.js";
 import { c } from "../lib/colors.js";
@@ -38,6 +39,16 @@ const STARTER = {
   ],
 };
 
+const SEEDED_COMMENT =
+  "doctrina verify runs each check below, in order, through your shell. " +
+  "These were seeded from the project's own manifests by the code " +
+  "inventory — confirm each one runs what its name says, and remove or add " +
+  "checks until this file is the project's executable definition of 'the " +
+  "code actually works'. A non-zero exit fails the gate. A check may add an " +
+  "\"expect\" block — {\"fail_if_output_matches\": \"<regex>\"} and/or " +
+  "{\"require_output_matches\": \"<regex>\"} — so that a run which exits 0 " +
+  "having executed NOTHING fails the gate instead of passing it.";
+
 // 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).
@@ -69,9 +80,24 @@ export async function run(_positional, flags) {
       console.error(c.red("error:") + ` ${CONFIG_REL} already exists (pass --force to overwrite)`);
       return 1;
     }
-    write(configPath, JSON.stringify(STARTER, null, 2) + "\n", { force: true });
-    console.log(c.green("created") + ` ${CONFIG_REL}`);
-    console.log(c.gray("Edit the `checks` array with your real commands, then run `doctrina verify`."));
+    // Seeded from the code inventory when it found the project's own build
+    // and test commands (change 0228): the absorb playbook says "declare the
+    // build gate from the inventory's candidate commands", and the inventory
+    // lists them under that heading — while --init wrote `exit 1` anyway,
+    // leaving the agent to copy by hand what the CLI had just read. With no
+    // candidate the starter stays fail-closed: a gate nobody declared must
+    // not pass.
+    // A check that belongs to one unit of a monorepo runs there (`cwd`).
+    const seeded = inventory(projectRoot).checks.map((ch) => ({ name: ch.name, run: ch.command, ...(ch.cwd ? { cwd: ch.cwd } : {}) }));
+    const config = seeded.length > 0
+      ? { ...STARTER, $comment: SEEDED_COMMENT, checks: seeded }
+      : STARTER;
+    write(configPath, JSON.stringify(config, null, 2) + "\n", { force: true });
+    console.log(c.green("created") + ` ${CONFIG_REL}` +
+      (seeded.length > 0 ? c.gray(` — seeded from the code inventory: ${seeded.map((s) => s.cwd ? `${s.run} (in ${s.cwd}/)` : s.run).join(", ")}`) : ""));
+    console.log(c.gray(seeded.length > 0
+      ? "Confirm each check runs what its name says (add an \"expect\" block where a run could execute nothing), then run `doctrina verify`."
+      : "Edit the `checks` array with your real commands, then run `doctrina verify`."));
     return 0;
   }
 
@@ -488,7 +514,9 @@ copy accumulates for the match. An "expect" pattern that is not a valid
 regular expression fails at config time, not silently.
 
 Flags:
-  --init     Scaffold a starter ${CONFIG_REL} (refuses to overwrite without --force)
+  --init     Scaffold a starter ${CONFIG_REL} (refuses to overwrite without --force):
+             the build and test commands the code inventory finds in the
+             project's manifests, or a fail-closed example when it finds none
   --list     Print the configured checks without running them
   --clean    Don't run checks; lint the project's package.json files for
              reproducibility footguns (entry points in a build dir with no