doctrina-cli 0.20.0 → 0.22.0

package/src/lib/install.js

@@ -0,0 +1,80 @@
+// @ts-check
+import path from "node:path";
+import process from "node:process";
+import { fileURLToPath } from "node:url";
+import { existsSync, readFileSync, realpathSync } from "node:fs";
+
+// WHICH `doctrina` A TERMINAL RUNS (change 0243).
+//
+// The hooks the adapters write call `doctrina` by name, so they run whatever
+// the PATH finds first — and a machine with two Node versions, or an npm
+// prefix that moved, holds two installs. `npm install -g` updated one, the
+// PATH still found the other, and `doctrina --version` answered the old
+// number while the registry and the package both said the new one. Nothing
+// in the CLI could say so: it only knew its own version.
+
+const here = path.dirname(fileURLToPath(import.meta.url));
+const real = (/** @type {string} */ p) => {
+  try {
+    return realpathSync(p);
+  } catch {
+    return null;
+  }
+};
+const versionAt = (/** @type {string} */ pkgDir) => {
+  try {
+    const pkg = JSON.parse(readFileSync(path.join(pkgDir, "package.json"), "utf8"));
+    return pkg.name === "doctrina-cli" ? String(pkg.version ?? "") : null;
+  } catch {
+    return null;
+  }
+};
+
+/** The package directory of the CLI that is running. */
+export function runningPackageDir() {
+  return real(path.resolve(here, "..", "..")) ?? path.resolve(here, "..", "..");
+}
+
+/**
+ * The package a `doctrina` found in `dir` belongs to: through the symlink npm
+ * writes on POSIX, or beside the `.cmd` shim it writes on Windows.
+ * @returns {{ bin: string, pkgDir: string | null, version: string | null } | null}
+ */
+function installIn(dir, platform) {
+  const names = platform === "win32" ? ["doctrina.cmd", "doctrina.ps1", "doctrina"] : ["doctrina"];
+  const bin = names.map((n) => path.join(dir, n)).find((p) => existsSync(p));
+  if (!bin) return null;
+  const candidates = [];
+  const target = real(bin);
+  // npm on POSIX: bin/doctrina -> ../lib/node_modules/doctrina-cli/src/index.js
+  if (target && target !== bin) candidates.push(path.resolve(path.dirname(target), ".."));
+  candidates.push(path.join(dir, "node_modules", "doctrina-cli"));           // npm on Windows, and a project's .bin
+  candidates.push(path.join(dir, "..", "doctrina-cli"));                     // node_modules/.bin
+  candidates.push(path.join(dir, "..", "lib", "node_modules", "doctrina-cli")); // a POSIX shim that is not a link
+  for (const c of candidates) {
+    const version = versionAt(c);
+    if (version !== null) return { bin, pkgDir: real(c) ?? c, version };
+  }
+  return { bin, pkgDir: null, version: null };
+}
+
+/**
+ * Every `doctrina` the PATH holds, in the order a shell would find them, one
+ * per package. The first is the one a bare `doctrina` runs.
+ * @returns {{ bin: string, pkgDir: string | null, version: string | null, running: boolean }[]}
+ */
+export function installsOnPath(env = process.env, platform = process.platform) {
+  const sep = platform === "win32" ? ";" : ":";
+  const running = runningPackageDir();
+  const seen = new Set();
+  const out = [];
+  for (const dir of String(env.PATH ?? env.Path ?? "").split(sep).filter(Boolean)) {
+    const found = installIn(dir, platform);
+    if (!found) continue;
+    const key = found.pkgDir ?? found.bin;
+    if (seen.has(key)) continue;
+    seen.add(key);
+    out.push({ ...found, running: found.pkgDir === running });
+  }
+  return out;
+}

package/src/lib/intake-model.js

@@ -15,7 +15,7 @@ import { stateWord } from "./spec-ops.js";
 // Clarification gate (review Topic A). A description too thin to spec from is
 // the moment to ask the user, not to let the agent invent requirements. Prints
 // the specific gaps before the bootstrap playbook; advisory, never blocking —
