doctrina-cli 0.21.0 → 0.22.0

package/README.md

@@ -3,7 +3,7 @@
 > CLI for the Doctrina framework. The package is published as
 > `doctrina-cli`; the executable it installs is `doctrina`.
 
-**Status:** v0.21.0 — current release. Zero runtime dependencies
+**Status:** v0.22.0 — current release. Zero runtime dependencies
 (Node.js standard library only).
 
 ## Install
@@ -23,14 +23,14 @@ read `AGENTS.md` and run `doctrina next` — it drives the rest. The
 surface, by the moment you reach for it:
 
 ```
-Bootstrap   init · intake · adapter list|add|remove
+Bootstrap   init · ui · onboard · intake · adapter list|add|remove
 Orient      prime · next · status · context · show · search · why · handoff
-Change      triage · work · spec new|list|set · change new|apply|archive|check|tick|abandon|delta|card
+Change      triage · work · spec new|list|set · change new|apply|archive|check|tick|abandon|renumber|delta|card
             contract new|list|check · decision new|accept|land|supersede|list|scope
             skill new|list|suggest · intent add|list
 Gate        clarify · validate · coverage · trace · review · verify · close · doctor
 Orchestrate workspace init|add|attach|detach|list|tool|guard · delivery new|route|list|status|tick|check|close
-Maintain    upgrade · index rebuild · hooks install · watch · metrics · completion · ci · templates list
+Maintain    upgrade · index rebuild|merge · hooks install · watch · metrics · completion · ci · templates list
 ```
 
 `doctrina --help` prints the same grouping with one line per command, and
@@ -44,7 +44,7 @@ code is in the
 |------|---------|
 | `--project-name <name>` | Override the project name (defaults to cwd basename) |
 | `--project-description <text>` | One-sentence description, with no intake. Without it on a terminal, `init` asks you to describe the project once and keeps the answer as the intake |
-| `--agent <name>` | Install the adapter for one of the twelve supported agents (`claude`, `codex`, `cursor`, `copilot`, `gemini`, `aider`, `windsurf`, `continue`, `amp`, `devin`, `factory`, `jules`) or `all` |
+| `--agent <name>` | Install the adapter for one of the 13 supported agents (`claude`, `codex`, `cursor`, `copilot`, `gemini`, `aider`, `windsurf`, `continue`, `amp`, `devin`, `factory`, `jules`, `kiro`) or `all` |
 | `--date <YYYY-MM-DD>` | Override the system date in artifacts |
 | `--force` | Overwrite existing files |
 | `--non-interactive` | Fail instead of prompting for missing required values |
@@ -57,7 +57,7 @@ code is in the
   `alwaysApply: true` pointing at `AGENTS.md`. `copilot`, `gemini`,
   `aider`, `windsurf`, and `continue` follow the same thin-pointer
   pattern at each agent's native path.
-- `--agent codex` (and `amp`, `devin`, `factory`, `jules`) installs
+- `--agent codex` (and `amp`, `devin`, `factory`, `jules`, `kiro`) installs
   nothing: these agents read `AGENTS.md` natively.
 - `--agent all` installs every adapter.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "doctrina-cli",
