doctrina-cli 0.18.0 → 0.20.0

package/src/lib/adapters.js

@@ -127,3 +127,83 @@ export function renderAdapterFile(file, tokens) {
 }
 
 export { exists };
+
+// ---------------------------------------------------------------------------
+// Configuration files an adapter SHARES with the user (change 0211).
+//
+// A hook lives in the agent's own settings — `.claude/settings.json`,
+// `.cursor/hooks.json` — which the project may already own: permissions,
+// other hooks, a model choice. Writing the file whole would be the data loss
+// `adapter add` exists to avoid, and skipping it because it exists would
+// leave the hooks out exactly where an agent is configured. So a `.json`
+// adapter file is MERGED: objects recurse, arrays gain the entries they do
+// not already hold, and a scalar the user set stays theirs. Removal takes
+// back only what the template put in.
+
+/** Whether an adapter file is merged into a shared configuration file. */
+export function isMergedConfig(file) {
+  return file.relativePath.endsWith(".json");
+}
+
+const same = (a, b) => JSON.stringify(a) === JSON.stringify(b);
+
+/** `ours` merged into `theirs`; neither argument is modified. */
+export function mergeJson(theirs, ours) {
+  if (Array.isArray(theirs) && Array.isArray(ours)) {
+    return [...theirs, ...ours.filter((o) => !theirs.some((t) => same(t, o)))];
+  }
+  if (isPlainObject(theirs) && isPlainObject(ours)) {
+    const out = { ...theirs };
+    for (const [k, v] of Object.entries(ours)) {
+      out[k] = k in theirs ? mergeJson(theirs[k], v) : v;
+    }
+    return out;
+  }
+  return theirs;
+}
+
+/**
+ * `theirs` with everything `ours` contributed taken out, and the containers
+ * that leaves empty pruned. A scalar is removed only when it equals ours AND
+ * nothing of the user's remains beside it. Returns null when nothing is left.
+ */
+export function unmergeJson(theirs, ours) {
+  if (Array.isArray(theirs) && Array.isArray(ours)) {
+    const left = theirs.filter((t) => !ours.some((o) => same(t, o)));
+    return left.length > 0 ? left : null;
+  }
+  if (isPlainObject(theirs) && isPlainObject(ours)) {
+    const out = {};
+    for (const [k, v] of Object.entries(theirs)) {
+      if (!(k in ours) || isScalar(ours[k])) { out[k] = v; continue; }
+      const kept = unmergeJson(v, ours[k]);
+      if (kept !== null) out[k] = kept;
+    }
+    // Our scalars (a `"version": 1`) go only when they are all that is left.
+    const userKeys = Object.keys(out).filter((k) => !(k in ours && isScalar(ours[k]) && same(out[k], ours[k])));
+    return userKeys.length > 0 ? out : null;
+  }
+  return same(theirs, ours) ? null : theirs;
+}
+
+function isPlainObject(v) {
+  return v !== null && typeof v === "object" && !Array.isArray(v);
+}
+
+function isScalar(v) {
+  return v === null || typeof v !== "object";
+}
+
+/** Whether `theirs` holds at least one array entry `ours` contributes. */
+export function holdsAnyOf(theirs, ours) {
+  if (Array.isArray(theirs) && Array.isArray(ours)) return ours.some((o) => theirs.some((t) => same(t, o)));
+  if (isPlainObject(theirs) && isPlainObject(ours)) {
+    return Object.keys(ours).some((k) => k in theirs && holdsAnyOf(theirs[k], ours[k]));
+  }
+  return false;
+}
+
+/** Whether every entry `ours` contributes is present in `theirs`. */
+export function containsJson(theirs, ours) {
+  return same(mergeJson(theirs, ours), theirs);
+}

package/src/lib/code-inventory.js