-// the intake is still captured verbatim (the playbook step 6 resolves it).
+// the intake is still captured verbatim (the playbook step 8 resolves it).
 /**
  * Does this argument read as a FILE PATH, or as the description itself?
  *
@@ -55,13 +55,16 @@ export function nextStepAfterInit(intakeFrom) {
       "Next: open your AI agent in this repository and tell it:",
       "    read AGENTS.md and run doctrina next",
       "It turns your description into product.md and specs; you review and approve.",
+      "New to Doctrina? `doctrina onboard` walks the whole cycle once, on this repository.",
     ];
   }
   return [
     "Next: give your AI agent the whole project description. It runs",
     "    doctrina intake --text \"<description>\"",
     "and turns it into product.md and specs (AGENTS.md, \"Working from intent\");",
-    "for an existing codebase, `doctrina work --from-diff` backfills them from the code.",
+    "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).",
+    "New to Doctrina? `doctrina onboard` walks the whole cycle once, on this repository.",
   ];
 }
 

package/src/lib/json-out.js

@@ -71,12 +71,14 @@ export function deferJson() {
  * Write the held payload with the exit code the command actually returned,
  * and leave deferred mode. A no-op when the command emitted nothing.
  */
+/** Write the held payload; false when the command held none. */
 export function flushJson(code) {
   deferring = false;
-  if (!held) return;
+  if (!held) return false;
   const { command, data } = held;
   held = null;
   writeEnvelope(command, data, { ok: code === EXIT.OK, exitCode: code });
+  return true;
 }
 
 // Print a structured payload. `command` is the invocation, `data` whatever