-  "version": "0.21.0",
+  "version": "0.22.0",
   "description": "Doctrina CLI — spec-driven, AGENTS.md-native framework for multi-agent AI development.",
   "license": "MIT",
   "keywords": [

package/src/commands/change.js

@@ -19,16 +19,19 @@ import { confirm, isInteractive } from "../lib/prompt.js";
 import { taskCard } from "../lib/task-card.js";
 import { EXIT } from "../lib/exit-codes.js";
 import { ensureDoctrinaProject, refuseChangeRef } from "../lib/project.js";
+import { renumberChange } from "../lib/change-numbers.js";
+import { appliedDeltas, deltaFingerprint, deltaKey, pendingOps, recordAppliedDeltas } from "../lib/applied-deltas.js";
 import { parseOperation, parseCapabilityFromDelta, isUntouchedScaffold } from "../lib/doc-model.js";
 import { changeNew, addDeltaOps } from "../lib/change-ops.js";
+import { propertyShape } from "../lib/properties.js";
 import { scanText } from "../lib/clarify-scan.js";
 
-const SUBCOMMANDS = ["new", "apply", "archive", "check", "tick", "abandon", "delta", "card"];
+const SUBCOMMANDS = ["new", "apply", "archive", "check", "tick", "abandon", "renumber", "delta", "card"];
 
 // Flags this command accepts. Declared HERE, with the command, so
 // adding a command never requires editing the entrypoint — the gap that
 // let six flags ship undeclared and silently swallow a positional (C3).
-export const flags = { boolean: ["json", "all", "chore", "design", "force", "no-spec", "verbose"], string: ["reason", "requirement", "criterion", "bump", "op"] };
+export const flags = { boolean: ["json", "all", "chore", "design", "force", "no-spec", "verbose"], string: ["reason", "requirement", "criterion", "property", "bump", "op"] };
 
 export async function run(positional, flags) {
   const sub = positional[0];
@@ -46,6 +49,8 @@ export async function run(positional, flags) {
       return changeTick(positional.slice(1), flags);
     case "abandon":
       return await changeAbandon(positional.slice(1), flags);
+    case "renumber":
+      return changeRenumber(positional.slice(1));
     case "delta":
       return changeDelta(positional.slice(1), flags);
     case "card":
@@ -89,7 +94,7 @@ function changeCard(args) {
   const { card, reason } = taskCard(projectRoot, id, ordinal);
   if (!card) {
     console.log(c.gray(reason));
-    return reason.startsWith("every task") ? EXIT.OK : EXIT.PRECONDITION;
+    return (reason ?? "").startsWith("every task") ? EXIT.OK : EXIT.PRECONDITION;
   }
   const L = [];
   L.push(`# Task card — ${card.change}, task ${card.ordinal} of ${card.total}` + (card.checked ? " (already ticked)" : ""));
@@ -242,21 +247,53 @@ function changeApply(args, flags) {
   const proposalPath = path.join(changeDir, "proposal.md");
   const alreadyApplied = isFile(proposalPath)
     && (getHeader(read(proposalPath), "Status") ?? "").trim().toLowerCase() === "applied";
+  const allDeltas = walk(path.join(changeDir, "specs")).filter((p) => p.endsWith("delta.md"));
+  // WHICH deltas the stamp covers (change 0247). The stamp is the change's,
+  // and a change is not finished when it is stamped: a close that applied
+  // and then stopped at a later gate leaves it `applied`, and the fix for
+  // that gate is often one more delta. The stamp said "nothing to do", the
+  // close went on, and the change was archived naming a spec it had never
+  // touched. The record names each delta that was applied, with what it held.
+  /** @type {Map<string, Set<number> | null> | null} delta → the ops still to apply (null: the whole delta) */
+  let lateOnly = null;
   if (alreadyApplied && !flagBool(flags, "force", false)) {
-    console.log(c.gray("skip ") + `change "${id}" is already applied — nothing to do`);
-    console.log(c.gray("The ops verbs are additive: applying twice duplicates every"));
-    console.log(c.gray("requirement this delta carries. Re-apply anyway with --force"));
-    console.log(c.gray("only after reverting the specs to their pre-apply state."));
-    return 0;
+    const record = appliedDeltas(read(proposalPath));
+    const late = new Map();
+    const edited = [];
+    for (const p of record ? allDeltas : []) {
+      const recorded = record?.get(deltaKey(changeDir, p));
+      if (!recorded) {
+        late.set(p, null);
+        continue;
+      }
+      const { fresh, gone } = pendingOps(recorded, deltaFingerprint(read(p)));
+      if (gone) edited.push(p);
+      else if (fresh.length > 0) late.set(p, new Set(fresh));
+    }
+    if (edited.length > 0) {
+      console.error(c.red("error:") + ` ${edited.map((p) => relPath(changeDir, p)).join(", ")}: an op that was already applied changed or was removed — the spec holds what it wrote, and applying the delta again would add to that, not replace it`);
+      console.error(c.gray("hint: ") + "restore the op as it was applied and add the correction as a new op (`replace-requirement`, `replace-criterion`, `doctrina change delta`), or revert the spec to its pre-apply state and run `doctrina change apply " + id + " --force`");
+      return 1;
+    }
+    if (late.size === 0) {
+      console.log(c.gray("skip ") + `change "${id}" is already applied — nothing to do`);
+      console.log(c.gray("The ops verbs are additive: applying twice duplicates every"));
+      console.log(c.gray("requirement this delta carries. Re-apply anyway with --force"));
+      console.log(c.gray("only after reverting the specs to their pre-apply state."));
+      return 0;
+    }
+    const what = [...late].map(([p, ops]) => `${relPath(changeDir, p)}${ops ? ` (${ops.size} new op${ops.size === 1 ? "" : "s"})` : ""}`).join(", ");
+    console.log(c.gray("note: ") + `change "${id}" was applied before this was added — applying only ${what}`);
+    lateOnly = late;
   }
 
   // The skip above comes FIRST (change 0221): the apply gate is a pre-apply
   // question, and on an applied change its ADDED check reads the content the
   // apply wrote as a conflict — which refused the resume of a killed close.
-  const applyGate = enforceTransition(projectRoot, id, changeDir, "apply", flags);
+  const applyGate = lateOnly ? { ok: true, forced: null } : enforceTransition(projectRoot, id, changeDir, "apply", flags);
   if (!applyGate.ok) return 1;
 
-  const deltaFiles = walk(path.join(changeDir, "specs")).filter((p) => p.endsWith("delta.md"));
+  const deltaFiles = lateOnly ? [...lateOnly.keys()] : allDeltas;
   const date = today();
   let errors = 0;
   let writes = 0;
@@ -310,7 +347,8 @@ function changeApply(args, flags) {
       // `ops` block (set-header / bump-version / set-criterion / ...; F3);
       // otherwise it falls back to the historical manual-merge pointer, so
       // prose deltas keep working unchanged.
-      const ops = extractOps(text);
+      const only = lateOnly?.get(deltaPath) ?? null;
+      const ops = extractOps(text).filter((_op, i) => only === null || only.has(i));
       if (ops.length === 0) {
         console.log(c.yellow("manual[MODIFIED]") + ` merge ${relPath(projectRoot, deltaPath)} into ${relPath(projectRoot, targetPath)} by hand (no ops block)`);
         manual += 1;
@@ -353,6 +391,10 @@ function changeApply(args, flags) {
         console.log(c.green("status") + " proposal.md → applied");
         flippedToApplied = true;
       }
+      // Every delta the proposal's stamp now covers, with what it held.
+      const stamped = read(proposalPath);
+      const withRecord = recordAppliedDeltas(stamped, allDeltas.map((p) => [deltaKey(changeDir, p), deltaFingerprint(read(p))]));
+      if (withRecord !== stamped) write(proposalPath, withRecord, { force: true });
     }
   }
 
@@ -520,6 +562,9 @@ function changeDelta(args, flags) {
   const bump = flagString(flags, "bump");
   for (const r of flagAll(flags, "requirement")) lines.push(`append-requirement ${r}`);
   for (const r of flagAll(flags, "criterion")) lines.push(`append-criterion ${r}`);
+  // A criterion that claims something of every input (change 0254): the
+  // mark is what makes coverage ask the cited test to be a property.
+  for (const r of flagAll(flags, "property")) lines.push(`append-criterion [property] ${r.replace(/^\[property\]\s*/i, "")}`);
   lines.push(...raw);
   if (bump) lines.push(`bump-version ${bump}`);
 
@@ -531,7 +576,23 @@ function changeDelta(args, flags) {
     return r.code;
   }
   console.log(c.green(r.created ? "created" : "updated") + ` ${r.deltaRel}` +
-    c.gray(` — ${lines.length} op${lines.length === 1 ? "" : "s"} added; the block now holds ${r.block.length} (${r.block.join(", ")}), and applies cleanly`));
+    c.gray(` — ${lines.length} op${lines.length === 1 ? "" : "s"} added; the block now holds ${(r.block ?? []).length} (${(r.block ?? []).join(", ")}), and applies cleanly`));
+  // The moment the requirement is written is the moment its proof is
+  // chosen (change 0254): one that claims something of every input is told
+  // so here, while the test for it does not exist yet.
+  if (flagAll(flags, "property").length === 0) {
+    let noted = 0;
+    for (const req of flagAll(flags, "requirement")) {
+      const shape = propertyShape(req.replace(/^[a-z-]+:\s*/i, ""));
+      if (!shape) continue;
+      noted++;
+      console.log(c.yellow("note: ") + `"${req.length > 70 ? req.slice(0, 69) + "…" : req}" reads as ${shape.id === "invariant" ? "an invariant" : shape.id} — ${shape.property}.`);
+    }
+    if (noted > 0) {
+      console.log(c.gray("  An example test proves the cases somebody thought of. If a failure here would be a bug, write a property test and claim it: ") +
+        c.cyan(`doctrina change delta ${id} ${capability} --property "<what holds for every input> — verified by \`<the property test>\`"`));
+    }
+  }
   console.log(c.gray("Preview the merge: ") + c.cyan(`doctrina change check ${id} --verbose`));
   return EXIT.OK;
 }
@@ -827,6 +888,34 @@ async function changeAbandon(args, flags) {
   return 0;
 }
 
+// Give an open change the next free number (change 0242): two branches that
+// each opened a change took the same one, and the merge holds both.
+function changeRenumber(args) {
+  const id = args[0];
+  if (!id) {
+    console.error(c.red("error:") + " change renumber requires <id>");
+    return 2;
+  }
+  const refused = refuseChangeRef(id);
+  if (refused !== null) return refused;
+  const projectRoot = process.cwd();
+  ensureDoctrinaProject(projectRoot);
+  const changeDir = path.join(projectRoot, ".doctrina", "changes", id);
+  if (!isDir(changeDir)) {
+    console.error(c.red("error:") + ` change "${id}" is not an open change (${relPath(projectRoot, changeDir)} not found) — an archived change keeps its number`);
+    return EXIT.USAGE;
+  }
+  const { to, rewritten } = renumberChange(projectRoot, id);
+  console.log(c.green("renumbered") + ` ${id} → ${to}`);
+  if (rewritten.length > 0) console.log(c.gray(`  the id was rewritten in ${rewritten.join(", ")}`));
+  const derived = deriveIndex(projectRoot, idx.load(projectRoot));
+  derived.last_updated = today();
+  idx.save(projectRoot, derived);
+  console.log(c.green("indexed") + ` change "${to}" in index.json`);
+  console.log(c.gray("next: ") + `name ${to} wherever the old number was written outside the change — a commit message, a branch, a task card already handed out`);
+  return 0;
+}
+
 // The per-delta preview: what applying this delta would do to its target.
 // ADDED reports the body it would write, REMOVED the spec it would delete,
 // MODIFIED a line diff against the current spec.
@@ -953,15 +1042,23 @@ Subcommands:
                          or every one with --all. No args = list only.
   abandon <id>           Delete an open change folder and its index entry, and
                          record the abandonment in the ledger ([--reason "..."]).
+  renumber <id>          Give an open change the next free number: the folder
+                         moves and the id is rewritten in its own files. For
+                         the merge that brought together two changes opened
+                         on two branches under one number — \`validate\` names it.
   delta <id> <capability> [--requirement "<section>: <text>"] [--criterion "<text>"]
-        [--bump major|minor|patch] [--op "<op line>" | <op line>]
+        [--property "<text>"] [--bump major|minor|patch] [--op "<op line>" | <op line>]
                          Write ops into the change's MODIFIED delta for the
                          capability — created from the template when absent —
                          parsed by the grammar apply reads and dry-run against
                          the spec first: nothing is written unless the whole
                          block applies. --requirement, --criterion and --op
                          repeat, one op each, in order; a second --bump
-                         replaces the first.
+                         replaces the first. --property writes a criterion
+                         marked [property]: a claim about every input, which
+                         coverage counts only when the test it cites is
+                         property-based (\`doctrina coverage --properties\`
+                         lists the requirements that read as one).
   card <id> [<n>]        Print task <n> (default: the next open one) as a
                          self-contained card for an executor: the task and the
                          lines indented under it (Files:, Requirement:, Verify:),

package/src/commands/clarify.js

@@ -15,7 +15,7 @@ import { EXIT, notADoctrinaProject } from "../lib/exit-codes.js";
 // guessing; persist it with .doctrina/config.json { "language": "pt-BR" }.
 function forcedLang(flags) {
   const raw = flagString(flags, "lang");
-  if (!raw || raw === true) return null;
+  if (!raw) return null;
   const lang = String(raw).toLowerCase();
   if (lang.startsWith("pt")) return "pt";
   if (lang.startsWith("en")) return "en";
@@ -73,7 +73,7 @@ export async function run(positional, flags) {
 // and clarify each. ADRs are immutable and the archive is history, so
 // neither is included; AGENTS.md is dense command text, a different
 // register from prose specs.
-function clarifyAll(projectRoot, lang = null) {
+function clarifyAll(projectRoot, lang = /** @type {string | null} */ (null)) {
   if (!exists(path.join(projectRoot, ".doctrina"))) {
     throw notADoctrinaProject();
   }

package/src/commands/close.js

@@ -463,7 +463,7 @@ async function closeOne(projectRoot, id, flags) {
     if (isFile(ledgerPath)) {
       // Written in the ledger's own entry grammar (change 0046): a waived
       // gate no reader can find is the same as an unrecorded one.
-      appendLedgerLine(projectRoot, docsGapLine(id, docsGap.signals));
+      appendLedgerLine(projectRoot, docsGapLine(id, /** @type {{ signals: string[] }} */ (/** @type {unknown} */ (docsGap)).signals));
       console.log(c.yellow("ledger") + " recorded the docs gap");
     }
   }

package/src/commands/coverage.js

@@ -3,6 +3,7 @@ import path from "node:path";
 import process from "node:process";
 import { spawnSync } from "node:child_process";
 import { exists, isFile, read, relPath } from "../lib/fs-ops.js";
+import { propertyCandidates, projectPropertyLibrary } from "../lib/properties.js";
 import { flagBool, flagString } from "../lib/args.js";
 import { c } from "../lib/colors.js";
 import { emitJson } from "../lib/json-out.js";
@@ -39,7 +40,7 @@ export { collect, summarize, deriveImplementation, derivedImplementations, imple
 // wrap it in the generic envelope.
 export const jsonNative = true;
 
-export const flags = { boolean: ["json", "run", "strict"], string: ["only"] };
+export const flags = { boolean: ["json", "run", "strict", "properties"], string: ["only"] };
 
 export async function run(_positional, flags) {
   const projectRoot = process.cwd();
@@ -77,6 +78,11 @@ export async function run(_positional, flags) {
     }
   }
 
+  // --properties: which requirements read as claims about EVERY input, and
+  // so ask for a property-based test (change 0254). A readout, exit 0: it
+  // proposes; the `[property]` mark on a criterion is what the gate enforces.
+  if (flagBool(flags, "properties", false)) return listProperties(projectRoot, only, json);
+
   const reports = collect(projectRoot, { only });
 
   // --run: execute the cited evidence instead of only checking it exists —
@@ -153,8 +159,8 @@ export async function run(_positional, flags) {
         if (r.unverified) {
           console.log(`    ${c.gray("○")} #${r.n}  proof resolves but the criterion is still marked [unverified] — flip the mark when the test proves it (spec set <cap> --criterion ${r.n}:verified)`);
         }
-        if (r.missing?.length > 0) {
-          console.log(`    ${c.yellow("!")} #${r.n}  also cites evidence that does not resolve: ${r.missing.map((m) => `\`${m}\``).join(", ")}`);
+        if ((r.missing ?? []).length > 0) {
+          console.log(`    ${c.yellow("!")} #${r.n}  also cites evidence that does not resolve: ${(r.missing ?? []).map((m) => `\`${m}\``).join(", ")}`);
         }
         continue;
       }
@@ -165,9 +171,9 @@ export async function run(_positional, flags) {
       } else if (r.kind === "conditional") {
         console.log(`    ${c.yellow("!")} #${r.n}  evidence is a skipped test (proves nothing): ${r.skipped.map((m) => `\`${m}\``).join(", ")}`);
       } else if (r.kind === "unguarded") {
-        console.log(`    ${c.red("✗")} #${r.n}  orchestration claim is not fail-closed: ${r.reason}`);
+        console.log(`    ${c.red("✗")} #${r.n}  ${r.label ?? "orchestration claim is not fail-closed"}: ${r.reason}`);
       } else {
-        console.log(`    ${c.yellow("!")} #${r.n}  evidence not found on disk: ${r.missing.map((m) => `\`${m}\``).join(", ")}`);
+        console.log(`    ${c.yellow("!")} #${r.n}  evidence not found on disk: ${(r.missing ?? []).map((m) => `\`${m}\``).join(", ")}`);
       }
     }
   }
