doctrina-cli 0.17.0 → 0.20.0

package/src/index.js

@@ -48,6 +48,8 @@ import * as upgrade from "./commands/upgrade.js";
 import * as adapter from "./commands/adapter.js";
 import * as triage from "./commands/triage.js";
 import * as ci from "./commands/ci.js";
+import * as workspace from "./commands/workspace.js";
+import * as delivery from "./commands/delivery.js";
 
 const COMMANDS = {
   init, spec, change, decision, validate, hooks, analyze, clarify,
@@ -56,18 +58,14 @@ const COMMANDS = {
   status, close, review, watch, why,
   prime, handoff, show, doctor, report, completion,
   intent, upgrade, adapter, triage, ci,
+  workspace, delivery,
 };
 
-const TOP_HELP = `
-Usage: doctrina <command> [options]      (\`doctrina <command> --help\` for its flags)
+const TOP_HELP = `Usage: doctrina <command> [options]      (\`doctrina <command> --help\` for its flags)
 
 ${surfaceHelp()}
 
-Global flags:
-  --help, -h           Show this message (or per-command help if after a command)
-  --version, -v        Print the version
-  --debug              On an unexpected error, also print the stack trace
-
+Global flags: --help/-h (this, or a command's own) · --version/-v · --debug (stack traces)
 Exit codes (a contract — an agent reads these to decide what to do next):
 ${exitCodeHelp()}
 `;

package/src/lib/actions.js

@@ -151,7 +151,7 @@ export function computeActions(projectRoot, gates = {}) {
       severity: "blocking",
       why: "no capability is specced yet, so nothing states what this project must do",
       text: 'doctrina intake --text "<what this project is>" — no capability is specced yet; ' +
-        "for an existing codebase, `doctrina work --from-diff` backfills from the code instead",
+        "for an existing codebase, `doctrina intake --from-code` takes its inventory as the intake (`doctrina work --from-diff` backfills one change from code already written)",
     }));
   }
 
