doctrina-cli 0.20.0 → 0.22.0

package/src/lib/coverage-model.js

@@ -1,5 +1,6 @@
 // @ts-check
 import path from "node:path";
+import { PROPERTY_MARKER, propertyLibraryIn } from "./properties.js";
 import { readdirSync } from "node:fs";
 import { exists, isDir, isFile, read } from "./fs-ops.js";
 import { specHeader } from "./scan.js";
@@ -27,9 +28,11 @@ import { parseAcceptanceCriteria } from "./criteria.js";
 // never a --strict failure. Declared debt and hidden debt stop being punished
 // identically (0.11.0 field review item 4: one deferred capability poisoned
 // the close of every unrelated change).
-export function collect(projectRoot, { only = null } = {}) {
+export function collect(projectRoot, { only = /** @type {Set<string> | null} */ (null) } = {}) {
   const specsDir = path.join(projectRoot, ".doctrina", "specs");
   const reports = [];
+  /** @type {Map<string, boolean>} evidence file → is its suite skipped */
+  const skippedOf = new Map();
   if (isDir(specsDir)) {
     for (const cap of readdirSync(specsDir).sort()) {
       if (only && !only.has(cap)) continue;
@@ -40,7 +43,7 @@ export function collect(projectRoot, { only = null } = {}) {
       if (criteria.length === 0) continue;
       const deferred = isDeclaredDeferral(text);
       const rows = criteria.map((crit, i) => {
-        const row = classify(crit, i + 1, projectRoot, path.dirname(specPath));
+        const row = classify(crit, i + 1, projectRoot, path.dirname(specPath), skippedOf);
         if (deferred && row.kind !== "covered") {
           return { ...row, kind: "deferred", was: row.kind };
         }
@@ -145,7 +148,7 @@ export function deriveImplementation(row) {
  *
  * @returns {Map<string, {derived: string, covered: number, total: number, deferred: boolean, unverified: number}>}
  */
-export function derivedImplementations(projectRoot, { only = null } = {}) {
+export function derivedImplementations(projectRoot, { only = /** @type {Set<string> | null} */ (null) } = {}) {
   const out = new Map();
   for (const rep of collect(projectRoot, { only })) {
     const row = {
@@ -301,7 +304,7 @@ function evidenceClause(criterion) {
   return m ? criterion.slice(m.index) : null;
 }
 
-function classify(criterion, n, projectRoot, specDir) {
+function classify(criterion, n, projectRoot, specDir, skippedOf = /** @type {Map<string, boolean>} */ (new Map())) {
   // An orchestration criterion is judged on its GUARD, not on whether a
   // cited file exists — the whole point is that existence proves nothing here.
   const marker = criterion.match(/^\[([^\]]+)\]/)?.[1]?.toLowerCase() ?? "";
@@ -349,10 +352,30 @@ function classify(criterion, n, projectRoot, specDir) {
       continue;
     }
     const isTest = looksLikeTestFile(token);
-    const skipped = isTest && isFile(hit) ? testSuiteIsSkipped(read(hit)) : false;
-    resolved.push({ token, isTest, skipped });
+    // One read per evidence file, not one per criterion that cites it
+    // (change 0249): a suite that proves forty criteria was read and
+    // scanned forty times, on every `prime`, `status` and `validate`.
+    let skipped = false;
+    if (isTest && isFile(hit)) {
+      if (!skippedOf.has(hit)) skippedOf.set(hit, testSuiteIsSkipped(read(hit)));
+      skipped = skippedOf.get(hit) === true;
+    }
+    resolved.push({ token, isTest, skipped, hit });
   }
   if (resolved.length === 0) return { kind: "dangling", n, missing };
+  // A `[property]` criterion claims something of EVERY input (change 0254):
+  // the test it cites must be one that generates its inputs. An example
+  // test proves three cases; calling that proof of a universal claim is the
+  // false confidence this gate exists against.
+  if (PROPERTY_MARKER.test(marker)) {
+    const generating = resolved.find((r) => r.isTest && !r.skipped && propertyLibraryIn(read(r.hit)) !== null);
+    if (!generating) {
+      return {
+        kind: "unguarded", n, label: "property claim is proven by no property",
+        reason: `${resolved.map((r) => `\`${r.token}\``).join(", ")} generates no input — a [property] criterion is proven by a property-based test (Hypothesis \`@given\`, fast-check \`fc.property\`, jqwik \`@Property\`, proptest), or it is an example and its mark is [verified]`,
+      };
+    }
+  }
   // Runnable evidence: the resolving test-shaped citations, recorded so
   // `coverage --run` can execute them (existence → passing proof).
   const evidence = resolved.filter((r) => r.isTest && !r.skipped).map((r) => r.token);

package/src/lib/delivery.js

@@ -1,12 +1,13 @@
 // @ts-check
 import { readdirSync } from "node:fs";
 import path from "node:path";
-import { isDir, isFile, read, write } from "./fs-ops.js";
+import { eolOf, isDir, isFile, read, withEol, write } from "./fs-ops.js";
 import { listHeader } from "./scan.js";
-import { checklistProgress, setHeader } from "./doc-model.js";
+import { checklistProgress, maskComments, parseChecklist, setHeader } from "./doc-model.js";
+import { parseLedger } from "./ledger.js";
 import { terms } from "./lexicon.js";
 import { slugify, padNumber } from "./dates.js";
-import { artifactRootOf } from "./workspace.js";
+import { artifactRootOf, projectState } from "./workspace.js";
 
 // A DELIVERY is one item of work that crosses repositories (ADR 0030): a
 // story, a screen, a fix. It lives in the workspace's `deliveries/` and
@@ -72,8 +73,8 @@ export function setDeliveryHeader(wsDir, id, name, value) {
   let text = read(p);
   const next = setHeader(text, name, value);
   if (next !== null) text = next;
-  else text = text.replace(/^(- \*\*Projects:\*\*.*)$/m, `$1\n- **${name}:** ${value}`);
-  write(p, text, { force: true });
+  else text = text.replace(/^(- \*\*Projects:\*\*[^\r\n]*)/m, `$1\n- **${name}:** ${value}`);
+  write(p, withEol(text, eolOf(read(p))), { force: true });
 }
 
 /**
@@ -125,11 +126,11 @@ export function deliveryChanges(wsDir, ws, delivery) {
   for (const name of delivery.projects) {
     const project = ws.projects.find((p) => p.name === name);
     if (!project) {
-      out.push({ project: name, missing: "not registered in the workspace", changes: [] });
+      out.push({ project: name, missing: "not registered in the workspace", changes: /** @type {any[]} */ ([]) });
       continue;
     }
     const changesDir = path.join(artifactRootOf(wsDir, project), ".doctrina", "changes");
-    const changes = [];
+    const changes = /** @type {any[]} */ ([]);
     for (const { dir, archived } of [{ dir: changesDir, archived: false }, { dir: path.join(changesDir, "archive"), archived: true }]) {
       if (!isDir(dir)) continue;
       for (const entry of readdirSync(dir).sort()) {
@@ -138,16 +139,26 @@ export function deliveryChanges(wsDir, ws, delivery) {
         const text = read(proposal);
         if ((listHeader(text, "Delivery") ?? "").trim() !== delivery.id) continue;
         const tasks = path.join(dir, entry, "tasks.md");
-        const progress = isFile(tasks) ? checklistProgress(read(tasks)) : { total: 0, done: 0 };
+        const progress = isFile(tasks) ? checklistProgress(read(tasks)) : { total: 0, done: 0, placeholders: 0 };
         changes.push({
           id: archived ? entry.replace(/^\d{4}-\d{2}-\d{2}-/, "") : entry,
           archived,
           status: archived ? "archived" : (listHeader(text, "Status") ?? "proposed").toLowerCase(),
           tasksDone: progress.done, tasksTotal: progress.total,
+          // Scaffold boxes no one wrote (third audit, change 0234): counted
+          // as tasks, they read "3 tasks left — hand the next card" for a
+          // change whose card command answers that none is written.
+          placeholders: progress.placeholders ?? 0,
         });
       }
     }
-    out.push({ project: name, path: project.path, changes });
+    // Abandoned for this delivery: the ledger keeps the delivery's id (change 0234).
+    const ledger = path.join(changesDir, "archive", "LEDGER.md");
+    const abandoned = isFile(ledger)
+      ? parseLedger(read(ledger)).entries.filter((e) => e.kind === "abandoned" && new RegExp(`\\(delivery ${delivery.id}\\)\\s*$`).test(e.title))
+        .map((e) => ({ id: e.id, reason: e.title.replace(/^abandoned\s*(—\s*)?/i, "").replace(/\s*\(delivery [^)]*\)\s*$/, "") }))
+      : [];
+    out.push({ project: name, path: project.path, absent: !isDir(project.path), changes, abandoned });
   }
   return out;
 }
@@ -181,9 +192,9 @@ export function daysBetween(from, to) {
 export function recordBlockers(delivery) {
   const out = [];
   if (sectionText(delivery.text, "Story") === "") out.push("## Story is empty — copy the tracker item's story and acceptance criteria, verbatim");
-  const release = sectionText(delivery.text, "Release");
-  const open = release.split("\n").filter((l) => /^[-*]\s*\[\s\]/.test(l));
-  for (const box of open) out.push(`## Release: unticked — ${box.replace(/^[-*]\s*\[\s\]\s*/, "")}`);
+  // The same boxes `delivery tick` lists and ticks — one reader, so a box
+  // the check holds you to is always one the CLI can tick.
+  for (const box of releaseBoxes(delivery.text).filter((b) => !b.checked)) out.push(`## Release: unticked — ${box.text}`);
   if (sectionText(delivery.text, "Observability") === "") out.push("## Observability is empty — record what was watched after the release (monitor, dashboard or query, the window, what it showed)");
   return out;
 }
@@ -198,6 +209,8 @@ export function deliveryBlockers(wsDir, ws, delivery) {
   if (delivery.projects.length === 0) blockers.push("no project routed — `doctrina delivery route <id> <a,b>`");
   for (const row of deliveryChanges(wsDir, ws, delivery)) {
     if (row.missing) blockers.push(`${row.project}: ${row.missing}`);
+    else if (row.absent) blockers.push(`${row.project}: the repository is not at ${row.path} — \`doctrina workspace attach ${row.project} --path <dir>\``);
+    else if (row.changes.length === 0 && row.abandoned?.length) blockers.push(`${row.project}: its change ${row.abandoned.map((a) => a.id).join(", ")} was abandoned — re-route the delivery without ${row.project}, or open a new change there with \`doctrina work "<title>" --delivery ${delivery.id}\``);
     else if (row.changes.length === 0) blockers.push(`${row.project}: no change carries this delivery — open one there with \`doctrina work "<title>" --delivery ${delivery.id}\``);
     else for (const ch of row.changes.filter((x) => !x.archived)) {
       blockers.push(`${row.project}: change ${ch.id} is ${ch.status} (${ch.tasksDone}/${ch.tasksTotal} tasks) — close it there with \`doctrina close ${ch.id}\``);
@@ -206,3 +219,68 @@ export function deliveryBlockers(wsDir, ws, delivery) {
   blockers.push(...recordBlockers(delivery));
   return blockers;
 }
+
+/**
+ * The `## Release` boxes of a delivery, in order, with their line index in
+ * the LF-normalised text (change 0226). The other sections are prose the
+ * planner writes; these are claims, and a claim is ticked through the CLI.
+ */
+export function releaseBoxes(text) {
+  // One owner for the box grammar (ADR 0021): the document model reads the
+  // boxes; a box inside a comment is the template's example, not a claim.
+  const lf = String(text).replace(/\r\n/g, "\n");
+  return parseChecklist(maskComments(lf), { section: "Release" })
+    .filter((b) => b.section === "Release")
+    .map((b, i) => ({ ordinal: i + 1, line: b.line, checked: b.checked, text: b.text }));
+}
+
+/** The text with the given Release boxes ticked (all when `ordinals` is "all"). */
+export function tickRelease(text, ordinals) {
+  const lines = String(text).replace(/\r\n/g, "\n").split("\n");
+  for (const box of releaseBoxes(text)) {
+    if (ordinals === "all" || ordinals.includes(box.ordinal)) {
+      lines[box.line] = lines[box.line].replace(/\[\s\]/, "[x]");
+    }
+  }
+  return lines.join("\n");
+}
+
+/**
+ * Projects a delivery cannot be routed to yet (change 0226): one whose
+ * repository is missing, or one still `pending` — no spec to write a delta
+ * against, so the change opened there would have nothing to change.
+ * @returns {{ name: string, state: string, reason: string, path: string }[]}
+ */
+export function unroutable(wsDir, ws, names) {
+  const out = [];
+  for (const name of names) {
+    const project = ws.projects.find((p) => p.name === name);
+    if (!project) continue;
+    const st = projectState(wsDir, project);
+    if (st.state !== "ready") out.push({ name, state: st.state, reason: st.reason, path: project.path });
+  }
+  return out;
+}
+
+/**
+ * Open changes in a routed repository that do NOT belong to this delivery
+ * (change 0226). Each is a second writer the planner must sequence: one
+ * writer per repository at a time holds across deliveries too.
+ * @returns {{ project: string, id: string, delivery: string|null }[]}
+ */
+export function otherWriters(wsDir, ws, delivery) {
+  const out = [];
+  for (const name of delivery.projects) {
+    const project = ws.projects.find((p) => p.name === name);
+    if (!project) continue;
+    const changesDir = path.join(artifactRootOf(wsDir, project), ".doctrina", "changes");
+    if (!isDir(changesDir)) continue;
+    for (const entry of readdirSync(changesDir).sort()) {
+      const proposal = path.join(changesDir, entry, "proposal.md");
+      if (entry === "archive" || !isFile(proposal)) continue;
+      const of = (listHeader(read(proposal), "Delivery") ?? "").trim() || null;
+      if (of !== delivery.id) out.push({ project: name, id: entry, delivery: of });
+    }
+  }
+  return out;
+}

package/src/lib/docs-impact.js

@@ -123,7 +123,7 @@ function withoutVerification(text) {
   return out.join("\n");
 }
 
-export function documentedSurfaceSignals(changeDir, projectRoot = null) {
+export function documentedSurfaceSignals(changeDir, projectRoot = /** @type {string | null} */ (null)) {
   const signals = [];
   const known = new Set(COMMAND_NAMES);
 
@@ -257,10 +257,16 @@ export function documentedSurfaceSignals(changeDir, projectRoot = null) {
     signals.push(`endpoints: ${[...routes].sort().slice(0, 6).join(", ")}`);
   }
 
+  // An UPPER_SNAKE name is an environment variable when something says so
+  // (change 0239): the shape alone also matches an error code
+  // (`CONTA_BLOQUEADA`) or a constant (`MAX_FALHAS`), and every change that
+  // merely cited one was asked to document an "environment" it never touched.
+  const exampleNames = projectRoot === null ? new Set() : envExampleNames(projectRoot);
   const envVars = new Set();
   for (const m of code.matchAll(/\b([A-Z][A-Z0-9]*(?:_[A-Z0-9]+)+)\b/g)) {
     // Not twice: a declared variable is already reported by name above.
-    if (!touchedDeclared.includes(m[1])) envVars.add(m[1]);
+    if (touchedDeclared.includes(m[1])) continue;
+    if (looksLikeEnv(m[1], text) || exampleNames.has(m[1])) envVars.add(m[1]);
   }
   if (envVars.size > 0) {
     signals.push(`environment: ${[...envVars].sort().slice(0, 8).join(", ")}`);
@@ -408,3 +414,32 @@ export function checkDocsImpact(projectRoot, changeDir) {
     reason: "alters a documented surface but no docs/ or README change accompanies it",
   };
 }
+
+// The suffixes configuration read from the environment carries.
+const ENV_SUFFIX = /_(URL|URI|DSN|HOST|PORT|ENDPOINT|KEY|TOKEN|SECRET|PASSWORD|PASS|USER|USERNAME|PATH|DIR|FILE|HOME|ENV|MODE|LEVEL|TIMEOUT|REGION|BUCKET|ENABLED|DISABLED|DEBUG|FLAG|PROFILE)$/;
+
+/**
+ * Whether the change text marks a name as an environment variable: read the
+ * way code reads one (`process.env.X`, `$X`, `${X}`, `getenv("X")`,
+ * `os.environ["X"]`, `X=`), named on a line that speaks of the environment,
+ * or carrying a configuration suffix (`_URL`, `_TOKEN`, `_PORT`…).
+ * @param {string} name
+ * @param {string} text  the change's authored text
+ */
+export function looksLikeEnv(name, text) {
+  if (ENV_SUFFIX.test(name)) return true;
+  const n = name.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  if (new RegExp(`(process\\.env\\.|process\\.env\\[["'\`]|\\benv\\.|\\$\\{?|getenv\\(["']|environ(?:\\.get\\(|\\[)["']|ENV\\[["'])${n}\\b|\\b${n}=`).test(text)) return true;
+  return text.split("\n").some((line) => line.includes(name) && /\b(env|environment|environment variable|variável de ambiente|ambiente|secret|segredo|\.env)\b/i.test(line));
+}
+
+/** The variable names a project's env example files declare. */
+function envExampleNames(projectRoot) {
+  const out = new Set();
+  for (const f of [".env.example", ".env.sample", ".env.template", ".env.dist", "example.env"]) {
+    const file = path.join(projectRoot, f);
+    if (!isFile(file)) continue;
+    for (const m of read(file).matchAll(/^\s*(?:export\s+)?([A-Z][A-Z0-9_]*)\s*=/gm)) out.add(m[1]);
+  }
+  return out;
+}

package/src/lib/fs-ops.js

@@ -19,17 +19,91 @@ import path from "node:path";
 // A file that had one loses it when a command rewrites it. That is a
 // normalisation, and the right one — nothing in this tree is served by
 // keeping it.
+/**
+ * The line ending a file already uses: CRLF when it carries one, LF otherwise.
+ * A command that rewrites a file a person owns keeps the file's ending — a
+ * Windows checkout with `core.autocrlf` stores CRLF, and turning it into LF
+ * on a tick makes every line of the file show as changed in the diff.
+ * @param {string} text
+ * @returns {"\r\n"|"\n"}
+ */
+export function eolOf(text) {
+  return /\r\n/.test(String(text)) ? "\r\n" : "\n";
+}
+
+/**
+ * `text` with every line ending made `eol` — what a rewrite hands to `write`
+ * after editing in LF, so an inserted line never mixes endings.
+ * @param {string} text
+ * @param {"\r\n"|"\n"} eol
+ */
+export function withEol(text, eol) {
+  const lf = String(text).replace(/\r\n/g, "\n");
+  return eol === "\n" ? lf : lf.replace(/\n/g, "\r\n");
+}
+
+// ...and so is the line ending (seventh audit, change 0250).
+//
+// A Windows checkout with `core.autocrlf` stores every artifact with CRLF,
+// and the grammar was read with patterns written for LF. `.*$` does not
+// cross a `\r`, so a header stamp matched nothing and reported success; a
+// placeholder bullet `-\r` read as an empty requirement, and a fresh spec
+// carried five EARS warnings an LF checkout never saw; a line diff showed
+// the whole file as changed. Each was fixed where it was found, one caller
+// at a time (`eolOf`/`withEol`), and the next caller forgot.
+//
+// So the rule is the door's: text is READ with LF, whatever the file holds,
+// and WRITTEN BACK with the ending the file already has. No parser
+// downstream has to know which checkout it is running in, and a rewrite
+// never mixes endings or turns a file's every line into a diff.
 export function read(p) {
   const text = readFileSync(p, "utf8");
-  return text.charCodeAt(0) === 0xFEFF ? text.slice(1) : text;
+  const body = text.charCodeAt(0) === 0xFEFF ? text.slice(1) : text;
+  return body.includes("\r\n") ? body.replace(/\r\n/g, "\n") : body;
+}
+
+/** Does the file at `p` end its lines with CRLF today? False when absent or unreadable. */
+function storedAsCrlf(p) {
+  try {
+    return readFileSync(p, "utf8").includes("\r\n");
+  } catch {
+    return false;
+  }
 }
 
-export function write(p, content, { force = false } = {}) {
-  if (existsSync(p) && !force) {
+export function write(p, content, { force = false, atomic = false } = {}) {
+  const there = existsSync(p);
+  if (there && !force) {
     throw new Error(`refusing to overwrite existing file: ${p} (pass --force to allow)`);
   }
   mkdirSync(path.dirname(p), { recursive: true });
-  writeFileSync(p, content);
+  // A rewrite keeps the ending the file has; a new file is written as given.
+  const text = there && typeof content === "string" && storedAsCrlf(p)
+    ? content.replace(/\r\n/g, "\n").replace(/\n/g, "\r\n")
+    : content;
+  if (!atomic) {
+    writeFileSync(p, text);
+    return;
+  }
+  // Whole or not at all: written beside the target and moved over it, so a
+  // command reading the file at that instant never sees half of it. Where the
+  // move is refused (a reader holding the file open on Windows) the plain
+  // write still lands.
+  const tmp = `${p}.${process.pid}.tmp`;
+  try {
+    writeFileSync(tmp, text);
+    renameSync(tmp, p);
+  } catch {
+    writeFileSync(p, text);
+    try {
+      unlinkSync(tmp);
+    } catch { /* never created, or already moved */ }
+  }
+}
+
+/** Append `line` to the text file at `p`, with the ending the file already uses. */
+export function appendLine(p, line) {
+  writeFileSync(p, `${line}${storedAsCrlf(p) ? "\r\n" : "\n"}`, { flag: "a" });
 }
 
 export function exists(p) {
@@ -110,17 +184,34 @@ export function pruneEmptyDirs(dir, stopAt) {
   return removed;
 }
 
-// Recursive file walk. Returns absolute paths of every regular file.
-export function walk(root) {
+// Recursive file walk. Returns absolute paths of every regular file, sorted.
+//
+// The directory listing already says what each entry is, so it is asked
+// once (change 0249): the walk used to `stat` every entry twice — is it a
+// directory? is it a file? — which was a third of `validate`'s time on this
+// repository. A symbolic link is still followed with a `stat`, as before.
+// `depth` bounds how far down it goes: 1 is the files directly in `root`.
+/**
+ * @param {string} root
+ * @param {{ depth?: number }} [opts]
+ * @returns {string[]}
+ */
+export function walk(root, { depth = Infinity } = {}) {
+  /** @type {string[]} */
   const out = [];
   if (!exists(root)) return out;
-  const stack = [root];
+  /** @type {[string, number][]} */
+  const stack = [[root, 1]];
   while (stack.length) {
-    const dir = stack.pop();
-    for (const entry of readdirSync(dir)) {
-      const full = path.join(dir, entry);
-      if (isDir(full)) stack.push(full);
-      else if (isFile(full)) out.push(full);
+    const [dir, level] = /** @type {[string, number]} */ (stack.pop());
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+      const full = path.join(dir, entry.name);
+      const link = entry.isSymbolicLink();
+      if (link ? isDir(full) : entry.isDirectory()) {
+        if (level < depth) stack.push([full, level + 1]);
+      } else if (link ? isFile(full) : entry.isFile()) {
+        out.push(full);
+      }
     }
   }
   return out.sort();

package/src/lib/gates.js

@@ -67,7 +67,7 @@ export const GATES = {
     blockers(projectRoot, changeDir) {
       const out = [];
       // Same counter as every other surface (change 0067).
-      const countUnchecked = (text, section = null) =>
+      const countUnchecked = (text, section = /** @type {string | null} */ (null)) =>
         checklistProgress(text, { section }).total - checklistProgress(text, { section }).done;
 
       const tasksPath = path.join(changeDir, "tasks.md");
@@ -224,6 +224,12 @@ export const SEQUENCES = {
     // the CLI's source, which is how a pt-BR project sat red under `clarify`
     // with no clue why (change 0047). Advisory: a default is not a fault.
     { id: "config", label: "config", level: "advisory", argv: null, rerun: "edit .doctrina/config.json" },
+    // Which `doctrina` the terminal runs, and how the repository merges
+    // (changes 0242, 0243). Readouts of the machine and the clone, not of the
+    // artifacts: the hooks call `doctrina` by name, so a second install ahead
+    // on the PATH is the one they run.
+    { id: "cli", label: "cli", level: "advisory", argv: null, rerun: "doctrina --version" },
+    { id: "merges", label: "merges", level: "advisory", argv: null, rerun: "doctrina hooks install" },
     // Also a readout, and also advisory. It appears only when the operator
     // has switched the usage log on: an instrument that is off has nothing
     // to say, and a row saying so every run would train the reader to skip

package/src/lib/git.js

@@ -69,6 +69,24 @@ export function git(cwd, args, { env } = {}) {
   return { state: GIT_STATE.FAILED, stdout: "", lines: [], stderr, code: r.status };
 }
 
+/**
+ * Where git keeps `name` for the repository `cwd` is in — `hooks`,
+ * `info/exclude` — as an absolute path, or null outside a repository. Asked
+ * of git, never built from `.git/`: in a worktree and in a submodule `.git`
+ * is a FILE, and `core.hooksPath` moves the hooks anywhere (change 0250).
+ */
+export function gitPathOf(cwd, name) {
+  const r = git(cwd, ["rev-parse", "--git-path", name]);
+  if (r.state !== GIT_STATE.OK || r.stdout.trim() === "") return null;
+  return path.resolve(cwd, r.stdout.trim());
+}
+
+/** `cwd` relative to the top of its repository, with forward slashes ("" at the top), or null outside one. */
+export function repoPrefix(cwd) {
+  const r = git(cwd, ["rev-parse", "--show-prefix"]);
+  return r.state === GIT_STATE.OK ? r.stdout.trim().replace(/\/+$/, "") : null;
+}
+
 // Is this a git repository at all?
 export function isRepo(cwd) {
   return git(cwd, ["rev-parse", "--is-inside-work-tree"]).state === GIT_STATE.OK;

package/src/lib/index-json.js

@@ -30,6 +30,12 @@ export function load(projectRoot) {
   try {
     return JSON.parse(raw);
   } catch (err) {
+    // Conflict markers are the one way this file usually stops parsing
+    // (change 0242): two branches closed a change each, and git merged the
+    // derived index as text. Said as what it is, with the two ways out.
+    if (/^(<{7}|={7}|>{7})( |$)/m.test(raw)) {
+      throw new Error(".doctrina/index.json carries git's merge conflict markers — it is derived, so `doctrina index rebuild` writes it again from the tree (and `doctrina hooks install` makes git merge it by itself)");
+    }
     throw new Error(`.doctrina/index.json is not valid JSON: ${err.message}`);
   }
 }
@@ -42,7 +48,10 @@ export function save(projectRoot, index) {
   index.framework_version = newestVersion(index.framework_version, cliVersion());
   const p = indexPath(projectRoot);
   const text = JSON.stringify(index, null, 2) + "\n";
-  write(p, text, { force: true });
+  // Atomic (change 0250): every command reads this file, and one that read
+  // it while another was half-way through writing it stopped with
+  // "Unexpected end of JSON input".
+  write(p, text, { force: true, atomic: true });
 }
 
 export function blank(projectName, date) {

package/src/lib/index-merge.js

@@ -0,0 +1,90 @@
+// @ts-check
+import { ARTIFACT_CATEGORIES } from "./index-json.js";
+import { newestVersion } from "./version.js";
+
+// THE INDEX MERGES AS WHAT IT IS: A LIST OF ARTIFACTS (change 0242).
+//
+// `index.json` is one file every change rewrites — a version here, a closed
+// change appended there, the date on top. Two branches that each close a
+// change therefore meet on the same lines, and git, which merges text, stops
+// with conflict markers in a file nobody wrote by hand.
+//
+// Merged as data there is nothing to resolve: an entry one branch added is
+// added, an entry one branch removed is removed, and where both changed the
+// same field the newer value wins — a version only grows, a date only moves
+// forward. What this cannot know (a header edited on both sides) the tree
+// still decides: `doctrina index rebuild` derives the index from the files,
+// and the commit hook runs it.
+
+const key = (/** @type {any} */ entry) => String(entry?.path ?? entry?.id ?? "");
+const same = (/** @type {any} */ a, /** @type {any} */ b) => JSON.stringify(a) === JSON.stringify(b);
+
+/** `1.10.0` over `1.9.0`; anything that is not three numbers compares as text. */
+function laterVersion(a, b) {
+  const parts = (/** @type {string} */ v) => String(v).split(".").map((n) => Number(n));
+  const [x, y] = [parts(a), parts(b)];
+  if (x.some(Number.isNaN) || y.some(Number.isNaN)) return String(a) >= String(b) ? a : b;
+  for (let i = 0; i < Math.max(x.length, y.length); i++) {
+    if ((x[i] ?? 0) !== (y[i] ?? 0)) return (x[i] ?? 0) > (y[i] ?? 0) ? a : b;
+  }
+  return a;
+}
+
+/** Both sides changed `field` to different values: the one that moved furthest. */
+function settle(field, ours, theirs) {
+  if (field === "framework_version") return newestVersion(ours, theirs);
+  if (field === "version") return laterVersion(ours, theirs);
+  if (/(^|_)(updated|date)$/.test(field)) return String(ours) >= String(theirs) ? ours : theirs;
+  return ours;
+}
+
+/** Three-way merge of one object's fields. */
+function mergeFields(base, ours, theirs) {
+  /** @type {Record<string, any>} */
+  const out = {};
+  for (const field of new Set([...Object.keys(ours ?? {}), ...Object.keys(theirs ?? {})])) {
+    const [b, o, t] = [base?.[field], ours?.[field], theirs?.[field]];
+    let value;
+    if (same(o, t) || same(t, b)) value = o;
+    else if (same(o, b)) value = t;
+    else if (o === undefined || t === undefined) value = o ?? t;
+    else value = settle(field, o, t);
+    if (value !== undefined) out[field] = value;
+  }
+  return out;
+}
+
+/** Three-way merge of one artifact category, in the order a rebuild writes. */
+function mergeList(base, ours, theirs) {
+  const by = (/** @type {any[]} */ list) => new Map((list ?? []).map((e) => [key(e), e]));
+  const [b, o, t] = [by(base), by(ours), by(theirs)];
+  const out = [];
+  for (const k of new Set([...o.keys(), ...t.keys()])) {
+    const [eb, eo, et] = [b.get(k), o.get(k), t.get(k)];
+    if (eo && et) out.push(mergeFields(eb, eo, et));
+    // Present on one side only: added there, or removed on the other. An
+    // entry the base never had was added; one it had was removed — unless
+    // the side that kept it also changed it, which a removal must not erase.
+    else if (!eb) out.push(eo ?? et);
+    else if (!same(eo ?? et, eb)) out.push(eo ?? et);
+  }
+  return out.sort((x, y) => (key(x) < key(y) ? -1 : key(x) > key(y) ? 1 : 0));
+}
+
+/**
+ * Merge two indexes that descend from `base`. Pure: returns the merged index.
+ * @param {any} base  the common ancestor (`{}` when there is none)
+ * @param {any} ours
+ * @param {any} theirs
+ */
+export function mergeIndex(base, ours, theirs) {
+  const out = mergeFields({ ...base, artifacts: undefined }, { ...ours, artifacts: undefined }, { ...theirs, artifacts: undefined });
+  const [ab, ao, at] = [base?.artifacts ?? {}, ours?.artifacts ?? {}, theirs?.artifacts ?? {}];
+  /** @type {Record<string, any>} */
+  const artifacts = {};
+  for (const cat of new Set([...Object.keys(ao), ...Object.keys(at)])) {
+    const list = ARTIFACT_CATEGORIES.includes(cat) || Array.isArray(ao[cat] ?? at[cat]);
+    artifacts[cat] = list ? mergeList(ab[cat], ao[cat], at[cat]) : mergeFields(ab[cat], ao[cat] ?? {}, at[cat] ?? {});
+  }
+  return { ...out, artifacts };
+}