@@ -250,8 +256,49 @@ function runEvidence(projectRoot, reports, strict) {
 }
 
 
+const CANDIDATES_SHOWN = 5;
+
+function listProperties(projectRoot, only, json) {
+  const caps = propertyCandidates(projectRoot, { only });
+  const lib = projectPropertyLibrary(projectRoot);
+  if (json) {
+    emitJson("coverage", { properties: caps, library: lib });
+    return 0;
+  }
+  const total = caps.reduce((n, cap) => n + cap.candidates.length, 0);
+  const proven = caps.reduce((n, cap) => n + cap.properties, 0);
+  console.log(c.bold("Property candidates") + c.gray(" — requirements that claim something of every input"));
+  console.log("");
+  if (total === 0) {
+    console.log(c.gray("no requirement here reads as an invariant (always/never, at most, unique, round trip, twice, in order)"));
+    return 0;
+  }
+  for (const cap of caps) {
+    if (cap.candidates.length === 0) continue;
+    console.log(`${c.cyan(cap.cap)}  ${cap.candidates.length} requirement${cap.candidates.length === 1 ? "" : "s"} read${cap.candidates.length === 1 ? "s" : ""} as invariant${cap.candidates.length === 1 ? "" : "s"}, ` +
+      `${cap.properties} criteri${cap.properties === 1 ? "on is a property" : "a are properties"}`);
+    for (const cand of cap.candidates.slice(0, CANDIDATES_SHOWN)) {
+      const text = cand.text.length > 110 ? `${cand.text.slice(0, 107)}…` : cand.text;
+      console.log(`    ${cand.ref.padEnd(13)} ${text}`);
+      console.log(c.gray(`    ${"".padEnd(13)} ${cand.shape}: ${cand.property}`));
+    }
+    if (cap.candidates.length > CANDIDATES_SHOWN) {
+      console.log(c.gray(`    … and ${cap.candidates.length - CANDIDATES_SHOWN} more — doctrina coverage --properties --only ${cap.cap} --json`));
+    }
+  }
+  console.log("");
+  console.log(`${total} candidate${total === 1 ? "" : "s"}, ${proven} propert${proven === 1 ? "y" : "ies"} claimed. A candidate is a reading of the words, not a verdict: choose the ones whose failure would be a bug.`);
+  const where = lib
+    ? `${lib.name}${lib.declared ? "" : " (not declared by this project yet — add it as a test dependency)"}`
+    : "the property library of the project's language";
+  console.log(`Write each as a test that generates its inputs with ${where}, then claim it:`);
+  console.log(c.cyan("  doctrina change delta <id> <capability> --property \"<what holds for every input> — verified by \`<the property test>\`\""));
+  console.log(c.gray("A criterion marked [property] counts as proven only when the test it cites is property-based."));
+  return 0;
+}
+
 export const help = `
-Usage: doctrina coverage [--strict] [--only <cap,cap>] [--run] [--json]
+Usage: doctrina coverage [--strict] [--only <cap,cap>] [--run] [--properties] [--json]
 
 Report how many acceptance criteria across .doctrina/specs/ cite an
 artifact or test that exists on disk. Each numbered criterion may cite
@@ -277,6 +324,22 @@ That check must declare an "expect" guard (see \`doctrina verify --help\`).
 A cited check with no guard is reported UNGUARDED and fails --strict: a
 check that exits 0 having run nothing would otherwise satisfy the claim.
 
+PROPERTY criteria. A requirement that claims something of EVERY input —
+"never returns a code already in use", "at most 100 items", "decoding
+gives back what was encoded" — is not proven by three examples. Mark the
+criterion [property] and cite a property-based test:
+
+  4. [property] no two codes collide, whatever the URLs —
+     verified by \`tests/test_codes_property.py\`
+
+It counts as covered only when that test generates its inputs
+(Hypothesis @given, fast-check fc.property, jqwik @Property, proptest,
+rapid, FsCheck, ScalaCheck); cited to an example test it is reported and
+fails --strict. \`doctrina coverage --properties\` lists, per capability,
+the requirements whose words read as an invariant, the property each
+suggests and the library this project would write it with — a readout,
+never a gate.
+
 A spec that declares a deliberate deferral —
 \`Implementation: planned — <why>\`, the same escape hatch validate
 honours — has its unproven criteria reported as DEFERRED: visible, but

package/src/commands/doctor.js

@@ -19,6 +19,11 @@ import { OPERATIONS } from "../lib/commands.js";
 import { coverageLabel } from "../lib/views.js";
 import { workspaceFindings, workspaceRootAt, workspaceSnapshot } from "../lib/workspace-view.js";
 import { cdThen } from "../lib/shell.js";
+import { cliVersion } from "../lib/version.js";
+import { installsOnPath, runningPackageDir } from "../lib/install.js";
+import { missingAttributes, configuredDriver } from "../lib/merge-setup.js";
+import { isRepo } from "../lib/git.js";
+import { shadowRootOf } from "../lib/workspace.js";
 
 // How many never-invoked operations the usage row names before pointing at
 // `metrics --commands` for the rest. The spec states this number, so it is
@@ -276,9 +281,9 @@ export async function run(_positional, _flags) {
           " (run `doctrina verify` to execute)";
         if (stale > 0) {
           const parts = [];
-          if (so.expired) parts.push(`${so.expired} expired`);
-          if (so.unverifiable) parts.push(`${so.unverifiable} unverifiable`);
-          if (so.pending) parts.push(`${so.pending} unsigned`);
+          if (so?.expired) parts.push(`${so.expired} expired`);
+          if (so?.unverifiable) parts.push(`${so.unverifiable} unverifiable`);
+          if (so?.pending) parts.push(`${so.pending} unsigned`);
           row("warn", "verify config", `${detail} — ${parts.join(", ")}`,
             "doctrina verify   (each names the re-sign command)");
           warningsTotal += 1;
@@ -306,7 +311,7 @@ export async function run(_positional, _flags) {
       if (cfg.errors.length > 0) {
         row("fail", "config", cfg.errors[0], "fix .doctrina/config.json, then `doctrina validate`");
       } else if (cfg.unknown.length > 0) {
-        row("warn", "config", `${summary}; unknown key${cfg.unknown.length === 1 ? "" : "s"} ${cfg.unknown.map((k) => `"${k}"`).join(", ")} ignored`, "the keys are language, context_budget, rules");
+        row("warn", "config", `${summary}; unknown key${cfg.unknown.length === 1 ? "" : "s"} ${cfg.unknown.map((k) => `"${k}"`).join(", ")} ignored`, "the keys are language, context_budget, rules, surface");
         warningsTotal += 1;
       } else {
         row("ok", "config", summary);
@@ -316,6 +321,45 @@ export async function run(_positional, _flags) {
       }
     },
 
+    // 9b. The CLI that is running, and the one a bare `doctrina` finds.
+    cli: () => {
+      const version = cliVersion();
+      const installs = installsOnPath();
+      const first = installs[0];
+      const here = runningPackageDir();
+      const others = installs.filter((i) => !i.running);
+      const label = (/** @type {{ bin: string, version: string | null }} */ i) => `${i.bin} (${i.version ?? "version unknown"})`;
+      if (first && !first.running) {
+        row("warn", "cli", `${version} is running from ${here}, but \`doctrina\` on the PATH is ${label(first)} — the hooks and every bare \`doctrina\` run that one`,
+          `remove or update the other install (npm uninstall -g doctrina-cli under the Node that owns it), or put this one first on the PATH`);
+        warningsTotal += 1;
+      } else if (others.length > 0) {
+        row("warn", "cli", `${version} at ${first.bin}; ${others.length} more on the PATH: ${others.map(label).join(", ")}`,
+          "remove the copies you do not use — a shell whose PATH orders them differently runs another version");
+        warningsTotal += 1;
+      } else if (!first && callsDoctrinaByName(projectRoot)) {
+        row("warn", "cli", `${version} is running from ${here}, and no \`doctrina\` is on the PATH — this project's agent hooks call it by name`,
+          "npm install -g doctrina-cli   (or add its bin directory to the PATH)");
+        warningsTotal += 1;
+      } else {
+        row("ok", "cli", first ? `${version} at ${first.bin} — the only one on the PATH` : `${version}, run from ${here} (no \`doctrina\` on the PATH)`);
+      }
+    },
+
+    // 9c. Whether two branches that each close a change merge by themselves.
+    merges: () => {
+      if (!isRepo(projectRoot) || shadowRootOf(projectRoot) !== null) return;
+      const attributes = missingAttributes(projectRoot).length === 0;
+      const driver = configuredDriver(projectRoot) !== null;
+      if (attributes && driver) {
+        row("ok", "merges", "index.json and the ledger merge by themselves (driver and .gitattributes in place)");
+        return;
+      }
+      const missing = !attributes && !driver ? "nothing is set up" : !attributes ? ".gitattributes lacks the two lines" : "this clone has no merge driver";
+      row("warn", "merges", `${missing} — two branches that each close a change stop on index.json and the ledger`, "doctrina hooks install   (once per clone; commit .gitattributes)");
+      warningsTotal += 1;
+    },
+
     // 10. Which of the catalog's operations have never been reached for —
     //     but ONLY when the operator turned the log on. `lib/usage.js` was
     //     built to instrument the surface before shrinking it, and the only
