doctrina-cli 0.15.1 → 0.16.0

package/src/lib/json-out.js

@@ -27,14 +27,99 @@ export function wantsJson(flags) {
   return flags?.get?.("json") === true;
 }
 
+// A deprecation notice belongs in the ENVELOPE, not only on the terminal
+// (change 0061). Change 0049 announced a superseded name on the real stderr,
+// before capture — right for a piped stdout, which stays exactly what it
+// was, but it meant the envelope's `stderr` array came back empty and the
+// machine reading only that never learned the name it invoked is on its way
+// out. Deprecation exists so consumers migrate, and this CLI's primary
+// consumer is an agent reading JSON.
+//
+// Set once by the entrypoint, before the command runs, so BOTH json paths
+// carry it: the captured envelope and a command that builds its own payload.
+/** @type {{ use: string, since: string, why: string } | null} */
+let deprecation = null;
+
+/** @param {{ use: string, since: string, why: string } | null} record */
+export function setDeprecation(record) {
+  deprecation = record;
+}
+
+// A command that builds its own payload calls `emitJson` BEFORE it returns —
+// in `coverage.js` the call sits one line above `return jsonClean ? 0 :
+// strict ? 1 : 0`. So the call site cannot know the exit code, and the
+// optimistic defaults answered for it: `coverage --strict` exited 1 while
+// its payload said `"ok": true, "exit_code": 0`, and `exit_code` was 0 in
+// every native payload the CLI has ever emitted (change 0086).
+//
+// The entrypoint is the one place that knows the code, which is why the
+// CAPTURED path (a command with no payload of its own) was always right: it
+// emits after the run, with the real code. The native path now works the
+// same way — `deferJson()` before the run holds the payload, `flushJson(code)`
+// after it writes the envelope with the verdict the process actually reports.
+/** @type {{ command: string, data: object, opts: object } | null} */
+let held = null;
+let deferring = false;
+
+/** Hold the next payload instead of writing it, until `flushJson`. */
+export function deferJson() {
+  deferring = true;
+  held = null;
+}
+
+/**
+ * Write the held payload with the exit code the command actually returned,
+ * and leave deferred mode. A no-op when the command emitted nothing.
+ */
+export function flushJson(code) {
+  deferring = false;
+  if (!held) return;
+  const { command, data } = held;
+  held = null;
+  writeEnvelope(command, data, { ok: code === EXIT.OK, exitCode: code });
+}
+
 // Print a structured payload. `command` is the invocation, `data` whatever
 // that command has to say.