@@ -165,6 +167,12 @@ export async function captureOutput(fn) {
   try {
     const code = await fn();
     return { code: code ?? EXIT.OK, stdout, stderr };
+  } catch (err) {
+    // A thrown precondition still answers inside the envelope (change 0234):
+    // it escaped as English on stderr, with no JSON on stdout at all.
+    stderr.push(`error: ${err?.message ?? err}`);
+    if (err?.remedy) stderr.push(`hint: run ${err.remedy} first, then retry`);
+    return { code: err?.exitCode ?? EXIT.GATE, stdout, stderr, error: err };
   } finally {
     console.log = origLog;
     console.error = origError;

package/src/lib/ledger.js

@@ -14,8 +14,7 @@
 // match the grammar is not a corrupt ledger — it is a person writing a note.
 // Such lines are counted, never thrown, and never rewritten.
 import path from "node:path";
-import { appendFileSync } from "node:fs";
-import { exists, isFile, mkdirp, read, write } from "./fs-ops.js";
+import { appendLine, exists, isFile, mkdirp, read, write } from "./fs-ops.js";
 import { today } from "./dates.js";
 
 export const LEDGER_REL = ".doctrina/changes/archive/LEDGER.md";
@@ -157,7 +156,7 @@ export function appendLedgerLine(projectRoot, line) {
     mkdirp(path.dirname(p));
     write(p, HEADER);
   }
-  appendFileSync(p, `${line}\n`);
+  appendLine(p, line);
   return p;
 }
 

package/src/lib/lock.js

@@ -0,0 +1,58 @@
+// @ts-check
+import path from "node:path";
+import { mkdirSync, rmdirSync, statSync } from "node:fs";
+
+// ONE AT A TIME, FOR THE FEW STEPS THAT MUST BE (seventh audit, change 0250).
+//
+// "One writer per repository" is the model; a planner and an executor in the
+// same clone, or an agent that fires its tool calls in parallel, is what
+// happens. Eight `doctrina work` at once opened three changes numbered 0003
+// and two numbered 0004: each read the highest number on disk before any of
+// the others had created its folder.
+//
+// The lock is a directory — `mkdir` either creates it or fails, atomically,
+// on every filesystem this runs on. It is held for milliseconds. A lock left
+// behind by a process that died is taken over once it is old.
+
+const WAIT_MS = 25;
+const GIVE_UP_MS = 5000;
+const STALE_MS = 30000;
+
+function sleep(ms) {
+  Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+
+/**
+ * Run `fn` holding the project's lock. If the lock cannot be had in time the
+ * function runs anyway: a stuck lock must never stop the work it protects.
+ * @template T
+ * @param {string} projectRoot
+ * @param {() => T} fn
+ * @returns {T}
+ */
+export function withProjectLock(projectRoot, fn) {
+  const lock = path.join(projectRoot, ".doctrina", ".lock");
+  let held = false;
+  for (let waited = 0; waited <= GIVE_UP_MS; waited += WAIT_MS) {
+    try {
+      mkdirSync(lock);
+      held = true;
+      break;
+    } catch (err) {
+      if (/** @type {NodeJS.ErrnoException} */ (err).code !== "EEXIST") break; // no .doctrina/, read-only tree: nothing to serialise
+      try {
+        if (Date.now() - statSync(lock).mtimeMs > STALE_MS) rmdirSync(lock);
+      } catch { /* released between the two calls */ }
+      sleep(WAIT_MS);
+    }
+  }
+  try {
+    return fn();
+  } finally {
+    if (held) {
+      try {
+        rmdirSync(lock);
+      } catch { /* already gone */ }
+    }
+  }
+}

package/src/lib/merge-setup.js

@@ -0,0 +1,55 @@
+// @ts-check
+import path from "node:path";
+import { exists, read, write } from "./fs-ops.js";
+import { git, GIT_STATE } from "./git.js";
+
+// WHAT A REPOSITORY NEEDS SO TWO BRANCHES MERGE THEIR ARTIFACTS (change 0242).
+//
+// Two files are rewritten by every change, so two branches always meet on
+// them: `index.json`, which is derived, and the ledger, which is a list.
+// `.gitattributes` names how each merges — it is committed, so every clone
+// reads it — and the index's driver is a command, which git keeps in the
+// clone's own config: `doctrina hooks install` writes both.
+
+export const MERGE_DRIVER = "doctrina-index";
+export const ATTRIBUTE_LINES = [
+  `**/.doctrina/index.json merge=${MERGE_DRIVER}`,
+  "**/.doctrina/changes/archive/LEDGER.md merge=union",
+];
+const HEADING = "# Doctrina: the derived index merges as data, the ledger as a list (`doctrina hooks install`)";
+
+/** The lines `.gitattributes` still lacks, in order. */
+export function missingAttributes(projectRoot) {
+  const file = path.join(projectRoot, ".gitattributes");
+  const have = exists(file) ? read(file).split(/\r?\n/).map((l) => l.trim()) : [];
+  return ATTRIBUTE_LINES.filter((line) => !have.includes(line));
+}
+
+/** Append the missing lines to `.gitattributes`. Returns how many were added. */
+export function writeAttributes(projectRoot) {
+  const missing = missingAttributes(projectRoot);
+  if (missing.length === 0) return 0;
+  const file = path.join(projectRoot, ".gitattributes");
+  const before = exists(file) ? read(file) : "";
+  const eol = before.includes("\r\n") ? "\r\n" : "\n";
+  const gap = before === "" || before.endsWith("\n") ? "" : eol;
+  const head = before.includes(HEADING) ? [] : [HEADING];
+  write(file, before + gap + (before === "" ? "" : eol) + [...head, ...missing].join(eol) + eol, { force: true });
+  return missing.length;
+}
+
+/** The driver command this clone runs for the index, or null when it has none. */
+export function configuredDriver(projectRoot) {
+  const r = git(projectRoot, ["config", "--get", `merge.${MERGE_DRIVER}.driver`]);
+  return r.state === GIT_STATE.OK && r.stdout.trim() !== "" ? r.stdout.trim() : null;
+}
+
+/**
+ * Point this clone's merge driver at `command` (the CLI, pinned by path as
+ * the hook is). Returns false when git refused.
+ */
+export function configureDriver(projectRoot, command) {
+  const set = (/** @type {string} */ k, /** @type {string} */ v) =>
+    git(projectRoot, ["config", `merge.${MERGE_DRIVER}.${k}`, v]).state === GIT_STATE.OK;
+  return set("name", "Doctrina index merge") && set("driver", `${command} index merge %O %A %B`);
+}

package/src/lib/metrics-model.js

@@ -90,7 +90,7 @@ export function parseLog(stdout) {
   for (const line of stdout.split("\n")) {
     if (line.startsWith("@@")) {
       const [hash, ts, ...rest] = line.slice(2).split("|");
-      current = { hash, ts: Number(ts), subject: rest.join("|"), files: [] };
+      current = { hash, ts: Number(ts), subject: rest.join("|"), files: /** @type {string[]} */ ([]) };
       commits.push(current);
     } else if (line.trim() !== "" && current) {
       current.files.push(line.trim());
@@ -181,7 +181,7 @@ export function readSeries(projectRoot) {
 }
 
 /** The most recent saved snapshot, excluding one basename. */
-export function latestSnapshot(projectRoot, excludeBase = null) {
+export function latestSnapshot(projectRoot, excludeBase = /** @type {string | null} */ (null)) {
   const series = readSeries(projectRoot).filter((s) => `${s.generated}.json` !== excludeBase);
   return series.length > 0 ? series[series.length - 1] : null;
 }

package/src/lib/onboard.js

@@ -0,0 +1,197 @@
+// @ts-check
+import path from "node:path";
+import { readdirSync } from "node:fs";
+import { isDir, isFile, read } from "./fs-ops.js";
+import { checklistProgress, parseChangeTitle } from "./doc-model.js";
+import { intakeStatus } from "./intake-model.js";
+import { parseAcceptanceCriteria } from "./criteria.js";
+import { collect } from "./coverage-model.js";
+import { gitLines } from "./git.js";
+
+// THE CYCLE ONCE, ON THE REAL REPOSITORY (change 0256).
+//
+// A newcomer had the reference (2,900 lines), a getting-started page, and
+// `next`, which names one action and assumes the reader knows why. Nothing
+// walked the whole cycle once. OpenSpec's `onboard` does that with a model
+// narrating; here the CLI reads where the project stands and prints the
+// walk — what each step is for, what to run, what to tell the human, and
+// where to stop and ask — and the agent is the guide.
+//
+// Every "done" below is read from the tree, never stored: a tour that
+// remembers its own progress is a second place for a fact to go stale.
+
+const CODE_FILE = /\.(py|js|mjs|cjs|ts|tsx|jsx|go|rs|java|kt|rb|php|cs|swift|scala|c|cc|cpp|h|hpp|sh)$/i;
+const TODO_LINE = /\b(TODO|FIXME)\b[:\s-]*(.{0,90})/;
+const FILES_READ = 400;
+const FILE_BYTES = 200_000;
+export const CANDIDATES_SHOWN = 3;
+
+/**
+ * Where the project stands, read from the tree.
+ * @param {string} projectRoot
+ */
+export function onboardState(projectRoot) {
+  const dir = path.join(projectRoot, ".doctrina");
+  const installed = isDir(dir);
+  const specsDir = path.join(dir, "specs");
+  const specs = isDir(specsDir)
+    ? readdirSync(specsDir).filter((cap) => isFile(path.join(specsDir, cap, "spec.md"))).sort()
+    : [];
+  const intake = path.join(dir, "intake.md");
+  const intakePending = isFile(intake) && intakeStatus(read(intake)) === "pending";
+  const changesDir = path.join(dir, "changes");
+  const open = [];
+  if (isDir(changesDir)) {
+    for (const id of readdirSync(changesDir).filter((d) => /^\d{4}-/.test(d)).sort()) {
+      const proposal = path.join(changesDir, id, "proposal.md");
+      if (!isFile(proposal)) continue;
+      const tasksPath = path.join(changesDir, id, "tasks.md");
+      const p = isFile(tasksPath) ? checklistProgress(read(tasksPath)) : { total: 0, done: 0, placeholders: 0 };
+      open.push({
+        id,
+        title: parseChangeTitle(read(proposal)) ?? "",
+        planned: p.total > 0 && p.placeholders === 0,
+        ticked: p.total > 0 && p.placeholders === 0 && p.done === p.total,
+        tasks: { total: p.total, done: p.done },
+      });
+    }
+  }
+  const archiveDir = path.join(changesDir, "archive");
+  const archived = isDir(archiveDir)
+    ? readdirSync(archiveDir).filter((d) => /^\d{4}-\d{2}-\d{2}-\d{4}-/.test(d)).sort()
+    : [];
+  const hasCode = codeFiles(projectRoot, 1).length > 0;
+  return {
+    installed, specs, intakePending, hasCode, open,
+    closed: archived.length,
+    lastClosed: archived.length > 0 ? `.doctrina/changes/archive/${archived[archived.length - 1]}/` : null,
+  };
+}
+
+/** Tracked code files, as git lists them; none outside a repository. */
+function codeFiles(projectRoot, limit) {
+  const out = [];
+  for (const f of gitLines(projectRoot, ["ls-files", "--cached", "--others", "--exclude-standard"])) {
+    if (f.startsWith(".doctrina/") || /(^|\/)(node_modules|vendor|dist|build)\//.test(f) || !CODE_FILE.test(f)) continue;
+    out.push(f);
+    if (out.length >= limit) break;
+  }
+  return out;
+}
+
+/**
+ * Small, real first tasks read from this repository: a criterion with no
+ * proof yet, then a TODO somebody left in the code.
+ * @param {string} projectRoot
+ * @returns {{ kind: "criterion" | "todo", where: string, text: string, prompt: string }[]}
+ */
+export function firstTaskCandidates(projectRoot) {
+  const out = [];
+  for (const report of collect(projectRoot)) {
+    if (out.length >= CANDIDATES_SHOWN) break;
+    const criteria = parseAcceptanceCriteria(read(report.specPath));
+    for (const row of report.rows) {
+      if (out.length >= CANDIDATES_SHOWN) break;
+      const kind = "was" in row ? row.was : row.kind;
+      if (kind !== "bare" && kind !== "dangling") continue;
+      const body = String(criteria[row.n - 1]?.body ?? "").replace(/^\[[a-z]+\]\s*/i, "").replace(/\s+—\s+(verified|proven|evidenced|demonstrated) by .*$/i, "").trim();
+      if (body === "") continue;
+      out.push({
+        kind: /** @type {"criterion"} */ ("criterion"),
+        where: `${report.cap} #${row.n}`,
+        text: `${kind === "bare" ? "no proof cited" : "the proof it cites is missing"}: ${clip(body, 90)}`,
+        prompt: `prove ${report.cap} criterion ${row.n}: ${clip(body, 70)}`,
+      });
+    }
+  }
+  let read_ = 0;
+  for (const f of codeFiles(projectRoot, FILES_READ)) {
+    if (out.length >= CANDIDATES_SHOWN * 2) break;
+    const abs = path.join(projectRoot, f);
+    if (!isFile(abs)) continue;
+    let text;
+    try {
+      text = read(abs);
+    } catch {
+      continue;
+    }
+    if (text.length > FILE_BYTES || ++read_ > FILES_READ) continue;
+    const lines = text.split("\n");
+    for (let i = 0; i < lines.length; i++) {
+      const m = lines[i].match(TODO_LINE);
+      if (!m || m[2].trim().length < 8) continue;
+      const note = m[2].trim().replace(/\s*(\*\/|-->)\s*$/, "");
+      out.push({ kind: /** @type {"todo"} */ ("todo"), where: `${f}:${i + 1}`, text: `${m[1]} ${clip(note, 90)}`, prompt: clip(note, 70) });
+      break;
+    }
+  }
+  return out.slice(0, CANDIDATES_SHOWN * 2);
+}
+
+const clip = (/** @type {string} */ s, /** @type {number} */ n) => (s.length > n ? `${s.slice(0, n - 1)}…` : s);
+
+/**
+ * The walk: every step with whether the tree says it is done, what it is
+ * for, what to run and where to ask. `current` is the first one not done.
+ * @param {ReturnType<typeof onboardState>} state
+ */
+export function onboardSteps(state) {
+  const first = state.open[0] ?? null;
+  const id = first?.id ?? "<id>";
+  const ran = state.closed > 0;
+  const steps = [
+    { id: "install", title: "Install",
+      done: state.installed,
+      evidence: state.installed ? ".doctrina/ and AGENTS.md are here" : "",
+      say: "Doctrina keeps what the system should do in `.doctrina/` and tells every agent how to work in `AGENTS.md`; nothing else in the repository is touched.",
+      run: ["doctrina init"],
+      ask: "" },
+    { id: "describe", title: "Describe the project",
+      done: state.installed && state.specs.length > 0 && !state.intakePending,
+      evidence: state.specs.length > 0 ? `${state.specs.length} capability spec${state.specs.length === 1 ? "" : "s"} (${state.specs.slice(0, 4).join(", ")}${state.specs.length > 4 ? ", …" : ""})` : "",
+      say: "The specs are the current truth: one per capability, each requirement a testable sentence, each criterion citing its proof. Everything after this step changes them through a change.",
+      run: state.intakePending
+        ? ["doctrina intake    # the stored description is pending: execute the playbook it prints"]
+        : [state.hasCode ? "doctrina intake --from-code    # describe what the code does today" : 'doctrina intake --text "<what the project is, in a paragraph>"'],
+      ask: state.hasCode ? "what the code cannot tell: who uses it, and what must never break." : "for the project in a paragraph: who it is for and what it must do." },
+    { id: "first-task", title: "Pick a first task and open it",
+      done: state.open.length > 0 || ran,
+      evidence: first ? `${first.id} is open` : (ran ? "a change was opened and closed" : ""),
+      say: "A request that changes behaviour becomes a change before code is edited; the CLI scaffolds it and prints the playbook. Small and real beats a toy: the cycle is learned on work that matters.",
+      run: ['doctrina work "<the task>"'],
+      ask: "to choose one of the candidates, or to name a small task of their own — something done in under an hour." },
+    { id: "plan", title: "Write the delta and the tasks",
+      done: ran || state.open.some((ch) => ch.planned),
+      evidence: first?.planned ? `${first.id} has ${first.tasks.total} task${first.tasks.total === 1 ? "" : "s"} written` : "",
+      say: "The delta is the sentence the spec gains or loses; the tasks are how the code gets there. Nothing is implemented yet — this is the moment the human reads and corrects.",
+      run: [`doctrina work --resume ${id}    # the playbook`, `doctrina change check ${id}    # would the close pass?`],
+      ask: "whether the requirement you wrote is what they meant — show it to them before any code.",
+      askAfter: true },
+    { id: "implement", title: "Implement and prove",
+      done: ran || state.open.some((ch) => ch.ticked),
+      evidence: first?.ticked ? `every task of ${first.id} is ticked` : "",
+      say: "Each task is implemented and ticked, and each new criterion cites the test that proves it: `coverage` reads that citation, not the claim.",
+      run: [`doctrina change tick ${id} <n>`, "doctrina verify"],
+      ask: "" },
+    { id: "close", title: "Close",
+      done: ran,
+      evidence: ran ? `${state.closed} change${state.closed === 1 ? "" : "s"} closed — the last at ${state.lastClosed}` : "",
+      say: "One command merges the delta into the spec, runs every gate and archives the change. If it refuses, the change is not done — it names what is missing.",
+      run: [`doctrina close ${id}`],
+      ask: "" },
+  ];
+  const at = steps.findIndex((s) => !s.done);
+  return { steps, current: at < 0 ? null : steps[at].id };
+}
+
+/** What a project that already ran the cycle shows a newcomer. */
+export function tourLines(state) {
+  const cap = state.specs[0] ?? "<capability>";
+  return [
+    "doctrina prime                 # the state of the project in one read — every session starts here",
+    `doctrina why ${cap}${" ".repeat(Math.max(1, 17 - cap.length))}# why a capability exists: intent, proof, decisions, history`,
+    ...(state.lastClosed ? [`${state.lastClosed}proposal.md    # a finished change, start to end`] : []),
+    'doctrina work "<request>"      # the next request — it says by itself when no change is needed',
+    "doctrina hooks install         # once per clone: the commit hook and the merge drivers",
+  ];
+}

package/src/lib/preset.js

@@ -0,0 +1,177 @@
+// @ts-check
+import path from "node:path";
+import { readdirSync } from "node:fs";
+import { isDir, isFile, read, walk, write } from "./fs-ops.js";
+import { configPath } from "./config.js";
+
+// A PRESET: THE ORGANISATION'S HOUSE, IN A FOLDER (change 0253).
+//
+// Every project of one company starts from the same things — its language,
+// the rules no repository may break, the decisions that bind all of them,
+// its templates, the checks its pipeline runs — and each `doctrina init`
+// started from the CLI's defaults, so the house style was re-typed, or
+// forgotten, per repository. A preset is a folder (a repository the team
+// clones, a submodule, a path on a shared drive — the CLI makes no network
+// call) that `init --preset` and `upgrade --preset` lay over a project:
+//
+//   preset.json     { "name", "description", "config": { … } }
+//   templates/**    → .doctrina/templates/**   (per-file overrides, ADR 0019)
+//   decisions/*.md  → .doctrina/decisions/
+//   skills/*.md     → .doctrina/skills/
+//   verify.json     → .doctrina/verify.json    (only when the project has none)
+//
+// ADDITIVE, like every scaffold update: a file the project already has is
+// kept, a config key it already declares is kept, and the plan says so.
+
+export const PRESET_FILE = "preset.json";
+const NAME = /^[a-z0-9][a-z0-9-]*$/;
+const CONFIG_KEYS = ["language", "context_budget", "rules", "surface"];
+const FOLDERS = [
+  { from: "templates", to: ".doctrina/templates", only: null },
+  { from: "decisions", to: ".doctrina/decisions", only: /\.md$/ },
+  { from: "skills", to: ".doctrina/skills", only: /\.md$/ },
+];
+
+/**
+ * Read a preset folder. Throws an Error whose message says what is wrong
+ * with it — the caller prints it and exits 2.
+ * @param {string} dir
+ * @returns {{ dir: string, name: string, description: string, config: Record<string, any> }}
+ */
+export function readPreset(dir) {
+  const root = path.resolve(dir);
+  if (!isDir(root)) throw new Error(`preset ${dir} is not a folder`);
+  const file = path.join(root, PRESET_FILE);
+  if (!isFile(file)) throw new Error(`${dir} has no ${PRESET_FILE} — a preset is a folder with one: { "name": "acme", "config": { … } }`);
+  let data;
+  try {
+    data = JSON.parse(read(file));
+  } catch (err) {
+    throw new Error(`${path.join(dir, PRESET_FILE)} is not valid JSON: ${/** @type {Error} */ (err).message}`);
+  }
+  if (!data || typeof data !== "object" || Array.isArray(data)) throw new Error(`${PRESET_FILE} must be an object`);
+  if (typeof data.name !== "string" || !NAME.test(data.name)) throw new Error(`${PRESET_FILE} needs a "name" of lowercase letters, digits and hyphens`);
+  const config = data.config ?? {};
+  if (typeof config !== "object" || Array.isArray(config)) throw new Error(`${PRESET_FILE}: "config" must be an object`);
+  const unknown = Object.keys(config).filter((k) => !CONFIG_KEYS.includes(k));
+  if (unknown.length > 0) throw new Error(`${PRESET_FILE}: config key${unknown.length === 1 ? "" : "s"} ${unknown.map((k) => `"${k}"`).join(", ")} unknown — a preset sets ${CONFIG_KEYS.join(", ")}`);
+  return { dir: root, name: data.name, description: typeof data.description === "string" ? data.description : "", config };
+}
+
+const posix = (/** @type {string} */ p) => p.split(path.sep).join("/");
+const adrNumber = (/** @type {string} */ name) => name.match(/^(\d{4})-/)?.[1] ?? null;
+
+/**
+ * What laying the preset over the project would do. Reads only.
+ * @returns {{
+ *   files: { rel: string, from: string, action: "copy" | "same" | "kept", note: string }[],
+ *   config: { key: string, value: any, action: "set" | "kept" | "same" }[],
+ *   verify: string[],
+ * }}
+ */
+export function planPreset(projectRoot, preset) {
+  /** @type {{ rel: string, from: string, action: "copy" | "same" | "kept", note: string }[]} */
+  const files = [];
+  const taken = new Map();
+  const decisions = path.join(projectRoot, ".doctrina", "decisions");
+  if (isDir(decisions)) {
+    for (const f of readdirSync(decisions)) {
+      const n = adrNumber(f);
+      if (n) taken.set(n, f);
+    }
+  }
+  const add = (/** @type {string} */ from, /** @type {string} */ rel) => {
+    const dest = path.join(projectRoot, rel);
+    if (isFile(dest)) {
+      files.push({ rel, from, action: read(dest) === read(from) ? "same" : "kept", note: "the project has its own" });
+      return;
+    }
+    // An ADR's number is its identity: a preset decision whose number the
+    // project already gave to another one is not renumbered behind its back.
+    const n = rel.startsWith(".doctrina/decisions/") ? adrNumber(path.basename(rel)) : null;
+    if (n && taken.has(n)) {
+      files.push({ rel, from, action: "kept", note: `ADR number ${n} is ${taken.get(n)} here — copy it under a free number by hand` });
+      return;
+    }
+    files.push({ rel, from, action: "copy", note: "" });
+  };
+  for (const folder of FOLDERS) {
+    const base = path.join(preset.dir, folder.from);
+    for (const from of walk(base)) {
+      if (folder.only && !folder.only.test(from)) continue;
+      add(from, `${folder.to}/${posix(path.relative(base, from))}`);
+    }
+  }
+  /** @type {string[]} */
+  let verify = [];
+  const presetVerify = path.join(preset.dir, "verify.json");
+  if (isFile(presetVerify)) {
+    add(presetVerify, ".doctrina/verify.json");
+    try {
+      verify = (JSON.parse(read(presetVerify)).checks ?? []).map((/** @type {{ run?: string }} */ ch) => String(ch.run ?? "")).filter(Boolean);
+    } catch { /* an unreadable verify.json is reported by `doctrina verify` once copied */ }
+  }
+
+  /** @type {Record<string, any>} */
+  let current = {};
+  try {
+    current = JSON.parse(read(configPath(projectRoot)));
+  } catch { /* no config.json yet, or an unreadable one: nothing is declared */ }
+  const config = Object.entries(preset.config).map(([key, value]) => ({
+    key, value,
+    action: /** @type {"set" | "kept" | "same"} */ (!(key in current) ? "set"
+      : JSON.stringify(current[key]) === JSON.stringify(value) ? "same" : "kept"),
+  }));
+  return { files, config, verify };
+}
+
+/** How many things the plan would write. */
+export function presetPending(plan) {
+  return plan.files.filter((f) => f.action === "copy").length + plan.config.filter((c) => c.action === "set").length;
+}
+
+/** Write what the plan calls for. The caller re-derives the index. */
+export function applyPreset(projectRoot, preset, plan) {
+  for (const f of plan.files) {
+    if (f.action === "copy") write(path.join(projectRoot, f.rel), read(f.from));
+  }
+  const file = configPath(projectRoot);
+  /** @type {Record<string, any>} */
+  let current = {};
+  try {
+    current = JSON.parse(read(file));
+  } catch { /* written whole below */ }
+  /** @type {Record<string, any>} */
+  const next = { ...current };
+  for (const c of plan.config) if (c.action === "set") next[c.key] = c.value;
+  next.preset = preset.name;
+  write(file, JSON.stringify(next, null, 2) + "\n", { force: true });
+}
+
+/**
+ * The plan as lines a person reads: what is copied, what is kept and why,
+ * and — said every time — the commands a preset's verify.json would run.
+ * @param {boolean} written
+ * @returns {string[]}
+ */
+export function describePreset(preset, plan, written) {
+  const verb = written ? "copied    " : "would copy";
+  const lines = [`preset ${preset.name}${preset.description ? ` — ${preset.description}` : ""}`];
+  for (const f of plan.files) {
+    if (f.action === "copy") lines.push(`  ${verb} ${f.rel}`);
+    else if (f.action === "kept") lines.push(`  kept       ${f.rel} — ${f.note}`);
+  }
+  for (const c of plan.config) {
+    const shown = Array.isArray(c.value) ? `${c.value.length} rule${c.value.length === 1 ? "" : "s"}` : JSON.stringify(c.value);
+    if (c.action === "set") lines.push(`  ${written ? "set       " : "would set "} config ${c.key} = ${shown}`);
+    else if (c.action === "kept") lines.push(`  kept       config ${c.key} — the project declares another value`);
+  }
+  const copiesVerify = plan.files.some((f) => f.rel === ".doctrina/verify.json" && f.action === "copy");
+  if (copiesVerify && plan.verify.length > 0) {
+    lines.push(`  note       the preset's verify.json declares what \`doctrina verify\` RUNS on this machine: ${plan.verify.map((r) => `\`${r}\``).join(", ")} — read it before running the gate`);
+  }
+  const same = plan.files.filter((f) => f.action === "same").length;
+  if (same > 0) lines.push(`  same       ${same} file${same === 1 ? "" : "s"} already as the preset has ${same === 1 ? "it" : "them"}`);
+  if (presetPending(plan) === 0) lines.push("  nothing to add — the project already carries the preset");
+  return lines;
+}