@@ -199,9 +199,13 @@ export function computeActions(projectRoot, gates = {}) {
       }
       const status = listHeader(read(proposalPath), "Status") ?? "proposed";
       if (status === "applied") {
+        // The close, not the archive (change 0201). 0.17 retired the
+        // hand-driven tail — `close` skips the apply it already did and
+        // still runs verify, coverage and the docs gate — but this line kept
+        // teaching `change archive`, the one path past every one of them.
         actions.push(action({
           id: "change-archive-pending",
-          command: "change archive",
+          command: "close",
           args: [id],
           gate: "archive",
           runnable: true,
@@ -239,11 +243,11 @@ export function computeActions(projectRoot, gates = {}) {
       } else {
         actions.push(action({
           id: "change-deltas-missing",
-          command: "change apply",
+          command: "close",
           args: [id],
-          why: `add spec deltas under .doctrina/changes/${id}/specs/, or apply as metadata-only`,
+          why: `add spec deltas under .doctrina/changes/${id}/specs/, or close it as metadata-only`,
           text: `add spec deltas under .doctrina/changes/${id}/specs/, ` +
-            `or apply as metadata-only: doctrina change apply ${id}`,
+            `or close it as metadata-only: doctrina close ${id}`,
         }));
       }
     }

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/change-ops.js

@@ -15,6 +15,10 @@ import { flagBool, flagString } from "./args.js";
 import { c } from "./colors.js";
 import { ensureDoctrinaProject, isChangeId, resolveWithinProject } from "./project.js";
 import { changeEntry } from "./scan.js";
+import { parseOp, insertOps, extractOps, applyOps } from "./spec-ops.js";
+import { parseOperation } from "./doc-model.js";
+import { substitute } from "./templates.js";
+import { EXIT } from "./exit-codes.js";
 export function changeNew(args, flags) {
   const id = args[0];
   const title = args.slice(1).join(" ").trim();
@@ -131,3 +135,91 @@ export function reindexChange(projectRoot, id, date = today()) {
   idx.touch(index, date);
   idx.save(projectRoot, index);
 }
+
+/**
+ * Add op lines to a change's MODIFIED delta for one capability (change 0205).
+ *
+ * A field review of 0.17 asked for "a command to add a requirement and a
+ * criterion without writing the ops blocks by hand". The grammar is
+ * `apply`'s (ADR 0021): every line is parsed by the same parser, and the
+ * whole block — what was there plus what is added — is dry-run against the
+ * current spec before anything is written, so an op that would not apply is
+ * refused now rather than at the close. Creates the delta from the template
+ * when the change has none for the capability yet; a second `bump-version`
+ * replaces the first instead of bumping twice.
+ *
+ * @param {string} projectRoot
+ * @param {string} id          change id (already refused/resolved by the caller)
+ * @param {string} capability
+ * @param {string[]} lines     op lines, one operation each
+ * @returns {{ code: number, error?: string, hint?: string, details?: string[],
+ *             deltaRel?: string, created?: boolean, block?: string[] }}
+ */
+export function addDeltaOps(projectRoot, id, capability, lines) {
+  if (lines.length === 0) {
+    return { code: EXIT.USAGE, error: "nothing to add",
+      hint: "pass --requirement \"<section>: <text>\", --criterion \"<text>\", --bump <level> or an op line" };
+  }
+  const bad = lines.map((l) => ({ l, op: parseOp(l) })).filter((x) => x.op.error);
+  if (bad.length > 0) {
+    return { code: EXIT.USAGE, error: "not an operation `apply` can read", details: bad.map((x) => x.op.error) };
+  }
+  const specPath = path.join(projectRoot, ".doctrina", "specs", capability, "spec.md");
+  if (!isFile(specPath)) {
+    return { code: EXIT.USAGE, error: `capability "${capability}" has no spec at ${relPath(projectRoot, specPath)}`,
+      hint: `a NEW capability is an ADDED delta with the full body — \`doctrina spec new ${capability}\`, then write it` };
+  }
+  const deltaPath = path.join(projectRoot, ".doctrina", "changes", id, "specs", capability, "delta.md");
+  const created = !isFile(deltaPath);
+  let text;
+  if (created) {
+    const tpl = read(path.join(locateTemplatesDir(), "change", "spec-delta.md.template"));
+    text = substitute(tpl, { CAPABILITY: capability }).replace(/^\*\*Operation:\*\*.*$/m, "**Operation:** MODIFIED");
+  } else {
+    text = read(deltaPath);
+    const op = parseOperation(text);
+    if (op && op !== "MODIFIED") {
+      return { code: EXIT.PRECONDITION, error: `${relPath(projectRoot, deltaPath)} is an ${op} delta — ops apply only to a MODIFIED one`,
+        hint: op === "ADDED" ? "write the requirement into the ADDED body itself" : "a REMOVED delta deletes the spec; there is nothing to add to" };
+    }
+  }
+  const next = insertOps(text, lines);
+  const dry = applyOps(read(specPath), extractOps(next));
+  if (dry.errors.length > 0) {
+    return { code: EXIT.GATE, error: `the ops block would not apply to ${relPath(projectRoot, specPath)} — nothing written`, details: dry.errors };
+  }
+  mkdirp(path.dirname(deltaPath));
+  write(deltaPath, next, { force: true });
+  addAffectedSpec(projectRoot, id, capability);
+  return { code: EXIT.OK, deltaRel: relPath(projectRoot, deltaPath), created, block: extractOps(next).map((o) => o.verb) };
+}
+
+/**
+ * Name `capability` in the proposal's `Affects specs:` header when the
+ * header does not already (change 0207). A change whose delta targets a
+ * capability affects that spec, and a header left empty while the delta
+ * folder said otherwise was the one fact `prime`, `status` and the review
+ * of the proposal disagreed on. A chore's "(none — chore)" is left alone:
+ * that is a declaration, and the structure gate is where a chore carrying a
+ * delta gets questioned.
+ *
+ * @param {string} projectRoot
+ * @param {string} id
+ * @param {string} capability
+ * @returns {boolean} whether the header changed
+ */
+export function addAffectedSpec(projectRoot, id, capability) {
+  const proposalPath = path.join(projectRoot, ".doctrina", "changes", id, "proposal.md");
+  if (!isFile(proposalPath)) return false;
+  const text = read(proposalPath);
+  const m = text.match(/^(-[ \t]+\*\*Affects specs:\*\*)([^\r\n]*)/m);
+  if (!m) return false;
+  const current = m[2].trim();
+  if (/^\(none/i.test(current)) return false;
+  const named = current.split(",").map((s) => s.trim().replace(/`/g, "")).filter(Boolean);
+  if (named.includes(capability)) return false;
+  const value = [...named, capability].join(", ");
+  write(proposalPath, text.replace(m[0], `${m[1]} ${value}`), { force: true });
+  reindexChange(projectRoot, id);
+  return true;
+}

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";
+}
+