-export function emitJson(command, data, { ok = true, exitCode = EXIT.OK } = {}) {
+/**
+ * @param {string} command The OPERATION, never the operation plus arguments.
+ * @param {Record<string, unknown>} data
+ * @param {{ ok?: boolean, exitCode?: number, args?: string[] }} [opts]
+ */
+export function emitJson(command, data, opts = {}) {
+  if (deferring) {
+    held = { command, data, opts };
+    return;
+  }
+  writeEnvelope(command, data, opts);
+}
+
+/**
+ * `EXIT` is frozen, so its members infer as literal types — without this the
+ * default `exitCode = EXIT.OK` narrows the parameter to `0`.
+ *
+ * @param {string} command
+ * @param {Record<string, unknown>} data
+ * @param {{ ok?: boolean, exitCode?: number, args?: string[] }} [opts]
+ */
+function writeEnvelope(command, data, { ok = true, exitCode = EXIT.OK, args } = {}) {
   process.stdout.write(JSON.stringify({
     $schema_version: JSON_SCHEMA_VERSION,
+    // The OPERATION, never the operation plus its arguments. `command` used
+    // to carry `"why carteira"`, so the field a consumer branches on took a
+    // different value for every capability — while `next --json` documents
+    // `command`/`args` as the contract (third audit, finding 6). A
+    // sub-operation like `spec list` IS the operation and stays whole; the
+    // catalog is what tells the two apart.
     command,
     ok,
     exit_code: exitCode,
+    // Present when the invocation carried arguments, so it stays
+    // reconstructible without parsing the name.
+    ...(args && args.length > 0 ? { args } : {}),
+    // Present only when the invoked name is superseded, so a consumer can
+    // branch on its presence rather than on a string.
+    ...(deprecation ? { deprecated: deprecation } : {}),
     ...data,
   }, null, 2) + "\n");
 }
@@ -53,8 +138,14 @@ export async function captureOutput(fn) {
   // only console.* let that output escape the envelope and corrupt the
   // JSON on stdout, so the raw stream is captured too.
   const origWrite = process.stdout.write.bind(process.stdout);
+  // The raw stderr stream is captured too (change 0114): `verify` tees a
+  // child's stderr straight to process.stderr, so a failing check's
+  // diagnostics landed on the real stderr while the envelope said
+  // `"stderr": []`. Carriage returns are stripped — a child on Windows
+  // writes CRLF, and `"ok\r"` is not a line.
+  const origErrWrite = process.stderr.write.bind(process.stderr);
   const pushLines = (target, chunk) => {
-    for (const line of String(chunk).replace(/\n$/, "").split("\n")) target.push(line);
+    for (const line of String(chunk).replace(/\r?\n$/, "").split(/\r?\n/)) target.push(line.replace(/\r$/, ""));
   };
   console.log = (...args) => stdout.push(args.map(String).join(" "));
   console.error = (...args) => stderr.push(args.map(String).join(" "));
@@ -65,6 +156,12 @@ export async function captureOutput(fn) {
     if (cb) cb();
     return true;
   };
+  process.stderr.write = (chunk, ...rest) => {
+    pushLines(stderr, chunk);
+    const cb = rest.find((r) => typeof r === "function");
+    if (cb) cb();
+    return true;
+  };
   try {
     const code = await fn();
     return { code: code ?? EXIT.OK, stdout, stderr };
@@ -73,6 +170,7 @@ export async function captureOutput(fn) {
     console.error = origError;
     console.warn = origWarn;
     process.stdout.write = origWrite;
+    process.stderr.write = origErrWrite;
   }
 }
 

package/src/lib/ledger.js

@@ -0,0 +1,192 @@
+// @ts-check
+// The archive ledger, read as well as written.
+//
+// `.doctrina/changes/archive/LEDGER.md` is a structured log — date, change
+// id, title, and the capabilities the change touched with the operation it
+// performed on each — and for two releases exactly two things read it: an
+// id set in `decision scope`, and a cross-check in `validate`. Everything
+// else that wanted to know "what has been happening here" derived it from
+// git, which knows about files and nothing about capabilities (audit
+// findings F13, F14).
+//
+// The parse is DELIBERATELY tolerant. The file's own header invites humans
+// to edit it and promises the CLI only appends, so a line that does not
+// match the grammar is not a corrupt ledger — it is a person writing a note.
+// Such lines are counted, never thrown, and never rewritten.
+import path from "node:path";
+import { appendFileSync } from "node:fs";
+import { exists, isFile, mkdirp, read, write } from "./fs-ops.js";
+import { today } from "./dates.js";
+
+export const LEDGER_REL = ".doctrina/changes/archive/LEDGER.md";
+
+const HEADER =
+  "# 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";
+
+export function ledgerPath(projectRoot) {
+  return path.join(projectRoot, ...LEDGER_REL.split("/"));
+}
+
+// One entry per recognised line. `kind` separates the three things the CLI
+// records, because they mean different things to a reader: a change that
+// LANDED, one that was discarded, and a gate that was waved through.
+/**
+ * @typedef {{
+ *   date: string, id: string, kind: "archived"|"abandoned"|"gap",
+ *   title: string, specs: {capability: string, operation: string}[],
+ *   line: number, raw: string
+ * }} LedgerEntry
+ */
+
+// `- YYYY-MM-DD — <id> — <rest>`, with either an em dash or a hyphen as the
+// separator and any indentation (a gap line is indented). The date's month
+// and day are range-checked: a bullet a person typed by hand is far more
+// likely to be prose that happens to start with digits than an entry, and
+// admitting it would put a fictional date into a churn window.
+const LINE_RE = /^\s*-\s+(\d{4}-(?:0[1-9]|1[0-2])-(?:0[1-9]|[12]\d|3[01]))\s+[—-]\s+(\S+)\s+[—-]\s+(.*)$/;
+const SPECS_RE = /\(specs:\s*([^)]*)\)\s*$/;
+
+/**
+ * Parse ledger text into entries.
+ *
+ * @param {string} text
+ * @returns {{entries: LedgerEntry[], unparsed: number}}
+ */
+export function parseLedger(text) {
+  const entries = [];
+  let unparsed = 0;
+  const lines = String(text ?? "").split(/\r?\n/);
+  for (let i = 0; i < lines.length; i++) {
+    const raw = lines[i];
+    if (raw.trim() === "") continue;
+    const m = raw.match(LINE_RE);
+    if (!m) {
+      // Prose, the file's own header, a hand-written note: not an entry, and
+      // not an error either.
+      if (/^\s*-\s/.test(raw)) unparsed += 1;
+      continue;
+    }
+    const [, date, id, rest] = m;
+    const trimmed = rest.trim();
+    let kind = /** @type {"archived"|"abandoned"|"gap"} */ ("archived");
+    if (/^abandoned\b/i.test(trimmed)) kind = "abandoned";
+    else if (/^(?:forced|docs gap)\b/i.test(trimmed)) kind = "gap";
+
+    const specsMatch = trimmed.match(SPECS_RE);
+    const specs = specsMatch ? parseSpecs(specsMatch[1]) : [];
+    const title = specsMatch ? trimmed.slice(0, specsMatch.index).trim() : trimmed;
+    entries.push({ date, id, kind, title, specs, line: i + 1, raw });
+  }
+  return { entries, unparsed };
+}
+
+// "cli MODIFIED, gates MODIFIED" → [{capability, operation}]. An entry whose
+// operation is missing keeps the capability: the capability is the fact the
+// consumers need, and dropping the pair over a missing verb would lose it.
+function parseSpecs(list) {
+  const out = [];
+  for (const part of list.split(",")) {
+    const t = part.trim();
+    if (!t) continue;
+    const m = t.match(/^([a-z][a-z0-9-]*)(?:\s+([A-Z]+))?$/);
+    if (!m) continue;
+    out.push({ capability: m[1], operation: m[2] ?? "" });
+  }
+  return out;
+}
+
+/**
+ * Read and parse the project's ledger.
+ *
+ * @param {string} projectRoot
+ * @returns {{path: string, exists: boolean, entries: LedgerEntry[], unparsed: number}}
+ */
+export function readLedger(projectRoot) {
+  const p = ledgerPath(projectRoot);
+  if (!isFile(p)) return { path: p, exists: false, entries: [], unparsed: 0 };
+  const { entries, unparsed } = parseLedger(read(p));
+  return { path: p, exists: true, entries, unparsed };
+}
+
+/**
+ * How often each capability was touched, newest first by count.
+ *
+ * The number is reported, never judged: a spec that changes often may be
+ * badly drawn or may simply be where the work is, and the CLI has no way to
+ * tell those apart (ADR 0005). Only landed changes count — an abandoned
+ * change touched nothing, and a forced-gap line records a waived gate rather
+ * than a spec edit.
+ *
+ * @param {LedgerEntry[]} entries
+ * @param {{since?: string|null}} [options] since — ISO date, inclusive
+ * @returns {{capability: string, changes: number, last: string}[]}
+ */
+export function churnByCapability(entries, { since = null } = {}) {
+  const seen = new Map();
+  for (const e of entries) {
+    if (e.kind !== "archived") continue;
+    if (since && e.date < since) continue;
+    for (const s of e.specs) {
+      const row = seen.get(s.capability) ?? { capability: s.capability, changes: 0, last: "" };
+      row.changes += 1;
+      if (e.date > row.last) row.last = e.date;
+      seen.set(s.capability, row);
+    }
+  }
+  return [...seen.values()].sort((a, b) => b.changes - a.changes || a.capability.localeCompare(b.capability));
+}
+
+/**
+ * Append one line, creating the ledger when this is its first entry.
+ *
+ * The three things that write the ledger — archive, abandon, and a forced
+ * transition — used to carry their own copy of this header and their own
+ * append, so the format the parser above reads had three authors. 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 the ledger exists to break.
+ *
+ * @param {string} projectRoot
+ * @param {string} line  the entry, without the trailing newline
+ */
+export function appendLedgerLine(projectRoot, line) {
+  const p = ledgerPath(projectRoot);
+  if (!exists(p)) {
+    mkdirp(path.dirname(p));
+    write(p, HEADER);
+  }
+  appendFileSync(p, `${line}\n`);
+  return p;
+}
+
+/** The canonical line for an archived change. */
+export function archivedLine(id, title, specsAffected = [], date = today()) {
+  const specs = specsAffected.length > 0
+    ? ` (specs: ${specsAffected.map((s) => `${s.capability} ${s.operation}`).join(", ")})`
+    : "";
+  return `- ${date} — ${id} — ${title}${specs}`;
+}
+
+/** The canonical line for an abandoned change. */
+export function abandonedLine(id, reason = "", date = today()) {
+  return `- ${date} — ${id} — abandoned${reason ? ` — ${reason}` : ""}`;
+}
+
+/** The canonical line for a lifecycle gate that was waved through. */
+export function forcedLine(id, transition, blockers, date = today()) {
+  const summary = blockers.map((b) => `${b.gate}: ${b.message}`).join("; ");
+  return `  - ${date} — ${id} — forced ${transition} past ${blockers.length} ` +
+    `blocker${blockers.length === 1 ? "" : "s"} (${summary})`;
+}
+
+/**
+ * The canonical line for a docs gap closed with --force.
+ *
+ * It follows the entry grammar rather than being free prose, because a
+ * waived gate that no reader can find is the same as an unrecorded one.
+ */
+export function docsGapLine(id, signals, date = today()) {
+  return `  - ${date} — ${id} — docs gap: closed with --force; ${signals.join("; ")} documented nowhere`;
+}

package/src/lib/lexicon.js

@@ -0,0 +1,191 @@
+// @ts-check
+import { slugify } from "./dates.js";
+
+// ONE lexicon (audit findings F5/F6).
+//
+// `work` ranked a prompt against the spec tree with one stop list, and
+// `context --for` ranked the same prompt with a different one — while the
+// work playbook tells the agent to run `context` immediately after `work`.
+// Two rankers, in sequence, on the same text, free to disagree about which
+// capability it is about. And `FIX_SHAPED` appeared byte for byte in two
+// modules, so a term added to one classifier silently did not reach the
+// other.
+//
+// What follows is the whole vocabulary the CLI uses to read natural
+// language: how text is folded, what counts as a content word, and how
+// strongly a document answers a query. Every consumer reads it from here.
+//
+// It is deliberately small and deterministic. The CLI does no natural-
+// language interpretation (ADR 0005) — these functions rank, they never
+// decide, and the playbook says so at the point the ranking is shown.
+
+/**
+ * Fold to comparable ASCII-ish lowercase: strip combining marks so a
+ * Portuguese prompt and an ASCII spec match on the same word ("função" and
+ * "funcao"), and lowercase so case never decides relevance.
+ */
+export function fold(text) {
+  return String(text ?? "").normalize("NFD").replace(/\p{M}+/gu, "").toLowerCase();
+}
+
+/**
+ * The connective tissue of a task description, in English and Portuguese.
+ *
+ * Deliberately conservative: it covers grammar and the verbs every prompt
+ * uses ("add", "create", "implementar"), and nothing domain-specific — a
+ * stop list that swallowed a real term would quietly make retrieval worse
+ * in exactly the cases it is supposed to help.
+ */
+export const STOPWORDS = new Set([
+  // en — grammar
+  "a", "an", "and", "are", "as", "at", "be", "but", "by", "can", "do", "for",
+  "from", "has", "have", "how", "i", "if", "in", "into", "is", "it", "its",
+  "of", "on", "or", "should", "that", "the", "then", "this", "to", "up",
+  "was", "we", "what", "when", "where", "which", "why", "will", "with",
+  "shall", "must",
+  // en — the verbs and nouns every feature prompt carries
+  "make", "add", "new", "use", "create", "implement", "feature", "system",
+  "user", "users",
+  // pt (ASCII-folded) — grammar
+  "uma", "umas", "uns", "dos", "das", "nos", "nas", "por", "para", "com",
+  "que", "sem", "aos", "nao", "mais", "ser", "quando", "esta", "sao",
+  "pela", "pelo", "deve", "de", "do", "da", "no", "na", "em", "ao", "os",
+  "as", "um", "ou", "se", "eh", "pra",
+  // pt — the same verbs and nouns
+  "faca", "fazer", "criar", "crie", "novo", "nova", "adicionar", "adicione",
+  "implementar", "implemente", "funcionalidade", "sistema", "usuario",
+  "usuarios",
+]);
+
+/**
+ * The content words of a query: folded, de-duplicated, stop words dropped.
+ *
+ * A term must be at least two characters, so an initial or a stray letter
+ * never becomes a search term — but "id", "ci" and "pt" survive, and those
+ * are real terms in this domain.
+ */
+export function terms(query) {
+  if (query === undefined || query === null) return [];
+  const words = fold(query).match(/[a-z][a-z0-9-]+/g) ?? [];
+  return [...new Set(words.filter((w) => !STOPWORDS.has(w)))];
+}
+
+/**
+ * How strongly a document answers the query, as a comparable TUPLE rather
+ * than one blended number — so the tiebreak order is readable and no
+ * weighting constant has to be guessed:
+ *
+ *   [ terms in the title/id, terms in the body, hits per 1000 chars ]
+ *
+ * Density, not raw hit count, breaks the final tie. Raw hits reward a
+ * document for being long: the 473-line `cli` spec out-scored `skills` on
+ * the query "write a skill from git history" purely on volume, which is the
+ * length bias that makes naive retrieval useless on a mature tree.
+ */
+export function relevance(text, queryTerms, emphasis = "") {
+  if (queryTerms.length === 0) return [0, 0, 0];
+  const hay = fold(text);
+  const head = fold(emphasis);
+  let inTitle = 0;
+  let inBody = 0;
+  let hits = 0;
+  for (const term of queryTerms) {
+    const escaped = term.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    const boundary = `(^|[^a-z0-9-])${escaped}`;
+    const n = (hay.match(new RegExp(boundary, "g")) ?? []).length;
+    if (n > 0) {
+      inBody += 1;
+      hits += n;
+    }
+    if (head && new RegExp(boundary).test(head)) inTitle += 1;
+  }
+  const density = hay.length > 0 ? Math.round((hits / hay.length) * 1000) : 0;
+  return [inTitle, inBody, density];
+}
+
+/**
+ * The same relevance, projected onto ONE comparable number.
+ *
+ * `work` shows a score in a column and `context` orders by the tuple; both
+ * must agree about which capability a prompt is about, so the scalar is a
+ * PROJECTION of the tuple rather than a second calculation. The weights only
+ * have to preserve the tuple's own ordering — title beats body beats
+ * density — which is what the lexicographic comparison already says.
+ */
+export function score(text, queryTerms, emphasis = "") {
+  const [inTitle, inBody, density] = relevance(text, queryTerms, emphasis);
+  return inTitle * 100 + inBody * 10 + Math.min(density, 9);
+}
+
+/**
+ * A slug or identifier that reads as a FIX rather than a feature — the
+ * signal `skill suggest` and `next` both look for when deciding whether an
+ * archived change taught a lesson worth capturing.
+ *
+ * One definition: it lived byte for byte in two modules, so a term added to
+ * one classifier did not reach the other.
+ */
+export const FIX_SHAPED =
+  /(?:^|-)(fix|bug|hotfix|patch|parse|parsing|tolerate|workaround|race|deadlock|flaky|retry|escape|sanitize|sanitise)(?:-|$)/;
+
+/**
+ * The same idea applied to a commit subject. Narrower than FIX_SHAPED on
+ * purpose: a subject is prose, so it needs the conventional-commit shape or
+ * an explicit fix verb rather than a bare word match.
+ */
+export const FIX_SHAPED_SUBJECT =
+  /^(fix|bugfix|hotfix|patch)(\(|:|!)|^(revert)\b|\b(fixes|fixed|regression|workaround)\b/i;
+
+/**
+ * Which language a document is written in, by counting each lexicon's
+ * grammar words. Used by `clarify` to pick its smell lexicon when the
+ * project declares no language.
+ */
+const PT_GRAMMAR = /\b(que|n[aã]o|para|uma|como|mais|ser|quando|est[aá]|s[aã]o|pela|pelo|dos|das|ou seja|deve)\b/gi;
+const EN_GRAMMAR = /\b(the|and|that|with|shall|when|this|from|are|not|for|must)\b/gi;
+
+export function detectLanguage(text) {
+  const pt = (String(text).match(PT_GRAMMAR) ?? []).length;
+  const en = (String(text).match(EN_GRAMMAR) ?? []).length;
+  return pt > en ? "pt" : "en";
+}
+
+/**
+ * The margin a ranked winner must hold over the runner-up before a caller
+ * may ACT on the ranking rather than merely display it.
+ *
+ * `triage` calls a verdict confident when the winning lane beats the
+ * runner-up by 2. Copying that number here would copy a unit, not the
+ * notion: on `score()` above, every signal is worth 10 or 100 and the
+ * density tie-breaker alone moves the number by up to 9. A gap of 2 can
+ * therefore mean the two specs matched exactly the same terms and one of
+ * them is shorter — the opposite of confidence.
+ *
+ * 10 is the smallest gap density CANNOT produce: it is one whole body
+ * term. Density is capped at 9 precisely so it can only break ties, so a
+ * margin at or above 10 says the winner led on term overlap itself.
+ */
+export const CONFIDENT_MARGIN = 10;
+
+// The SLUG_WORDS content words of a prompt, slugified — the short half of a
+// change id (change 0070).
+//
+// The id used to be the whole prompt slugified, and the proposal's H1 is
+// `# Change <id> — <title>` with the title defaulting to that same prompt: so
+// a change opened on the default path said the same sentence twice, and every
+// read surface printed both halves. `prime` spent 133 characters of one line
+// on it — the command whose entire value is density.
+//
+// The id is what a person types and what sorts a backlog, so it wants to be
+// short; the title is what a person reads, so it wants to be whole. Capping
+// the SLUG rather than truncating the title gives both, and is exactly what
+// `--title` did by hand. Deterministic: a shipped stopword list, first N
+// content words, no interpretation (ADR 0005).
+export const SLUG_WORDS = 4;
+
+export function slugFromPrompt(prompt, { words = SLUG_WORDS } = {}) {
+  const content = terms(prompt).slice(0, words);
+  const slug = slugify(content.join(" "));
+  // A prompt of nothing but stopwords ("do it now") still needs an id.
+  return slug || slugify(prompt).split("-").slice(0, words).join("-");
+}

package/src/lib/metrics-model.js

@@ -0,0 +1,159 @@
+// @ts-check
+// The adoption metrics themselves: what a snapshot IS, computed once.
+//
+// `metrics` renders a snapshot and saves it; `report` shows two of its rates
+// for the reporting period. Before this they would each have had their own
+// idea of "revert rate", which is the kind of divergence nobody notices until
+// two numbers on two screens disagree and neither is wrong (ADR 0025).
+//
+// Everything here is derived from local git history. No network calls, no
+// telemetry: the numbers stay in the repository, versioned like any other
+// artifact. This is the tooling half of docs/en/validation.md.
+import path from "node:path";
+import { readdirSync } from "node:fs";
+import { isDir, isFile, read } from "./fs-ops.js";
+import { today } from "./dates.js";
+import { GIT_STATE, git } from "./git.js";
+
+export const REEDIT_WINDOW_DAYS = 21;
+export const METRICS_REL = ".doctrina/metrics";
+
+export function computeSnapshot(commits, since) {
+  const total = commits.length;
+  const reverts = commits.filter((cm) => /^Revert\b/.test(cm.subject)).length;
+  const fixes = commits.filter((cm) => /^fix[(:!]/.test(cm.subject)).length;
+
+  // File churn: commits per file, top offenders first.
+  const churn = new Map();
+  for (const cm of commits) {
+    for (const f of cm.files) churn.set(f, (churn.get(f) ?? 0) + 1);
+  }
+  const topChurn = [...churn.entries()]
+    .sort((a, b) => b[1] - a[1])
+    .slice(0, 5)
+    .map(([file, count]) => ({ file, commits: count }));
+
+  // Re-edit proxy: a commit counts when it touches a file another commit
+  // already touched in the previous REEDIT_WINDOW_DAYS. This is a proxy
+  // for rework, not a verdict — iterative work also trips it.
+  const windowSec = REEDIT_WINDOW_DAYS * 86400;
+  const lastTouch = new Map();
+  let reedits = 0;
+  for (const cm of [...commits].sort((a, b) => a.ts - b.ts)) {
+    const isReedit = cm.files.some((f) => {
+      const prev = lastTouch.get(f);
+      return prev !== undefined && cm.ts - prev <= windowSec;
+    });
+    if (isReedit) reedits += 1;
+    for (const f of cm.files) lastTouch.set(f, cm.ts);
+  }
+
+  return {
+    generated: today(),
+    window: since,
+    commits: total,
+    reverts,
+    revert_rate: round(reverts / total),
+    fix_share: round(fixes / total),
+    reedit_window_days: REEDIT_WINDOW_DAYS,
+    reedit_rate: round(reedits / total),
+    top_churn: topChurn,
+  };
+}
+
+
+export function parseLog(stdout) {
+  const commits = [];
+  let current = null;
+  for (const line of stdout.split("\n")) {
+    if (line.startsWith("@@")) {
+      const [hash, ts, ...rest] = line.slice(2).split("|");
+      current = { hash, ts: Number(ts), subject: rest.join("|"), files: [] };
+      commits.push(current);
+    } else if (line.trim() !== "" && current) {
+      current.files.push(line.trim());
+    }
+  }
+  return commits;
+}
+
+
+export function round(x) {
+  return Math.round(x * 1000) / 1000;
+}
+
+
+/**
+ * A snapshot for a window, or null when there is no history to read.
+ *
+ * @param {string} projectRoot
+ * @param {string} since  a git --since value ("90 days ago", "2026-01-01")
+ */
+export function collectMetrics(projectRoot, since) {
+  const log = git(projectRoot, [
+    "log", `--since=${since}`, "--date=unix",
+    "--pretty=format:@@%H|%ct|%s", "--name-only",
+  ]);
+  if (log.state !== GIT_STATE.OK) return null;
+  const commits = parseLog(log.stdout);
+  if (commits.length === 0) return null;
+  return computeSnapshot(commits, since);
+}
+
+/**
+ * Every saved snapshot, oldest first.
+ *
+ * The snapshots are a TIME SERIES, versioned in the repository — and for two
+ * releases the only thing that ever read them was a delta against the most
+ * recent one, so a year of measurement answered exactly one question: "is it
+ * better than last time?" (audit finding F15). Reading the series is what
+ * makes the saving worth doing.
+ */
+export function readSeries(projectRoot) {
+  const dir = path.join(projectRoot, ...METRICS_REL.split("/"));
+  if (!isDir(dir)) return [];
+  const out = [];
+  for (const f of readdirSync(dir).sort()) {
+    if (!/^\d{4}-\d{2}-\d{2}\.json$/.test(f)) continue;
+    const file = path.join(dir, f);
+    if (!isFile(file)) continue;
+    try {
+      const snap = JSON.parse(read(file));
+      // The filename is the authority on when it was taken: `generated` can
+      // be absent in a hand-edited file, and a series ordered by a field
+      // that may be missing is not ordered at all.
+      out.push({ ...snap, generated: snap.generated ?? f.replace(/\.json$/, "") });
+    } catch { /* a malformed snapshot is skipped, never fatal */ }
+  }
+  return out;
+}
+
+/** The most recent saved snapshot, excluding one basename. */
+export function latestSnapshot(projectRoot, excludeBase = null) {
+  const series = readSeries(projectRoot).filter((s) => `${s.generated}.json` !== excludeBase);
+  return series.length > 0 ? series[series.length - 1] : null;
+}
+
+/**
+ * The direction each tracked rate moved across the WHOLE series.
+ *
+ * First to last, not last to previous: a rate that drifted up for six months
+ * and dipped once looks like an improvement from the delta and like what it
+ * is from the series.
+ *
+ * @param {ReturnType<typeof readSeries>} series
+ */
+export function trend(series) {
+  const rates = ["revert_rate", "fix_share", "reedit_rate"];
+  if (series.length < 2) return { span: series.length, rows: [] };
+  const first = series[0];
+  const last = series[series.length - 1];
+  const rows = [];
+  for (const rate of rates) {
+    const a = first[rate];
+    const b = last[rate];
+    if (typeof a !== "number" || typeof b !== "number") continue;
+    rows.push({ rate, first: a, last: b, delta: round(b - a) });
+  }
+  return { span: series.length, from: first.generated, to: last.generated, rows };
+}