doctrina-cli 0.17.0 → 0.20.0

package/src/commands/context.js

@@ -14,6 +14,7 @@ import { GIT_STATE, historyState, changedFiles } from "../lib/git.js";
 import { terms as queryTerms, relevance } from "../lib/lexicon.js";
 import { notADoctrinaProject, EXIT } from "../lib/exit-codes.js";
 import * as idx from "../lib/index-json.js";
+import { adrDigest, sliceSpec } from "../lib/context-slice.js";
 
 // Materialise the AGENTS.md read order as a command: print the exact
 // context pack for a task, in the order an agent should read it. This is
@@ -72,11 +73,14 @@ export const TIER = { CORE: 0, SPEC: 1, CHANGE: 2, DEPENDENCY: 3, DECISION: 4 };
 // 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", "concat"], string: ["budget", "diff", "for"] };
+export const flags = { boolean: ["json", "concat", "full"], string: ["budget", "diff", "for"] };
 
 export async function run(positional, cmdFlags) {
   const capability = positional[0] ?? null;
   const concat = flagBool(cmdFlags, "concat", false);
+  // --full: the whole text of everything, as before change 0216 — AGENTS.md
+  // repeated, every spec and ADR whole. The lean pack is the default.
+  const full = flagBool(cmdFlags, "full", false);
   const budgetRaw = flagString(cmdFlags, "budget");
   const diffRef = flagString(cmdFlags, "diff");
   const query = flagString(cmdFlags, "for");
@@ -162,6 +166,8 @@ export async function run(positional, cmdFlags) {
       tier: TIER.CORE,
       rank: [],
       degraded: false,
+      /** @type {string | null} */ slice: null,
+      /** @type {string | null} */ digest: null,
       ...extra,
     };
     pack.push(item);
@@ -170,7 +176,10 @@ export async function run(positional, cmdFlags) {
 
   // 1-2. Root rules and product truth — always first. Displayed paths are
   // POSIX strings (path.join would emit backslashes on Windows).
-  if (wanted("AGENTS.md")) pushFile("AGENTS.md", "root rules");
+  // AGENTS.md is not repeated by default (change 0216): every agent this
+  // pack is for loads it already — natively, or through its adapter — and
+  // it cost ~2.5k tokens per pack to say it twice.
+  if (wanted("AGENTS.md") && full) pushFile("AGENTS.md", "root rules");
   if (wanted(".doctrina/product.md")) pushFile(".doctrina/product.md", "product truth");
 
   // 3. The capability spec(s) — the current truth. With a named capability,
@@ -241,6 +250,21 @@ export async function run(positional, cmdFlags) {
     }
   }
 
+  // A spec read for a task — the task's own, and the ones it depends on — is
+  // cut to what the task is about (change
+  // 0216): headers, Purpose, and the requirements and criteria the query
+  // matches, the rest named by count. No query, or nothing matched: whole.
+  if (!full && terms.length > 0) {
+    for (const item of pack) {
+      if ((item.tier !== TIER.CORE && item.tier !== TIER.DEPENDENCY) || !item.rel.startsWith(".doctrina/specs/")) continue;
+      const sliced = sliceSpec(read(path.join(projectRoot, item.rel)), terms, item.rel);
+      if (!sliced) continue;
+      item.slice = sliced.text;
+      item.tokens = estimateTokens(sliced.text);
+      item.note = `${item.note} — sliced: ${sliced.kept} of ${sliced.total} items match`;
+    }
+  }
+
   // 4. Open changes (their proposal, tasks, and deltas) — never
   //    diff-filtered: work in flight is the one thing a resuming agent
   //    cannot reconstruct from anywhere else, so it is always present.
@@ -347,7 +371,7 @@ export async function run(positional, cmdFlags) {
 
     const id = path.basename(f).match(/^(\d{4})-/)?.[1] ?? "0000";
     const title = getTitle(text) ?? path.basename(f, ".md");
-    pushFile(rel, global ? "accepted ADR" : `accepted ADR (${scope.join(", ")})`, {
+    const adrItem = pushFile(rel, global ? "accepted ADR" : `accepted ADR (${scope.join(", ")})`, {
       tier: TIER.DECISION,
       // Best-first, deterministic: an ADR that NAMES this capability outranks
       // an unscoped one — which is DECLARED to belong in every pack — which in
@@ -360,6 +384,13 @@ export async function run(positional, cmdFlags) {
       title,
       summary: adrSummary(text),
     });
+    // A decision as a digest by default (change 0216): its title and the
+    // opening of its Decision — what tells a reader whether it binds the
+    // task. Sixteen whole ADRs were ~22k tokens of the `gates` pack.
+    if (adrItem && !full) {
+      adrItem.digest = adrDigest(text, title, id);
+      adrItem.tokens = estimateTokens(adrItem.digest);
+    }
   }
 
   // 6. Skills are on-demand: list name + description + trigger, never the
@@ -406,7 +437,8 @@ export async function run(positional, cmdFlags) {
     for (const item of kept) {
       console.log(`===== ${item.rel} (${item.note}) =====`);
       console.log("");
-      console.log(item.degraded ? degradedBody(item) : read(path.join(projectRoot, item.rel)).trimEnd());
+      console.log(item.degraded ? degradedBody(item)
+        : item.slice ?? item.digest ?? read(path.join(projectRoot, item.rel)).trimEnd());
       console.log("");
     }
     // Keep the pack pipeable: the budget verdict goes to stderr.
@@ -417,7 +449,7 @@ export async function run(positional, cmdFlags) {
     console.log(c.bold("Context pack") + (capability ? c.gray(` (capability: ${capability})`) : "") + forNote + scope + c.gray(" — read in this order:"));
     console.log("");
     kept.forEach((item, i) => {
-      const mark = item.degraded ? c.yellow(" summary") : "        ";
+      const mark = item.degraded ? c.yellow(" summary") : item.slice ? c.yellow("  sliced") : item.digest ? c.yellow("  digest") : "        ";
       console.log(`${String(i + 1).padStart(2)}. ${c.cyan(item.rel.padEnd(56))} ${String(item.lines).padStart(4)} lines ${c.gray(`~${String(item.tokens).padStart(5)} tok`)}${mark}  ${c.gray(item.note)}`);
     });
     console.log("");
@@ -709,14 +741,21 @@ function changedPaths(projectRoot, ref) {
 
 export const help = `
 Usage: doctrina context [<capability>] [--for "<task>"] [--concat]
-                        [--budget <tokens>] [--diff <ref>]
+                        [--budget <tokens>] [--diff <ref>] [--full]
 
 Print the exact context pack for a task, in the documented read
-order: AGENTS.md, product.md, the capability spec (when given —
-otherwise every active spec), open changes, accepted ADRs. Skills are
+order: product.md, the capability spec (when given — otherwise every
+active spec), open changes, accepted ADRs. Skills are
 listed name + description + when-trigger only — they are on-demand by
 design. The change archive is excluded.
 
+The pack is LEAN by default: AGENTS.md is not repeated (your agent
+loads it every turn), an accepted ADR is a digest — its title and the
+opening of its Decision; \`doctrina show NNNN\` reads the rest — and
+with --for the task's spec is sliced to its headers, Purpose and the
+requirements and criteria the task matches, the others named by count.
+--full restores every text whole.
+
 Assembly is retrieval, not a dump. A token budget ALWAYS applies
 (default ${DEFAULT_BUDGET}; set "context_budget": <n> in
 .doctrina/config.json, or pass --budget). Over budget, accepted ADRs
@@ -731,6 +770,8 @@ Flags:
                     the list — ready to pipe into an agent. The budget
                     verdict goes to stderr, keeping stdout pure.
   --budget <n>      Token ceiling for this call, overriding the project's.
+  --full            Every artifact whole: AGENTS.md included, specs not
+                    sliced, ADRs not digested (the pre-0.19 pack).
   --diff <ref>      Scope the stable artifacts (AGENTS.md, product.md,
                     specs, ADRs) to those changed since the git ref; open
                     changes are always included. The resume-session read.

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

@@ -82,6 +82,7 @@ export const RUNNERS = {
   "change check": () => import("./change.js"),
   "change apply": () => import("./change.js"),
   "change archive": () => import("./change.js"),
+  close: () => import("./close.js"),
   "index rebuild": () => import("./index-rebuild.js"),
 };