@@ -377,6 +421,14 @@ export async function run(_positional, _flags) {
   return 0;
 }
 
+/** Does an agent hook in this project call `doctrina` by its bare name? */
+function callsDoctrinaByName(projectRoot) {
+  return [".cursor/hooks.json", ".claude/settings.json"].some((rel) => {
+    const file = path.join(projectRoot, rel);
+    return isFile(file) && /"(command)":\s*"doctrina /.test(read(file));
+  });
+}
+
 export const help = `
 Usage: doctrina doctor
 
@@ -391,6 +443,12 @@ exact remediation command.
            enums. Reports membership only; a rejected value is never
            printed, so this is safe to run and to paste.
 
+Two rows read the machine and the clone, not the artifacts: \`cli\` names
+the install that is running and any other \`doctrina\` the PATH holds — the
+agent hooks call it by name, so the first one found is the one they run —
+and \`merges\` says whether \`doctrina hooks install\` has set this clone up
+to merge index.json and the ledger without a manual step.
+
 A driver over the same collections the gates themselves render; it adds
 no checks of its own, so it can never disagree with the gates it fronts,
 and it runs entirely in this process — no subprocess, no re-parsing of

package/src/commands/hooks.js

@@ -11,6 +11,9 @@ import { flagBool } from "../lib/args.js";
 import { c } from "../lib/colors.js";
 import { suggest } from "../lib/suggest.js";
 import { EXIT } from "../lib/exit-codes.js";
+import { writeAttributes, configureDriver, configuredDriver } from "../lib/merge-setup.js";
+import { shadowRootOf } from "../lib/workspace.js";
+import { gitPathOf, repoPrefix } from "../lib/git.js";
 
 const SUBCOMMANDS = ["install"];
 
@@ -33,16 +36,49 @@ export async function run(positional, flags) {
   const force = flagBool(flags, "force", false);
   const projectRoot = process.cwd();
 
-  if (!exists(path.join(projectRoot, ".git"))) {
+  // Asked of git, not of `.git/` (seventh audit, change 0250). In a worktree
+  // and in a submodule `.git` is a file, so `mkdir .git/hooks` crashed with
+  // ENOTDIR after the attributes were already written; and a project in a
+  // subfolder of its repository has no `.git` beside it at all, so it was
+  // told to `git init` inside a repository — while `doctor` kept sending it
+  // back here.
+  const prefix = repoPrefix(projectRoot);
+  const hooksDir = prefix === null ? null : gitPathOf(projectRoot, "hooks");
+  if (prefix === null || hooksDir === null) {
     // A PRECONDITION, not a gate: nothing was measured and found wanting,
     // the place to put the hook simply does not exist yet. Class 1 told an
     // agent to fix its work and retry the same command, which never clears.
-    console.error(c.red("error:") + " not a git repository (no .git/ in cwd)");
+    console.error(c.red("error:") + " not a git repository — git does not answer for this folder");
     console.error(c.gray("hint: ") + "run `git init` here, then `doctrina hooks install`");
     return EXIT.PRECONDITION;
   }
 
-  const hooksDir = path.join(projectRoot, ".git", "hooks");
+  // The CLI that installed this, pinned by path (change 0116). `.git/` is
+  // local to the clone, so an absolute path is the right thing to write;
+  // a bare `doctrina` ran whichever release was on the PATH — a global
+  // 0.15.0 under a 0.15.1 tree rewrote the stamp backwards on every commit.
+  // `DOCTRINA=` in the environment overrides it for the hook.
+  const entry = path.resolve(here, "..", "index.js").replaceAll("\\", "/");
+  const bin = `node \"${entry}\"`;
+
+  // How the artifacts merge (change 0242). Before the hook, and whatever
+  // becomes of it: a pre-commit hook somebody else owns is no reason for
+  // two branches to stop on index.json. A shadowed repository keeps its
+  // `.doctrina/` out of its own git, so there is nothing of it to merge here.
+  if (shadowRootOf(projectRoot) === null) {
+    const added = writeAttributes(projectRoot);
+    if (added > 0) console.log(c.green("wrote") + ` .gitattributes — ${added} line${added === 1 ? "" : "s"}: index.json merges as data, the ledger as a list (commit it)`);
+    const before = configuredDriver(projectRoot);
+    const command = `node "${entry}"`;
+    if (before !== `${command} index merge %O %A %B`) {
+      if (configureDriver(projectRoot, command)) {
+        console.log(c.green("set") + "   the index merge driver in this clone's git config (every clone runs `doctrina hooks install` once)");
+      } else {
+        console.log(c.yellow("warn:") + " git refused the merge driver; two branches that close changes will stop on index.json — `doctrina index rebuild` resolves it");
+      }
+    }
+  }
+
   mkdirp(hooksDir);
 
   const target = path.join(hooksDir, "pre-commit");