@@ -0,0 +1,297 @@
+// @ts-check
+import { readdirSync } from "node:fs";
+import path from "node:path";
+import { isDir, isFile, read } from "./fs-ops.js";
+import { gitLines } from "./git.js";
+
+// The INVENTORY of an existing codebase (change 0221): what `intake
+// --from-code` stores as the intake of a repository that already has code
+// and no specs. Deterministic, local and cheap — it reads manifests and
+// counts files; it never interprets prose and never reads a secret.
+//
+// It is the FACTS half of absorbing a project. The agent does the other
+// half — reading the code it points at and writing what the system does
+// today — through the absorb playbook (ADR 0005: the CLI does no
+// interpretation).
+
+const SKIP_DIRS = new Set([
+  ".git", "node_modules", ".doctrina", "dist", "build", "out", "target", "vendor", "coverage",
+  ".venv", "venv", "__pycache__", ".next", ".nuxt", ".gradle", ".idea", ".vscode", "bin", "obj",
+  ".terraform", ".pytest_cache", ".mypy_cache", "Pods", ".dart_tool", ".expo",
+]);
+const MAX_FILES = 20000;
+
+// Dependency name → what it tells about the project.
+const JS_SIGNALS = {
+  react: "React", next: "Next.js", vue: "Vue", nuxt: "Nuxt", "@angular/core": "Angular", svelte: "Svelte",
+  "react-native": "React Native", expo: "Expo", express: "Express", fastify: "Fastify", "@nestjs/core": "NestJS",
+  koa: "Koa", graphql: "GraphQL", prisma: "Prisma", typeorm: "TypeORM", sequelize: "Sequelize", mongoose: "Mongoose",
+  jest: "Jest", vitest: "Vitest", mocha: "Mocha", "@playwright/test": "Playwright", playwright: "Playwright",
+  cypress: "Cypress", "@cucumber/cucumber": "Cucumber", webdriverio: "WebdriverIO", "@testing-library/react": "Testing Library",
+  storybook: "Storybook", "@storybook/react": "Storybook", typescript: "TypeScript", "k6": "k6",
+};
+const PY_SIGNALS = {
+  django: "Django", flask: "Flask", fastapi: "FastAPI", pytest: "pytest", behave: "Behave",
+  "robotframework": "Robot Framework", selenium: "Selenium", playwright: "Playwright", requests: "requests",
+  sqlalchemy: "SQLAlchemy", pandas: "pandas", pyspark: "PySpark", locust: "Locust", celery: "Celery",
+};
+const JVM_SIGNALS = {
+  "spring-boot": "Spring Boot", junit: "JUnit", "rest-assured": "REST Assured", cucumber: "Cucumber",
+  testng: "TestNG", selenium: "Selenium", kotlin: "Kotlin", mockito: "Mockito",
+};
+
+const TEST_FILE = /(\.(test|spec)\.[cm]?[jt]sx?$)|(^test_.*\.py$)|(_test\.(py|go)$)|(\.feature$)|(Tests?\.(java|kt|cs)$)|(\.robot$)|(_spec\.rb$)/;
+const CI_FILES = [
+  [".github/workflows", "GitHub Actions"], [".gitlab-ci.yml", "GitLab CI"], ["Jenkinsfile", "Jenkins"],
+  ["azure-pipelines.yml", "Azure Pipelines"], ["bitbucket-pipelines.yml", "Bitbucket Pipelines"], [".circleci", "CircleCI"],
+];
+const INFRA_FILES = [
+  ["Dockerfile", "Docker"], ["docker-compose.yml", "Docker Compose"], ["docker-compose.yaml", "Docker Compose"],
+  ["compose.yml", "Docker Compose"], ["helm", "Helm"], ["k8s", "Kubernetes manifests"], ["kubernetes", "Kubernetes manifests"],
+  ["serverless.yml", "Serverless"], ["Procfile", "Procfile"],
+];
+const ENV_EXAMPLES = [".env.example", ".env.sample", ".env.template", ".env.dist"];
+const AREA_ROOTS = ["src", "app", "lib", "packages", "apps", "services", "modules", "features", "pages", "components", "tests", "test", "e2e", "cypress"];
+
+function walk(root) {
+  const files = [];
+  let truncated = false;
+  const stack = [""];
+  while (stack.length && !truncated) {
+    const rel = stack.pop();
+    let entries;
+    try {
+      entries = readdirSync(path.join(root, rel), { withFileTypes: true });
+    } catch {
+      continue;
+    }
+    for (const e of entries) {
+      const r = rel ? `${rel}/${e.name}` : e.name;
+      if (e.isDirectory()) {
+        if (!SKIP_DIRS.has(e.name)) stack.push(r);
+      } else if (e.isFile()) {
+        files.push(r);
+        if (files.length >= MAX_FILES) {
+          truncated = true;
+          break;
+        }
+      }
+    }
+  }
+  return { files: files.sort(), truncated };
+}
+
+function readJson(p) {
+  try {
+    return JSON.parse(read(p));
+  } catch {
+    return null;
+  }
+}
+
+function signalsFrom(names, table) {
+  const out = new Set();
+  for (const n of names) {
+    const key = String(n).toLowerCase();
+    for (const [dep, label] of Object.entries(table)) {
+      // Exact names only (a scope prefix aside): `express` must not read as
+      // `expo`, nor `nextjs-toolbox` as Next.js.
+      if (key === dep || key.endsWith("/" + dep)) out.add(label);
+    }
+  }
+  return [...out];
+}
+
+/** Every `KEY=` name in an env example file — names only, never a value. */
+export function envNames(text) {
+  return String(text).split(/\r?\n/)
+    .map((l) => l.match(/^\s*(?:export\s+)?([A-Z][A-Z0-9_]*)\s*=/)?.[1])
+    .filter(Boolean);
+}
+
+function readmeSummary(root) {
+  for (const name of ["README.md", "readme.md", "README.MD", "README"]) {
+    const p = path.join(root, name);
+    if (!isFile(p)) continue;
+    const lines = read(p).split(/\r?\n/);
+    const title = lines.find((l) => /^#\s+/.test(l))?.replace(/^#\s+/, "").trim() ?? "";
+    const para = [];
+    let started = false;
+    for (const l of lines) {
+      if (/^#/.test(l) || /^\s*(<|!\[|\[!\[)/.test(l)) {
+        if (started) break;
+        continue;
+      }
+      if (l.trim() === "") {
+        if (started) break;
+        continue;
+      }
+      started = true;
+      para.push(l.trim());
+    }
+    return { file: name, title, summary: para.join(" ").slice(0, 400) };
+  }
+  return null;
+}
+
+function gitFacts(root) {
+  const dates = gitLines(root, ["log", "--format=%cs"]);
+  if (!dates || dates.length === 0) return null;
+  return { commits: dates.length, first: dates[dates.length - 1], last: dates[0] };
+}
+
+/**
+ * The inventory of the codebase at `root`.
+ */
+export function inventory(root) {
+  const { files, truncated } = walk(root);
+  const has = (rel) => files.includes(rel) || isDir(path.join(root, rel));
+  const stack = new Set();
+  const signals = new Set();
+  const checks = [];
+
+  const pkg = isFile(path.join(root, "package.json")) ? readJson(path.join(root, "package.json")) : null;
+  if (pkg) {
+    stack.add(isFile(path.join(root, "tsconfig.json")) ? "Node.js / TypeScript" : "Node.js");
+    const deps = [...Object.keys(pkg.dependencies ?? {}), ...Object.keys(pkg.devDependencies ?? {})];
+    for (const s of signalsFrom(deps, JS_SIGNALS)) signals.add(s);
+    const runner = isFile(path.join(root, "pnpm-lock.yaml")) ? "pnpm" : isFile(path.join(root, "yarn.lock")) ? "yarn" : "npm";
+    for (const name of ["typecheck", "lint", "test", "build"]) {
+      if (pkg.scripts?.[name]) checks.push({ name, command: `${runner} run ${name}`, from: "package.json scripts" });
+    }
+    for (const [name, cmd] of Object.entries(pkg.scripts ?? {})) {
+      if (/^(test:|e2e)/.test(name)) checks.push({ name, command: `${runner} run ${name}`, from: `package.json scripts (${String(cmd).slice(0, 60)})` });
+    }
+  }
+  const pyFiles = ["pyproject.toml", "requirements.txt", "requirements-dev.txt", "setup.py", "Pipfile"].filter((f) => isFile(path.join(root, f)));
+  if (pyFiles.length) {
+    stack.add("Python");
+    const text = pyFiles.map((f) => read(path.join(root, f))).join("\n").toLowerCase();
+    const names = text.match(/[a-z][a-z0-9_.-]+/g) ?? [];
+    for (const s of signalsFrom([...new Set(names)].filter((n) => PY_SIGNALS[n]), PY_SIGNALS)) signals.add(s);
+    if (signals.has("pytest")) checks.push({ name: "test", command: "pytest", from: pyFiles.join(", ") });
+    if (signals.has("Behave")) checks.push({ name: "bdd", command: "behave", from: pyFiles.join(", ") });
+  }
+  const jvm = ["pom.xml", "build.gradle", "build.gradle.kts"].filter((f) => isFile(path.join(root, f)));
+  if (jvm.length) {
+    stack.add(jvm[0] === "pom.xml" ? "Java / Maven" : "JVM / Gradle");
+    const text = jvm.map((f) => read(path.join(root, f))).join("\n").toLowerCase();
+    for (const [dep, label] of Object.entries(JVM_SIGNALS)) if (text.includes(dep)) signals.add(label);
+    checks.push(jvm[0] === "pom.xml"
+      ? { name: "test", command: "mvn -q test", from: "pom.xml" }
+      : { name: "test", command: isFile(path.join(root, "gradlew")) ? "./gradlew test" : "gradle test", from: jvm[0] });
+  }
+  if (isFile(path.join(root, "go.mod"))) {
+    stack.add("Go");
+    checks.push({ name: "test", command: "go test ./...", from: "go.mod" });
+  }
+  if (isFile(path.join(root, "Cargo.toml"))) {
+    stack.add("Rust");
+    checks.push({ name: "test", command: "cargo test", from: "Cargo.toml" });
+  }
+  if (files.some((f) => /\.(csproj|sln)$/.test(f))) {
+    stack.add(".NET");
+    checks.push({ name: "test", command: "dotnet test", from: "*.csproj" });
+  }
+  if (isFile(path.join(root, "pubspec.yaml"))) {
+    stack.add("Dart / Flutter");
+    checks.push({ name: "test", command: "flutter test", from: "pubspec.yaml" });
+  }
+  if (isFile(path.join(root, "Gemfile"))) stack.add("Ruby");
+  if (isFile(path.join(root, "composer.json"))) stack.add("PHP");
+  if (isDir(path.join(root, "android"))) signals.add("Android project");
+  if (isDir(path.join(root, "ios"))) signals.add("iOS project");
+  if (files.some((f) => f.endsWith(".tf"))) signals.add("Terraform");
+
+  const testFiles = files.filter((f) => TEST_FILE.test(path.basename(f)) || /(^|\/)(cypress|e2e)\/.+\.[cm]?[jt]sx?$/.test(f));
+  const testDirs = new Map();
+  for (const f of testFiles) {
+    const dir = f.includes("/") ? f.split("/").slice(0, Math.min(2, f.split("/").length - 1)).join("/") : ".";
+    testDirs.set(dir, (testDirs.get(dir) ?? 0) + 1);
+  }
+  const ci = CI_FILES.filter(([p]) => has(p)).map(([p, label]) => ({ path: p, label }));
+  const infra = INFRA_FILES.filter(([p]) => has(p)).map(([p, label]) => ({ path: p, label }));
+  const env = [];
+  for (const f of ENV_EXAMPLES) {
+    if (isFile(path.join(root, f))) env.push({ file: f, names: envNames(read(path.join(root, f))) });
+  }
+
+  // Candidate AREAS: the folders one level under the conventional source
+  // roots, with how many files each holds — where capabilities usually are.
+  const areas = new Map();
+  for (const f of files) {
+    const parts = f.split("/");
+    if (parts.length < 3 || !AREA_ROOTS.includes(parts[0])) continue;
+    const key = `${parts[0]}/${parts[1]}`;
+    areas.set(key, (areas.get(key) ?? 0) + 1);
+  }
+  const topDirs = new Map();
+  for (const f of files) {
+    const top = f.includes("/") ? f.split("/")[0] : null;
+    if (top) topDirs.set(top, (topDirs.get(top) ?? 0) + 1);
+  }
+
+  return {
+    root,
+    files: files.length,
+    truncated,
+    readme: readmeSummary(root),
+    stack: [...stack],
+    signals: [...signals].sort(),
+    checks,
+    tests: { files: testFiles.length, dirs: [...testDirs.entries()].sort((a, b) => b[1] - a[1]).slice(0, 10) },
+    ci,
+    infra,
+    env,
+    areas: [...areas.entries()].sort((a, b) => b[1] - a[1]).slice(0, 25),
+    topDirs: [...topDirs.entries()].sort((a, b) => b[1] - a[1]).slice(0, 15),
+    git: gitFacts(root),
+  };
+}
+
+/** The inventory as the Markdown body of an intake. */
+export function inventoryMarkdown(inv, projectName) {
+  const L = [];
+  L.push(`Code inventory of ${projectName} — the FACTS an agent absorbs the project from.`);
+  L.push("Written by `doctrina intake --from-code`: manifests read, files counted, nothing interpreted.");
+  L.push("Business intent is NOT in here: what the code cannot say goes to the human as a question.");
+  L.push("");
+  if (inv.readme) {
+    L.push(`## README (${inv.readme.file})`, "");
+    if (inv.readme.title) L.push(`- Title: ${inv.readme.title}`);
+    if (inv.readme.summary) L.push(`- Opening: ${inv.readme.summary}`);
+    L.push("");
+  }
+  L.push("## Stack", "");
+  L.push(`- Languages / build: ${inv.stack.length ? inv.stack.join(", ") : "none detected from manifests"}`);
+  L.push(`- Frameworks and tools: ${inv.signals.length ? inv.signals.join(", ") : "none detected"}`);
+  L.push(`- Files scanned: ${inv.files}${inv.truncated ? ` (stopped at ${MAX_FILES})` : ""}`);
+  if (inv.git) L.push(`- History: ${inv.git.commits} commits, ${inv.git.first} → ${inv.git.last}`);
+  L.push("");
+  L.push("## Where the code is", "");
+  for (const [dir, n] of inv.topDirs) L.push(`- \`${dir}/\` — ${n} files`);
+  if (inv.topDirs.length === 0) L.push("- (flat repository)");
+  L.push("");
+  L.push("## Candidate areas (one capability each, usually)", "");
+  for (const [dir, n] of inv.areas) L.push(`- \`${dir}/\` — ${n} files`);
+  if (inv.areas.length === 0) L.push("- none under the conventional roots — derive areas from the top-level folders");
+  L.push("");
+  L.push("## Tests", "");
+  L.push(`- ${inv.tests.files} test file${inv.tests.files === 1 ? "" : "s"}`);
+  for (const [dir, n] of inv.tests.dirs) L.push(`- \`${dir}\` — ${n}`);
+  L.push("");
+  L.push("## Build and test commands (candidates for `doctrina verify --init`)", "");
+  for (const ch of inv.checks) L.push(`- \`${ch.command}\` — ${ch.name}, from ${ch.from}`);
+  if (inv.checks.length === 0) L.push("- none detected — ask the human how this project is built and tested");
+  L.push("");
+  L.push("## Delivery", "");
+  for (const c of inv.ci) L.push(`- CI: ${c.label} (\`${c.path}\`)`);
+  for (const i of inv.infra) L.push(`- Runtime: ${i.label} (\`${i.path}\`)`);
+  if (inv.ci.length + inv.infra.length === 0) L.push("- no CI or runtime manifest found");
+  L.push("");
+  L.push("## Configuration (names only — values are never read)", "");
+  for (const e of inv.env) L.push(`- \`${e.file}\`: ${e.names.length ? e.names.map((n) => `\`${n}\``).join(", ") : "(no KEY= lines)"}`);
+  if (inv.env.length === 0) L.push("- no env example file");
+  return L.join("\n") + "\n";
+}
+

package/src/lib/commands.js

@@ -19,6 +19,8 @@ export const COMMAND_NAMES = [
   "prime", "context", "show", "search", "status", "next", "why", "handoff",
   // gates
   "analyze", "clarify", "validate", "coverage", "trace", "review", "verify", "close", "doctor",
+  // orchestrate
+  "workspace", "delivery",
   // maintenance
   "templates", "hooks", "index", "watch", "metrics", "report", "completion", "upgrade", "ci",
 ];
@@ -48,6 +50,7 @@ export const OPERATIONS = [
   ["change tick", "List/tick the unchecked boxes (tasks + verification; --all)"],
   ["change abandon", "Discard an open change cleanly (recorded in the ledger)"],
   ["change delta", "Add a requirement/criterion/bump to a change's delta (ops written for you)"],
+  ["change card", "One task as an executor receives it: the task, its why, the spec cut to it"],
   ["contract new", "Own the integration surface (ports, env, interfaces)"],
   ["contract list", "List contracts with status and last-updated date"],
   ["contract check", "Verify port collisions, env drift, referenced specs"],
@@ -82,6 +85,19 @@ export const OPERATIONS = [
   ["status", "One-glance project health dashboard"],
   ["why", "Explain provenance: a capability's chain, or an anchor's (SC1)"],
   ["handoff", "Markdown handoff note: open work, task state, resume command"],
+  ["workspace init", "Create a multi-repository workspace (a private git repo of context)"],
+  ["workspace add", "Register a repository: in-repo, or shadowed when it cannot carry .doctrina/"],
+  ["workspace attach", "Re-create a shadow project's links in its repository"],
+  ["workspace detach", "Remove a shadow project's links; the shadow stays"],
+  ["workspace list", "Projects with mode, state and open changes"],
+  ["workspace tool", "Declare a tool (MCP server) the work uses: role, read or write"],
+  ["workspace guard", "Pre-call hook: allow, deny or ask an MCP call from the declared access"],
+  ["delivery new", "Open a delivery across repositories; print the orchestration playbook"],
+  ["delivery route", "Choose the projects a delivery touches, dependencies first"],
+  ["delivery list", "Deliveries with status, ref and closed/total changes"],
+  ["delivery status", "Per project: the changes carrying a delivery and their tasks"],
+  ["delivery check", "What still keeps a delivery from closing (exit 1 while anything does)"],
+  ["delivery close", "Close a delivery once every project's change is closed"],
   ["templates list", "List the templates shipped by the installed CLI"],
   ["templates check", "Compare the project against the recommended template shape"],
   ["templates update", "Additive fixer for check findings (preview; --write applies)"],
@@ -127,8 +143,8 @@ export const COMMAND_META = {
   why:          { moment: "Orient",     when: "you need to justify or trace a capability's existence", purpose: "provenance: intent, proof, ADRs, and history" },
   handoff:      { moment: "Orient",     when: "BEFORE compaction or handing over to another session", purpose: "a resume note: open work, task state, next command" },
 
-  triage:       { moment: "Change",     when: "a request arrives — BEFORE scaffolding, especially if it smells like an incident", purpose: "classify the lane (product/runtime/chore) and check the declared runtime surface" },
-  work:         { moment: "Change",     when: "a request arrives that changes behaviour (triage says PRODUCT)", purpose: "scaffold a change and print the playbook to execute" },
+  triage:       { moment: "Change",     when: "diagnosing an incident or a runtime symptom — `work` classifies every other request itself", purpose: "classify the lane (product/runtime/chore) and check the declared runtime surface" },
+  work:         { moment: "Change",     when: "a request changes behaviour — BEFORE editing code; it classifies the lane itself", purpose: "scaffold a change and print the playbook to execute" },
   spec:         { moment: "Change",     when: "a capability needs creating or its headers advancing", purpose: "create, list, and edit capability specs" },
   change:       { moment: "Change",     when: "driving a change through its lifecycle by hand", purpose: "drive a change by hand — check --verbose previews every delta" },
   decision:     { moment: "Change",     when: "the change decides something a later session must not relitigate", purpose: "record, accept, land, scope, and supersede ADRs" },
@@ -146,6 +162,9 @@ export const COMMAND_META = {
   close:        { moment: "Gate",       when: "a change is implemented and ready to finish", purpose: "the whole closing sequence in one attested pass" },
   doctor:       { moment: "Gate",       when: "something looks wrong and you do not know which gate to ask", purpose: "aggregate diagnostic with per-finding remedies" },
 
+  delivery:     { moment: "Orchestrate", when: "a story or screen must land in more than one repository", purpose: "plan, route, track and close one item of work across repositories" },
+  workspace:    { moment: "Orchestrate", when: "the work spans several repositories, or a repository cannot carry .doctrina/", purpose: "register repositories, in-repo or shadowed, in one versioned workspace" },
+
   templates:    { moment: "Maintain",   when: "customising a scaffold, to see which template file wins", purpose: "where each shipped template resolves from" },
   upgrade:      { moment: "Maintain",   when: "you just updated the doctrina-cli package", purpose: "bring this project up to the installed CLI" },
   index:        { moment: "Maintain",   when: "the index drifted from the tree", purpose: "regenerate index.json from the artifacts on disk" },
@@ -158,7 +177,7 @@ export const COMMAND_META = {
 };
 
 // The order moments appear in the generated block.
-export const MOMENTS = ["Bootstrap", "Orient", "Change", "Gate", "Maintain"];
+export const MOMENTS = ["Bootstrap", "Orient", "Change", "Gate", "Orchestrate", "Maintain"];
 
 // The Commands block of `doctrina --help`, generated from OPERATIONS so the
 // printed surface can never omit an operation the catalog knows about.
@@ -192,7 +211,10 @@ export function surfaceHelp() {
       const ops = live.filter(([op]) => op.split(" ")[0] === cmd);
       const subs = ops.map(([op]) => op.split(" ")[1]).filter(Boolean);
       const text = ops.length === 1 ? ops[0][1] : capitalise(COMMAND_META[cmd].purpose);
-      out.push(line(subs.length > 0 ? `${cmd} ${subs.join("|")}` : cmd, text));
+      const op = subs.length > 0 ? `${cmd} ${subs.join("|")}` : cmd;
+      // A compact moment's long invocation stands alone rather than wrapping
+      // onto a second line (change 0220): `doctrina <cmd> --help` has the rest.
+      out.push(COMPACT_MOMENTS.has(moment) && op.length >= 20 ? `  ${op}` : line(op, text));
     }
   }
   const old = OPERATIONS.filter(([op]) => DEPRECATED[op]);
@@ -317,7 +339,10 @@ export const SURFACE_LINE_BUDGET = 40;
 // each its own line pushed the block past its budget. The budget is the
 // forcing function — a surface that cannot describe itself in 40 lines is
 // too large, and the answer is to cut commands (M8), not to raise it.
-const COMPACT_MOMENTS = new Set(["Maintain"]);
+// "Orchestrate" is compact too (change 0220): an orchestrating session reads
+// the workspace's own AGENTS.md, which carries the delivery playbook in full;
+// inside one repository the commands only need to be discoverable.
+const COMPACT_MOMENTS = new Set(["Orchestrate", "Maintain"]);
 
 // The full managed section, heading included, between the markers.
 //
@@ -517,6 +542,20 @@ export const AGENT_CHANGELOG = {
   // Each entry lists only ITS OWN delta. The series carries the rest
   // forward (see agentChangelogEntries), so a patch never has to restate
   // the minor that introduced the commands, and never silently erases it.
+  "0.20.0": [
+    "Work across repositories is a delivery: from the workspace, `doctrina delivery new \"<title>\" --ref <id>`, then follow its playbook — route, one change per repository with `doctrina work \"<title>\" --delivery <id>`, close each, then `doctrina delivery close <id>`.",
+    "Write tasks as self-contained cards (indented `Files:`, `Requirement:`, `Verify:` lines) and hand an executor `doctrina change card <id>`; one writer per repository, and only the planner closes (ADR 0030).",
+    "An existing codebase with no specs: `doctrina intake --from-code`, then the absorb playbook — describe what the code does today and send what it cannot tell to the human as open questions.",
+    "A repository that may not carry `.doctrina/` is a workspace shadow: its `.doctrina/` is a link, hidden from its git — never commit it there; commit the workspace.",
+    "MCP tools declared in the workspace are read-only unless declared `write`: a refused or held call means ask the human, never route around it.",
+  ],
+  "0.19.0": [
+    "A request that changes behaviour is a change opened BEFORE code, whether or not it names Doctrina; say its id in your first sentence to the human, and repeat the `Tell the human:` line `work` and `close` print.",
+    "`doctrina context <cap> --for \"<task>\" --concat` is now lean (no AGENTS.md, ADR digests, the spec sliced to the task) — read it before editing; `prime` is state, not the spec. `--full` gives the whole text.",
+    "Project skills are exported to `.agents/skills/` and `.claude/skills/`, where your agent lists skills — use them; edit `.doctrina/skills/`, never the exports.",
+    "`work` holds (exit 3) a request that repeats an open change or one archived in the last 14 days: resume it, or tell the human it is done and where; `--force` only for genuinely new work.",
+    "Hooks: `doctrina adapter add claude|cursor` merges session/prompt hooks (`prime --hook`, `prime --pulse`) into the agent's settings.",
+  ],
   "0.18.0": [
     "`doctrina change delta <id> <capability> --requirement \"<section>: <text>\" --criterion \"<text>\" --bump minor` writes the ops lines for you and dry-runs them against the spec — stop hand-writing ops blocks.",
     "`close` runs `verify --reuse`: running `doctrina verify` yourself right before `doctrina close` is no longer paid twice, and a batch close runs the suite once. Use `verify --affected` while working when checks declare `\"paths\"`.",

package/src/lib/context-slice.js

@@ -0,0 +1,118 @@
+// @ts-check
+import { fold } from "./lexicon.js";
+import { getSection } from "./doc-model.js";
+
+// The lean read pack (change 0216).
+//
+// A field review: the agent ran `prime` and `work` and skipped `context`,
+// although AGENTS.md calls it the read for ANY task. Measured on this
+// repository, the reason is the price: `context gates --concat` was ~40k
+// tokens — AGENTS.md again (the agent already carries it), the whole spec,
+// and every accepted ADR in full — and `--for "<task>"` cut nothing, because
+// retrieval only degraded the pack once the 50k budget overflowed. These
+// cuts are the default now; `--full` restores the whole text.
+
+// How much of an ADR's Decision a digest keeps.
+const ADR_DIGEST_CHARS = 700;
+// How many requirements and criteria a sliced spec keeps at most, each.
+const SLICE_MAX_ITEMS = 25;
+
+/**
+ * An ADR as a reader deciding whether it binds the task needs it: the
+ * title and the opening of its Decision section. `doctrina show NNNN`
+ * reads the rest.
+ *
+ * @param {string} text
+ * @param {string} title
+ * @param {string} id   four-digit ADR number
+ */
+export function adrDigest(text, title, id) {
+  const decision = (getSection(text.replace(/\r\n/g, "\n"), "Decision") ?? "")
+    .split("\n").filter((l) => !l.trim().startsWith("<!--")).join("\n").trim();
+  const clipped = decision.length > ADR_DIGEST_CHARS
+    ? `${decision.slice(0, ADR_DIGEST_CHARS).replace(/\s+\S*$/, "")} …`
+    : decision;
+  return [`# ${title}`, "", clipped || "(no Decision section)", "",
+    `(digest — full text: \`doctrina show ${id}\`, or \`context --full\`)`].join("\n");
+}
+
+/**
+ * A spec cut to what the task is about: its headers, its Purpose, and the
+ * requirements and criteria that match the query best — the rest named by
+ * count, never silently dropped. Deterministic: an item's score is how many
+ * distinct query terms it contains; the items scoring at least half the
+ * best score are kept, best first in document order, up to a cap per list.
+ *
+ * @param {string} text
+ * @param {string[]} queryTerms  already folded, stop words removed
+ * @param {string} rel           the spec's path, for the footer
+ * @returns {{ text: string, kept: number, total: number } | null}  null when nothing matched
+ */
+export function sliceSpec(text, queryTerms, rel) {
+  if (queryTerms.length === 0) return null;
+  const lines = text.replace(/\r\n/g, "\n").split("\n");
+  // Items: a bullet or numbered entry with its continuation lines.
+  /** @type {Array<{ start: number, end: number, kind: "req"|"crit", score: number }>} */
+  const items = [];
+  let section = "";
+  for (let i = 0; i < lines.length; i++) {
+    const l = lines[i];
+    if (/^##\s/.test(l)) { section = l; continue; }
+    const req = /^##\s+Requirements/i.test(section) && /^\s*-\s+\S/.test(l);
+    const crit = /^##\s+Acceptance criteria/i.test(section) && /^\s*\d+\.\s+\S/.test(l);
+    if (!req && !crit) continue;
+    let end = i;
+    while (end + 1 < lines.length && /^\s+\S/.test(lines[end + 1]) && !/^\s*(-|\d+\.)\s/.test(lines[end + 1])) end += 1;
+    const body = fold(lines.slice(i, end + 1).join(" "));
+    const score = queryTerms.filter((t) => body.includes(t)).length;
+    items.push({ start: i, end, kind: req ? "req" : "crit", score });
+    i = end;
+  }
+  const best = Math.max(0, ...items.map((it) => it.score));
+  if (best === 0) return null;
+  const floor = Math.max(1, Math.ceil(best / 2));
+  const keep = new Set();
+  for (const kind of ["req", "crit"]) {
+    items.filter((it) => it.kind === kind && it.score >= floor)
+      .sort((a, b) => b.score - a.score || a.start - b.start)
+      .slice(0, SLICE_MAX_ITEMS)
+      .forEach((it) => keep.add(it.start));
+  }
+
+  const out = [];
+  section = "";
+  let omitted = 0;
+  const flushOmitted = () => {
+    if (omitted > 0) out.push(`  … ${omitted} not matching the task`);
+    omitted = 0;
+  };
+  for (let i = 0; i < lines.length; i++) {
+    const l = lines[i];
+    if (/^##\s/.test(l)) {
+      flushOmitted();
+      section = l;
+      out.push(l);
+      continue;
+    }
+    const item = items.find((it) => it.start === i);
+    if (item) {
+      if (keep.has(i)) { flushOmitted(); out.push(...lines.slice(i, item.end + 1)); } else omitted += 1;
+      i = item.end;
+      continue;
+    }
+    // Headers, Purpose and subsection headings are kept; prose in the other
+    // sections (Out of scope, Maturity, …) is the first thing a task can do
+    // without.
+    const inLists = /^##\s+(Requirements|Acceptance criteria)/i.test(section);
+    const prose = section !== "" && !/^##\s+Purpose/i.test(section) && !inLists;
+    if (/^###\s/.test(l)) { flushOmitted(); out.push(l); continue; }
+    if (section === "" || /^##\s+Purpose/i.test(section)) { out.push(l); continue; }
+    if (inLists && l.trim() !== "") continue;
+    if (!prose) out.push(l);
+  }
+  flushOmitted();
+  const kept = keep.size;
+  out.push("", `(sliced for "${queryTerms.join(" ")}" — ${kept} of ${items.length} requirements and criteria kept; ` +
+    `full text: ${rel}, or \`context --full\`)`);
+  return { text: out.join("\n").replace(/\n{3,}/g, "\n\n"), kept, total: items.length };
+}