doctrina-cli 0.15.1 → 0.17.0

package/src/lib/gates.js

@@ -1,10 +1,11 @@
 // @ts-check
-import { getSection } from "./doc-model.js";
+import { checklistProgress, getSection } from "./doc-model.js";
 import path from "node:path";
 import { appendFileSync, writeFileSync } from "node:fs";
 import { exists, isFile, mkdirp, read } from "./fs-ops.js";
 import { today } from "./dates.js";
-import { collectAnalysis } from "../commands/analyze.js";
+import { collectAnalysis } from "./analysis.js";
+import { appendLedgerLine, forcedLine } from "./ledger.js";
 
 // The gate-to-transition map (audit item C6).
 //
@@ -23,10 +24,10 @@ import { collectAnalysis } from "../commands/analyze.js";
 // A gate is a named precondition returning human-readable blockers.
 export const GATES = {
   // Structural validity: the change's own files parse and point at real
-  // targets. The same checks `doctrina analyze` reports.
+  // targets. The same checks `doctrina change check` reports first.
   structure: {
     label: "structure",
-    rerun: (id) => `doctrina analyze ${id}`,
+    rerun: (id) => `doctrina change check ${id}`,
     blockers(projectRoot, changeDir) {
       return collectAnalysis(projectRoot, changeDir)
         .filter((r) => r.kind === "fail")
@@ -48,7 +49,7 @@ export const GATES = {
   // history recorded six hollow proposals reaching the archive.
   integrity: {
     label: "integrity",
-    rerun: (id) => `doctrina analyze ${id}`,
+    rerun: (id) => `doctrina change check ${id}`,
     blockers(projectRoot, changeDir) {
       return collectAnalysis(projectRoot, changeDir)
         .filter((r) => r.kind === "fail" && r.scope !== "pre-apply")
@@ -57,23 +58,26 @@ export const GATES = {
   },
 
   // Verification: the work is claimed complete. Every checkbox in
-  // tasks.md (closing steps included) and in the proposal's
-  // "## Verification" section.
+  // tasks.md and in the proposal's "## Verification" section — except a
+  // legacy "## Closing steps" list, which names what the close itself does
+  // (change 0195).
   verification: {
     label: "verification",
     rerun: (id) => `doctrina change tick ${id}`,
     blockers(projectRoot, changeDir) {
       const out = [];
-      const countUnchecked = (s) => (s.match(/^\s*-\s*\[ \]/gm) ?? []).length;
+      // Same counter as every other surface (change 0067).
+      const countUnchecked = (text, section = null) =>
+        checklistProgress(text, { section }).total - checklistProgress(text, { section }).done;
 
       const tasksPath = path.join(changeDir, "tasks.md");
       if (isFile(tasksPath)) {
         const n = countUnchecked(read(tasksPath));
-        if (n > 0) out.push(`${n} unchecked task${n === 1 ? "" : "s"} in tasks.md (closing steps count)`);
+        if (n > 0) out.push(`${n} unchecked task${n === 1 ? "" : "s"} in tasks.md`);
       }
       const proposalPath = path.join(changeDir, "proposal.md");
       if (isFile(proposalPath)) {
-        const n = countUnchecked(getSection(read(proposalPath), "Verification"));
+        const n = countUnchecked(read(proposalPath), "Verification");
         if (n > 0) out.push(`${n} unmet verification item${n === 1 ? "" : "s"} in proposal.md (## Verification)`);
       }
       return out;
@@ -105,6 +109,218 @@ export const TRANSITIONS = {
   archive: { label: "change archive", gates: ["integrity", "verification"] },
 };
 
+// ---------------------------------------------------------------------------
+// The gate SEQUENCES (audit finding F1)
+// ---------------------------------------------------------------------------
+//
+// ADR 0017 promised ONE gate map. TRANSITIONS above delivered it for the two
+// mutating transitions and stopped there: `close` carried a literal array of
+// ten steps, `doctor` eight hand-written rows, and `action.yml` five YAML
+// steps. Four lists, four owners, and nothing that noticed when they
+// diverged — which is how the runtime gate could land in `close` and stay
+// absent from CI (change 0033 had to add it to both by hand, and nothing
+// would have caught it if the second edit had been forgotten).
+//
+// So a sequence is DATA. Each step declares what it is, how hard it bites,
+// and the command that runs it standalone. The surfaces only RENDER it:
+// `close` executes it in order, `doctor` reports each as a row, and
+// `doctrina ci --emit github` writes it as CI YAML. None of them may invent
+// a step, drop one, or reorder — a drift test holds each surface to this
+// declaration, and the emitted YAML to the versioned `action.yml`.
+//
+// What this does NOT decide is which gates belong in a sequence; it declares
+// the sequences that exist so that the answer lives in one file.
+
+/**
+ * One step of a gate sequence.
+ *
+ * @typedef {object} GateStep
+ * @property {string} id        Stable key. The surfaces bind their renderer/runner to it.
+ * @property {string} label     What the surface calls the step.
+ * @property {"blocking"|"advisory"|"forceable"} level
+ *   blocking  — a non-zero result stops the sequence.
+ *   advisory  — reported, never stops anything.
+ *   forceable — blocking, unless --force, which records the gap in the ledger.
+ * @property {string[]|null} argv
+ *   The standalone CLI invocation this step is, or null when the step is not
+ *   one command (the ADR checkpoint, the docs gate). The token "<id>" is
+ *   replaced with the change id at render time.
+ * @property {string} [rerun]   Literal rerun line, for a step argv cannot describe.
+ * @property {string} [why]     One line of rationale. The CI emitter writes it as a comment.
+ * @property {boolean} [strict] CI only: the command takes --strict when the action runs strict.
+ * @property {string} [script]  CI only: a shell body that replaces the derived one-liner.
+ * @property {string} [flag]    Only run/report this step when that flag is set.
+ * @property {string} [short]   CI only: the name used in the action's own description.
+ * @property {string} [summary] CI only: the name plus what it checks, for the file header.
+ */
+
+/** @type {Record<string, GateStep[]>} */
+export const SEQUENCES = {
+  // The closing sequence. `close` runs these in order, in-process where it
+  // can, stopping at the first blocking failure with the step's rerun line.
+  close: [
+    // The structural pre-flight. Its id stays "analyze" (the module it runs
+    // in-process), but a reader sees "structure", the gate it holds: change
+    // 0182 deprecated `doctrina analyze`, and the command a person reruns is
+    // `change check`, which reports the same checks first (change 0183).
+    { id: "analyze", label: "structure", level: "blocking", argv: ["analyze", "<id>"], rerun: "doctrina change check <id>" },
+    { id: "adr-checkpoint", label: "ADR checkpoint (advisory)", level: "advisory", argv: ["decision", "list"] },
+    // Conformance review (audit finding F3). It is the richest analysis the
+    // project has — capabilities whose code moved while their spec did not,
+    // affected dependants, dangling coverage — and no driver invoked it, so
+    // it only ever happened when somebody typed the command.
+    //
+    // BEFORE the apply, deliberately: that is the point where its findings can
+    // still change what gets written. Advisory for now — it raises a break for
+    // every capability with touched code and a still spec, and that noise has
+    // to be measured before it is allowed to refuse. `review --strict` remains
+    // the door for a project that wants CI to block on it.
+    { id: "review", label: "review (advisory)", level: "advisory", argv: ["review"] },
+    { id: "apply", label: "apply", level: "blocking", argv: ["change", "apply", "<id>"] },
+    { id: "runtime", label: "runtime", level: "blocking", argv: ["contract", "check"] },
+    { id: "implementation", label: "implementation (advisory)", level: "advisory", argv: null, rerun: "doctrina spec set <cap> --implementation auto" },
+    { id: "verify", label: "verify", level: "blocking", argv: ["verify"] },
+    { id: "coverage", label: "coverage", level: "blocking", argv: ["coverage", "--strict"] },
+    { id: "trace", label: "trace", level: "advisory", argv: ["trace"] },
+    { id: "docs", label: "docs", level: "forceable", argv: null, rerun: "document the change, then rerun" },
+    { id: "archive", label: "archive", level: "blocking", argv: ["change", "archive", "<id>"] },
+    // AFTER the archive, because the archive is the last step that WRITES the
+    // index, and a gate placed before the step it guards cannot guard it.
+    //
+    // The drift check already ran, inside `verify` — and that is exactly why
+    // it missed: `verify` is five steps earlier, so it certified an index the
+    // archive had not yet rewritten. Change 0138 closed green on a tree whose
+    // index had drifted, the commit shipped, and all six test legs of CI went
+    // red on the next push. The close was not wrong about what it checked; it
+    // checked before the damage.
+    //
+    // `validate` cannot stand in for it: drift of that kind is only visible by
+    // rebuilding the index and comparing, which validate deliberately does not
+    // do.
+    { id: "index-drift", label: "index drift", level: "blocking", argv: ["index", "rebuild", "--check"] },
+    { id: "validate", label: "validate", level: "blocking", argv: ["validate"] },
+  ],
+
+  // The diagnostic sequence. Every row is advisory in the sense that `doctor`
+  // never mutates anything; the level says whether the row counts as a
+  // failing area (exit 1) or an advisory one (exit 0).
+  doctor: [
+    { id: "validate", label: "validate", level: "blocking", argv: ["validate"] },
+    { id: "index", label: "index", level: "blocking", argv: ["index", "rebuild", "--check"] },
+    { id: "coverage", label: "coverage", level: "advisory", argv: ["coverage"] },
+    { id: "trace", label: "trace", level: "advisory", argv: ["trace"] },
+    { id: "clean-checkout", label: "clean-checkout", level: "blocking", argv: ["verify", "--clean"] },
+    { id: "templates", label: "templates", level: "advisory", argv: ["upgrade"] },
+    { id: "runtime", label: "runtime", level: "blocking", argv: ["contract", "check"] },
+    { id: "local-env", label: "local .env", level: "blocking", argv: null, rerun: "doctrina doctor --env", flag: "env" },
+    { id: "verify-config", label: "verify config", level: "blocking", argv: ["verify", "--init"] },
+    // The declared size budgets, and the headroom left. Reported BEFORE either
+    // is breached: `agents-md-lines` is OUTPUT, so `analyze` refuses the
+    // raise-the-ceiling fix, and the generated surface block lives inside
+    // AGENTS.md — one command added spends a line of both (change 0072).
+    { id: "budgets", label: "budgets", level: "advisory", argv: null, rerun: "doctrina validate" },
+    // Not a check — a READOUT. Every other row can fail; this one exists
+    // because a project could not see what it had configured without reading
+    // 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" },
+    // 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
+    // the section (change 0050).
+    { id: "usage", label: "usage", level: "advisory", argv: null, rerun: "doctrina metrics --commands" },
+  ],
+
+  // The CI sequence, emitted as the composite action. Deliberately WITHOUT
+  // `verify`: the build gate is the adopting project's own to run, and the
+  // action exists to check the artifact tree.
+  ci: [
+    { id: "validate", label: "doctrina validate", level: "blocking", argv: ["validate"], short: "validate", summary: "validate (schema/structure)" },
+    { id: "index-drift", label: "doctrina index rebuild --check", level: "blocking", argv: ["index", "rebuild", "--check"], short: "index drift", summary: "index rebuild --check (index ↔ tree drift)" },
+    {
+      id: "contract-check",
+      label: "doctrina contract check",
+      level: "blocking",
+      argv: ["contract", "check"],
+      short: "contract check",
+      summary: "contract check (the declared runtime surface, RT01-RT05)",
+      why:
+        "The runtime gate (RT01-RT05). Every other step reads Markdown; this one\n" +
+        "reads what the Markdown CLAIMS about the running system and holds the\n" +
+        "implementation to it — the variable no workflow exports, the default an\n" +
+        "empty CI value never triggers, the unvalidated enum, the selector that\n" +
+        "matches nothing and still exits 0. Not gated on `strict`: a declaration\n" +
+        "that does not hold is an error at any adoption stage. A project with no\n" +
+        "contracts prints one line and exits 0.",
+    },
+    { id: "coverage", label: "doctrina coverage", level: "blocking", argv: ["coverage"], strict: true, short: "coverage", summary: "coverage (acceptance-criteria evidence)" },
+    { id: "trace", label: "doctrina trace", level: "blocking", argv: ["trace"], strict: true, short: "trace", summary: "trace (intent provenance)" },
+    {
+      id: "context-budget",
+      label: "doctrina context (budget)",
+      level: "blocking",
+      argv: ["context"],
+      short: "context budget",
+      summary: "context (the pack budget, ADR 0022)",
+      why:
+        "The context budget (ADR 0022). A pack that degrades to fit is fine; this\n" +
+        "fails only when a pack's irreducible core no longer fits at all, which\n" +
+        "means a spec has outgrown itself or a change has gone stale. Configure\n" +
+        "the ceiling per project with \"context_budget\": n in\n" +
+        ".doctrina/config.json.",
+      script:
+        "{{PREFIX}} context >/dev/null\n" +
+        "for cap in $(ls .doctrina/specs 2>/dev/null); do\n" +
+        "  {{PREFIX}} context \"$cap\" >/dev/null\n" +
+        "done",
+    },
+  ],
+};
+
+/** The declared steps of a sequence, or an error naming the ones that exist. */
+export function sequence(name) {
+  const steps = SEQUENCES[name];
+  if (!steps) throw new Error(`unknown gate sequence "${name}" (declared: ${Object.keys(SEQUENCES).join(", ")})`);
+  return steps;
+}
+
+/**
+ * The sequence as a reader sees it: each step's label, in order, with the
+ * forceable ones marked the way the advisory ones already are in their own
+ * labels.
+ *
+ * Every surface that SHOWS the sequence renders it from here. Four copies of
+ * the close sequence were written out by hand — `close --help`, two adapter
+ * command files, and the flow page in both languages — and all four had gone
+ * stale, each to a different list: one named four steps of thirteen, another
+ * eleven. A sequence a reader can count is a sequence a reader will trust, so
+ * it has exactly one author.
+ */
+export function sequenceLabels(name) {
+  // The marker comes from `level`, never from the label text: labels had
+  // already drifted among themselves — `trace` is advisory and did not say so
+  // while `ADR checkpoint` did — so any marker already written in is stripped
+  // and re-derived. One rule, applied to every step.
+  return sequence(name).map((s) => {
+    const base = s.label.replace(/\s*\((?:advisory|forceable)\)\s*$/, "");
+    if (s.level === "advisory") return `${base} (advisory)`;
+    if (s.level === "forceable") return `${base} (forceable)`;
+    return base;
+  });
+}
+
+/**
+ * The command that runs one step on its own — what a surface prints when it
+ * tells the operator how to clear the gate. Derived from `argv` so the
+ * declaration cannot disagree with itself; `rerun` covers the steps that are
+ * not a single command.
+ */
+export function stepRerun(step, changeId = "<id>") {
+  if (step.rerun) return step.rerun.replace(/<id>/g, changeId);
+  if (!step.argv) return `doctrina ${step.id}`;
+  return `doctrina ${step.argv.map((a) => (a === "<id>" ? changeId : a)).join(" ")}`;
+}
+
 // Evaluate a transition's gates. Returns { ok, blockers, gates } where
 // blockers is a flat list of human-readable reasons.
 export function checkTransition(projectRoot, changeDir, transition) {
@@ -123,25 +339,11 @@ export function checkTransition(projectRoot, changeDir, transition) {
 // waved through is part of the visible history rather than nothing at all
 // — the same posture `change archive --force` and `change abandon` take.
 export function recordForcedGap(projectRoot, id, transition, blockers) {
-  const archiveDir = path.join(projectRoot, ".doctrina", "changes", "archive");
-  const ledgerPath = path.join(archiveDir, "LEDGER.md");
-  // Create the ledger if this is the first entry. A forced transition can
-  // happen before any change has ever been archived, and a gap that goes
-  // unrecorded because the file did not exist yet is exactly the silence
-  // this is meant to break.
-  if (!exists(ledgerPath)) {
-    mkdirp(archiveDir);
-    writeFileSync(ledgerPath,
-      "# Change ledger\n\n" +
-      "One line per archived change, newest last. Appended by\n" +
-      "`doctrina change archive`; edit freely, the CLI only appends.\n\n");
-  }
-  const summary = blockers.map((b) => `${b.gate}: ${b.message}`).join("; ");
-  appendFileSync(
-    ledgerPath,
-    `  - ${today()} — ${id} — forced ${transition} past ${blockers.length} ` +
-    `blocker${blockers.length === 1 ? "" : "s"} (${summary})\n`,
-  );
+  // The ledger owns its own format and its own creation (lib/ledger.js): a
+  // forced transition can happen before any change has ever been archived,
+  // and a gap that goes unrecorded because the file did not exist yet is
+  // exactly the silence this is meant to break.
+  appendLedgerLine(projectRoot, forcedLine(id, transition, blockers));
   return true;
 }
 

package/src/lib/git.js

@@ -69,6 +69,23 @@ export function hasCommits(cwd) {
   return git(cwd, ["rev-parse", "--verify", "HEAD"]).state === GIT_STATE.OK;
 }
 
+/**
+ * Does this ref resolve to a commit in this repository?
+ *
+ * Asked directly, because the message heuristic above cannot answer it: git
+ * says "unknown revision or path not in the working tree" both for a
+ * repository with no commits and for a ref that does not exist, so a diff
+ * against a missing ref came back as GIT_STATE.EMPTY and every caller read
+ * it as "nothing changed". `doctrina review --diff main --strict` therefore
+ * passed on a shallow clone with no local `main` (change 0092).
+ *
+ * False when git is absent, this is not a repository, or the ref is unknown —
+ * callers that need to tell those apart ask `historyState` as well.
+ */
+export function refExists(cwd, ref) {
+  return git(cwd, ["rev-parse", "--verify", "--quiet", `${ref}^{commit}`]).state === GIT_STATE.OK;
+}
+
 // The state a command should report before trying to read history:
 // { usable, state, reason } where `reason` is a sentence fit to print.
 export function historyState(cwd) {
@@ -95,3 +112,118 @@ export function gitLines(cwd, args) {
 function splitLines(s) {
   return s.split(/\r?\n/).map((x) => x.trim()).filter(Boolean);
 }
+
+// ---------------------------------------------------------------------------
+// The period window the report view describes (change 0037)
+// ---------------------------------------------------------------------------
+//
+// `report` shelled out to git twice with its own spawnSync, which is the one
+// pattern this module exists to end: a caller that reads a non-zero exit as
+// "no commits" rather than "the command refused". Both probes go through
+// `git()` here, so an absent binary, a non-repository and a real failure stay
+// distinguishable — and the view above stays a pure formatter.
+
+/** The ISO date `days` ago — the left edge of a report window. */
+export function windowCutoff(days) {
+  return new Date(Date.now() - days * 24 * 60 * 60 * 1000).toISOString().slice(0, 10);
+}
+
+/**
+ * Commits, fix-shaped share and top-churn files in the window.
+ * Returns null when there is no history to read — outside a repository, with
+ * git absent, or before the first commit — so the caller can say so rather
+ * than print a confident zero.
+ */
+export function gitWindow(cwd, days) {
+  const since = `--since=${days} days ago`;
+  const log = git(cwd, ["log", since, "--pretty=%s"]);
+  if (log.state !== GIT_STATE.OK) return null;
+  const subjects = log.lines.filter((l) => l.trim().length > 0);
+  const fixes = subjects.filter((sub) => /^(fix|bug|hotfix|patch)(\(|:|!)/i.test(sub)).length;
+
+  const files = git(cwd, ["log", since, "--name-only", "--pretty=format:"]);
+  const counts = new Map();
+  if (files.state === GIT_STATE.OK) {
+    for (const line of files.lines) {
+      const f = line.trim();
+      if (!f) continue;
+      counts.set(f, (counts.get(f) ?? 0) + 1);
+    }
+  }
+  const churn = [...counts.entries()].sort((a, b) => b[1] - a[1]).slice(0, 5);
+  return { commits: subjects.length, fixes, churn };
+}
+
+// ---------------------------------------------------------------------------
+// Changed files: the one answer, four callers (audit finding F5)
+// ---------------------------------------------------------------------------
+//
+// `work`, `review`, `context` and `docs-impact` each carried their own
+// "which files changed" — four spawnSync helpers, four slightly different
+// answers, and each one reading a non-zero exit as an empty list rather than
+// a refusal. The semantics that genuinely differ between them are OPTIONS
+// here, not separate implementations: `docs-impact` needs the merge-base so a
+// branch's earlier commits count, `context --diff` compares against a named
+// ref, and a review against a ref does not want untracked files mixed in.
+
+/**
+ * The files that changed, as the caller defines "changed".
+ *
+ * @param {string} cwd
+ * @param {object} [opts]
+ * @param {string|null} [opts.since]      Compare against this ref instead of HEAD.
+ * @param {boolean} [opts.untracked]      Include untracked, non-ignored files (default true).
+ * @param {boolean} [opts.mergeBase]      Also include everything since the merge-base with the
+ *                                        default branch, so a branch's earlier commits count.
+ * @param {string[]} [opts.bases]         Which branch names to try as the merge-base target.
+ * @returns {{ ok: boolean, files: string[], state: string }}
+ *   `ok` is false when git could not answer — outside a repository, with git
+ *   absent, or on a real failure. A caller that treats "not ok" as "nothing
+ *   changed" is making the mistake this door exists to prevent, so the state
+ *   is returned rather than folded into an empty list.
+ */
+export function changedFiles(cwd, { since = null, untracked = true, mergeBase = false, bases = ["main", "master"] } = {}) {
+  const out = new Set();
+  const add = (r) => {
+    for (const line of r.lines) {
+      const p = line.trim();
+      if (p) out.add(p.replace(/\\/g, "/"));
+    }
+  };
+
+  const diff = git(cwd, since ? ["diff", "--name-only", since, "--"] : ["diff", "--name-only", "HEAD"]);
+  if (diff.state !== GIT_STATE.OK) return { ok: false, files: [], state: diff.state };
+  add(diff);
+
+  if (untracked) {
+    const others = git(cwd, ["ls-files", "--others", "--exclude-standard"]);
+    if (others.state === GIT_STATE.OK) add(others);
+  }
+
+  if (mergeBase) {
+    for (const base of bases) {
+      const mb = git(cwd, ["merge-base", "HEAD", base]);
+      if (mb.state === GIT_STATE.OK && mb.lines[0]) {
+        const since = git(cwd, ["diff", "--name-only", `${mb.lines[0].trim()}..HEAD`]);
+        if (since.state === GIT_STATE.OK) add(since);
+        break;
+      }
+    }
+  }
+
+  return { ok: true, files: [...out].sort(), state: GIT_STATE.OK };
+}
+
+/**
+ * The date of the most recent tag, as YYYY-MM-DD, or null.
+ *
+ * The left edge of "what has landed since the last release". Null when there
+ * is no tag, no history, or no repository — the caller then has to say which
+ * window it used rather than pretend there was one.
+ */
+export function lastTagDate(cwd) {
+  const tags = gitLines(cwd, ["for-each-ref", "--sort=-creatordate", "--count=1",
+    "--format=%(creatordate:short)", "refs/tags"]);
+  const date = tags[0] ?? "";
+  return /^\d{4}-\d{2}-\d{2}$/.test(date) ? date : null;
+}

package/src/lib/index-json.js

@@ -1,7 +1,7 @@
 // @ts-check
 import path from "node:path";
 import { read, write, exists } from "./fs-ops.js";
-import { cliVersion } from "./version.js";
+import { cliVersion, newestVersion } from "./version.js";
 
 export const SCHEMA_VERSION = "0.1.0";
 
@@ -39,7 +39,7 @@ export function save(projectRoot, index) {
   // records which CLI last wrote it, so a stale stamp (an index written by an
   // older CLI) is detectable by `doctrina validate` and migrated by
   // `doctrina index rebuild`.
-  index.framework_version = cliVersion();
+  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 });
@@ -64,10 +64,45 @@ export function blank(projectName, date) {
   };
 }
 
+// INSERT WHERE A REBUILD WOULD HAVE PUT IT.
+//
+// Every category here is written twice: incrementally, by the command that
+// creates the artifact, and wholesale by `index rebuild`, which walks the
+// directory — `readdirSync(...).sort()` — and writes what it finds, in that
+// order. The two agreed only by luck: appending matches a sorted walk exactly
+// when the new entry happens to sort last.
+//
+// It usually does, which is why this survived. `doctrina spec new alpha` after
+// `spec new zebra` does not, and neither does closing change 0138 after 0139 —
+// that one shipped, and turned all six test legs of CI red on a tree whose own
+// `close` had just reported green.
+//
+// `validate` cannot see it: drift of this kind is only visible by rebuilding
+// and comparing, which is `index rebuild --check`, a different gate. So the
+// tree looked healthy from inside and failed from outside.
+//
+// Each entry's `path` embeds the on-disk name the rebuild sorts by, and the
+// parent directory is constant within a category — so ordering by `path`
+// reproduces the walk exactly, without this module having to know how any
+// category is laid out.
+// The comparison has to be the SAME one: `readdirSync(dir).sort()` takes the
+// default comparator, which orders by UTF-16 code unit, and `localeCompare`
+// does not — it ignores or reweights punctuation, so `0100-a` and `0100_a`
+// can come out in the opposite order. Matching the walk means comparing the
+// way the walk compares.
+function insertInRebuildOrder(list, entry) {
+  list.push(entry);
+  list.sort((a, b) => {
+    const x = String(a.path ?? ""), y = String(b.path ?? "");
+    return x < y ? -1 : x > y ? 1 : 0;
+  });
+  return list;
+}
+
 export function addSkill(index, entry) {
   if (!index.artifacts.skills) index.artifacts.skills = [];
   if (!index.artifacts.skills.some((s) => s.id === entry.id)) {
-    index.artifacts.skills.push(entry);
+    insertInRebuildOrder(index.artifacts.skills, entry);
   }
   return index;
 }
@@ -75,17 +110,11 @@ export function addSkill(index, entry) {
 export function addContract(index, entry) {
   if (!index.artifacts.contracts) index.artifacts.contracts = [];
   if (!index.artifacts.contracts.some((s) => s.id === entry.id)) {
-    index.artifacts.contracts.push(entry);
+    insertInRebuildOrder(index.artifacts.contracts, entry);
   }
   return index;
 }
 
-export function removeSkill(index, id) {
-  if (!index.artifacts.skills) return index;
-  index.artifacts.skills = index.artifacts.skills.filter((s) => s.id !== id);
-  return index;
-}
-
 export function touch(index, date) {
   index.last_updated = date;
   return index;
@@ -93,19 +122,14 @@ export function touch(index, date) {
 
 export function addSpec(index, entry) {
   if (!index.artifacts.specs.some((s) => s.id === entry.id)) {
-    index.artifacts.specs.push(entry);
+    insertInRebuildOrder(index.artifacts.specs, entry);
   }
   return index;
 }
 
-export function removeSpec(index, id) {
-  index.artifacts.specs = index.artifacts.specs.filter((s) => s.id !== id);
-  return index;
-}
-
 export function addDecision(index, entry) {
   if (!index.artifacts.decisions.some((d) => d.id === entry.id)) {
-    index.artifacts.decisions.push(entry);
+    insertInRebuildOrder(index.artifacts.decisions, entry);
   }
   return index;
 }
@@ -117,17 +141,11 @@ export function updateDecision(index, id, mutator) {
   return index;
 }
 
-export function addChange(index, entry) {
-  if (!index.artifacts.changes.some((c) => c.id === entry.id)) {
-    index.artifacts.changes.push(entry);
-  }
-  return index;
-}
 
 export function moveChangeToArchive(index, id, archiveEntry) {
   index.artifacts.changes = index.artifacts.changes.filter((c) => c.id !== id);
   if (!index.artifacts.changes_archive.some((c) => c.id === id)) {
-    index.artifacts.changes_archive.push(archiveEntry);
+    insertInRebuildOrder(index.artifacts.changes_archive, archiveEntry);
   }
   return index;
 }