@@ -53,13 +89,13 @@ export async function run(positional, flags) {
 
   const templatesDir = locateTemplatesDir();
   const tplPath = path.join(templatesDir, "hooks", "pre-commit.sample");
-  // The hook pins the CLI that installed it (change 0116). `.git/hooks/` is
-  // local to the clone, so an absolute path is the right thing to write;
-  // a bare `doctrina` ran whichever release was on the PATH — a global
-  // 0.15.0 under a 0.15.1 tree rewrote the stamp backwards on every commit.
-  // `DOCTRINA=` in the environment overrides it.
-  const entry = path.resolve(here, "..", "index.js").replaceAll("\\", "/");
-  const body = substitute(read(tplPath), { DOCTRINA_BIN: `node \"${entry}\"` });
+  let body = substitute(read(tplPath), { DOCTRINA_BIN: bin });
+  // git runs a hook from the top of the repository. A project that lives
+  // below it is entered first, or `validate` would answer for a folder that
+  // is not a Doctrina project.
+  if (prefix !== "") {
+    body = body.replace(/^DOCTRINA=/m, `# This Doctrina project lives below the repository root.\ncd "${prefix}" || exit 1\n\nDOCTRINA=`);
+  }
   write(target, body, { force: true });
   chmodSync(target, 0o755);
   console.log(c.green("installed") + ` ${relPath(projectRoot, target)}`);
@@ -72,7 +108,16 @@ export async function run(positional, flags) {
 export const help = `
 Usage: doctrina hooks install [--force]
 
-Install the Doctrina pre-commit hook into .git/hooks/pre-commit.
+Set the repository up for commits and merges:
+
+  - .gitattributes gains two lines (commit them): index.json merges through
+    \`doctrina index merge\`, as a list of artifacts, and the ledger through
+    git's own \`union\`, so two branches that each closed a change merge
+    without conflict markers in either file;
+  - this clone's git config gains the index merge driver, pinned to the CLI
+    that installed it — every clone runs \`doctrina hooks install\` once;
+  - .git/hooks/pre-commit gains the Doctrina hook.
+
 The hook runs \`doctrina validate --fix\`: it regenerates index.json
 from the tree (healing the most common gate failure — a hand-edited
 header that drifted the index — and re-staging the repaired index)