doctrina-cli 0.15.1 → 0.17.0

package/src/commands/intake.js

@@ -2,12 +2,19 @@
 import path from "node:path";
 import process from "node:process";
 import { exists, isFile, read, relPath, write } from "../lib/fs-ops.js";
+import { ensureDoctrinaProject, projectName } from "../lib/project.js";
 import { listHeader } from "../lib/scan.js";
 import { assessBrief } from "../lib/clarity.js";
 import * as idx from "../lib/index-json.js";
 import { today } from "../lib/dates.js";
 import { flagBool, flagString } from "../lib/args.js";
 import { c } from "../lib/colors.js";
+import { looksLikePath, markIntakeConverted, printBootstrapPlaybook, warnIfThinIntake, writeIntakeFile } from "../lib/intake-model.js";
+
+// `init --intake` performs the same operations; they live in
+// lib/intake-model.js so neither command imports out of the other (F7).
+export { warnIfThinIntake, writeIntakeFile, printBootstrapPlaybook } from "../lib/intake-model.js";
+import { collectValidation } from "../lib/validation-model.js";
 import { EXIT, notADoctrinaProject } from "../lib/exit-codes.js";
 
 // `intake` is the first half of the no-ceremony path (ADR 0005): store the
@@ -19,10 +26,47 @@ import { EXIT, notADoctrinaProject } from "../lib/exit-codes.js";
 // 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", "force"], string: ["text"] };
+export const flags = { boolean: ["json", "force", "converted"], string: ["text"] };
 
 export async function run(positional, flags) {
   const projectRoot = process.cwd();
+
+  // Close the bootstrap through the CLI, not by hand.
+  //
+  // Step 7 of the playbook used to read "flip Status to converted in
+  // .doctrina/intake.md" — the one place this framework told an agent to
+  // hand-author a metadata header, against its own standing rule, and the one
+  // header nothing read back. A mistyped word left `next` asking forever for
+  // a bootstrap that was already done.
+  if (flagBool(flags, "converted", false)) {
+    ensureDoctrinaProject(projectRoot);
+    // Converting is the claim that the bootstrap is done — step 6 of the
+    // playbook, "fix everything the gates report", made checkable (change
+    // 0194). It used to convert over a tree `validate` failed, so the specs
+    // became "the source of truth" while an error still said they were not
+    // well-formed. --force converts anyway, for a tree whose errors are not
+    // the bootstrap's to fix.
+    if (isFile(path.join(projectRoot, ".doctrina", "intake.md")) && !flagBool(flags, "force", false)) {
+      const { errors } = collectValidation(projectRoot);
+      if (errors.length > 0) {
+        console.error(c.red("error:") + ` the bootstrap is not done — \`doctrina validate\` reports ${errors.length} error${errors.length === 1 ? "" : "s"}:`);
+        for (const e of errors.slice(0, 5)) console.error("  - " + e);
+        if (errors.length > 5) console.error(`  … and ${errors.length - 5} more`);
+        console.error(c.gray("hint: ") + "fix them (`doctrina validate --fix` heals index drift), then rerun; `--force` converts anyway");
+        return EXIT.GATE;
+      }
+    }
+    const written = markIntakeConverted(projectRoot);
+    if (!written) {
+      console.error(c.red("error:") + " no intake to mark converted at .doctrina/intake.md");
+      console.error(c.gray("hint: ") + 'store one first: `doctrina intake --text "<description>"`');
+      return EXIT.PRECONDITION;
+    }
+    console.log(c.green("converted") + ` ${relPath(projectRoot, written)} — specs are the source of truth now`);
+    console.log(c.gray("next: ") + 'doctrina next');
+    return EXIT.OK;
+  }
+
   if (!exists(path.join(projectRoot, ".doctrina"))) {
     throw notADoctrinaProject();
   }
@@ -58,12 +102,24 @@ export async function run(positional, flags) {
     source = "inline (--text)";
   } else {
     const abs = path.resolve(projectRoot, sourceFile);
-    if (!isFile(abs)) {
+    if (isFile(abs)) {
+      body = read(abs);
+      source = relPath(projectRoot, abs);
+    } else if (looksLikePath(sourceFile)) {
       console.error(c.red("error:") + ` description file not found: ${sourceFile}`);
+      console.error(c.gray("hint: ") +
+        'to pass the description itself, use `doctrina intake --text "<description>"`');
       return 1;
+    } else {
+      // Prose, not a path (change 0071). The surface block says "store the
+      // intent", so passing the intent is what its wording invites; answering
+      // "description file not found:" and echoing the author's whole sentence
+      // back as a filename was the CLI blaming the reader for reading it.
+      body = sourceFile;
+      source = "inline";
+      console.error(c.gray("note:  ") +
+        'read as the description itself, not as a file — `--text "<description>"` says so explicitly');
     }
-    body = read(abs);
-    source = relPath(projectRoot, abs);
   }
   if (body.trim().length === 0) {
     console.error(c.red("error:") + " the description is empty");
@@ -74,9 +130,19 @@ export async function run(positional, flags) {
     console.error(c.red("error:") + ` ${relPath(projectRoot, intakePath)} already exists (pass --force to overwrite)`);
     return 1;
   }
+  // After conversion the specs are the only source of truth, and the intake
+  // is never edited to change requirements (change 0112). `--force` was the
+  // CLI-sanctioned way to do exactly that: it rewrote the file to `pending`
+  // and printed the bootstrap playbook as if the tree were empty. The door
+  // for new intent is `intent add`; for a change of behaviour, `work`.
+  if (exists(intakePath) && (listHeader(read(intakePath), "Status") ?? "pending").toLowerCase() === "converted") {
+    console.error(c.red("error:") + ` ${relPath(projectRoot, intakePath)} is already converted — the specs are the source of truth now, and --force does not reopen it`);
+    console.error(c.gray("hint: ") + "new product intent: `doctrina intent add \"<text>\"` · a change of behaviour: `doctrina work \"<prompt>\"`");
+    return EXIT.PRECONDITION;
+  }
 
-  const projectName = idx.load(projectRoot).project ?? path.basename(projectRoot);
-  writeIntakeFile(projectRoot, { body, source, projectName, date: today(), force });
+  const name = projectName(projectRoot);
+  writeIntakeFile(projectRoot, { body, source, projectName: name, date: today(), force });
   console.log(c.green("created") + ` ${relPath(projectRoot, intakePath)}`);
   console.log("");
   warnIfThinIntake(body);
@@ -84,95 +150,6 @@ export async function run(positional, flags) {
   return 0;
 }
 
-// Clarification gate (review Topic A). A description too thin to spec from is
-// the moment to ask the user, not to let the agent invent requirements. Prints
-// the specific gaps before the bootstrap playbook; advisory, never blocking —
-// the intake is still captured verbatim (the playbook step 6 resolves it).
-export function warnIfThinIntake(body) {
-  const assessment = assessBrief(body, { kind: "intake" });
-  if (!assessment.thin) return;
-  console.log(c.yellow("⚠ thin intake — clarify with the user before converting to specs:"));
-  for (const reason of assessment.reasons) console.log(`    - ${reason}`);
-  console.log("");
-}
-
-// Shared with `init --intake`. Writes the intake verbatim under a small
-// status header; the agent flips Status to converted at the end of the
-// playbook, which is how `next` knows the bootstrap is done.
-export function writeIntakeFile(projectRoot, { body, source, projectName, date, force = false }) {
-  const intakePath = path.join(projectRoot, ".doctrina", "intake.md");
-  const content = [
-    `# Intake — ${projectName}`,
-    "",
-    "- **Status:** pending",
-    `- **Date:** ${date}`,
-    `- **Source:** ${source}`,
-    "",
-    "<!-- Raw project intent, stored verbatim. The bootstrap playbook",
-    "     (doctrina intake) converts it into product.md and capability",
-    "     specs, then flips Status to converted. After conversion the",
-    "     specs are the only source of truth; never edit this file to",
-    "     change requirements. -->",
-    "",
-    "---",
-    "",
-    body.replace(/\r\n/g, "\n").replace(/\n*$/, "\n"),
-  ].join("\n");
-  write(intakePath, content, { force });
-  return intakePath;
-}
-
-// Exported so `init --intake` can print the same playbook inline instead
-// of bouncing the user to a second command.
-export function printBootstrapPlaybook(projectRoot) {
-  const hasSpecs = exists(path.join(projectRoot, ".doctrina", "specs"));
-  console.log(c.bold("Bootstrap playbook") + c.gray(" — agent-executed (ADR 0005); the CLI does no interpretation."));
-  console.log("");
-  console.log("Execute in order, in a single linear pass:");
-  console.log("");
-  console.log(`1. Read ${c.cyan(".doctrina/intake.md")} (raw intent) and ${c.cyan(".doctrina/product.md")}.`);
-  console.log("");
-  console.log("2. Fill every product.md section from the intake: Vision, Problem,");
-  console.log("   Target users, Scope (in/out), Non-goals, Success criteria, and the");
-  console.log("   Delivery order — name the ONE end-to-end walking skeleton to build");
-  console.log("   and verify before fanning out (depth before breadth).");
-  console.log("   One fact, one home — product.md holds vision, never requirements.");
-  console.log("");
-  console.log("3. Derive the capability list: kebab-case, one per area of behaviour");
-  console.log("   (e.g. auth, billing, reports). For each capability:");
-  console.log(`       ${c.cyan("doctrina spec new <capability>")}`);
-  console.log("   then replace the template placeholders in");
-  console.log("   .doctrina/specs/<capability>/spec.md with EARS requirements derived");
-  console.log("   from the intake (Ubiquitous / Event-driven / State-driven /");
-  console.log("   Unwanted-behavior / Optional). Keep the two axes honest — leave");
-  console.log("   Implementation: planned for what is not built yet; keep aspiration");
-  console.log("   under ## Maturity → Future, not in EARS; write concrete Acceptance");
-  console.log("   criteria, each [unverified] until a cited test proves it.");
-  console.log("");
-  console.log("4. If the project spans services/front-ends, own the seams between");
-  console.log("   them (port map, env, API/WS/event shapes) as a contract:");
-  console.log(`       ${c.cyan("doctrina contract new <name>")} → fill it → ${c.cyan("doctrina contract check")}`);
-  console.log("");
-  console.log("5. Record any architectural decision the intake forces (cite Evidence):");
-  console.log(`       ${c.cyan("doctrina decision new \"<title>\"")} → edit → ${c.cyan("doctrina decision accept <num>")}`);
-  console.log("");
-  console.log("6. Quality gates — fix everything they report before moving on:");
-  console.log(`       ${c.cyan("doctrina clarify --all")}`);
-  console.log(`       ${c.cyan("doctrina validate")}`);
-  console.log(`       ${c.cyan("doctrina coverage")}   (and ${c.cyan("doctrina verify --init")} to declare the build gate)`);
-  console.log("   If something in the intake is genuinely ambiguous, ask the user");
-  console.log("   before assuming.");
-  console.log("");
-  console.log("7. Mark the intake consumed: in .doctrina/intake.md flip");
-  console.log("   \"- **Status:** pending\" to \"- **Status:** converted\".");
-  console.log("");
-  console.log(`8. ${c.cyan("doctrina next")} — follow the recommendation. Implementation then`);
-  console.log(`   flows through ${c.cyan("doctrina work \"<brief prompt>\"")}, one change at a time.`);
-  if (!hasSpecs) {
-    console.log("");
-    console.log(c.yellow("warn:") + " .doctrina/specs/ is missing — re-run `doctrina init` first.");
-  }
-}
 
 export const help = `
 Usage: doctrina intake [<file>] [--text "<description>"] [--force]
@@ -189,11 +166,20 @@ Forms:
   doctrina intake --text "<text>"     Ingest an inline description
   doctrina intake                     Reprint the playbook for the
                                       existing pending intake
+  doctrina intake --converted         Close the bootstrap: flip the stored
+                                      intake's Status to converted
 
 Options:
   --text "<description>"   Inline description instead of a file
-  --force                  Overwrite an existing .doctrina/intake.md
-
-After conversion the agent flips the intake header to
-"- **Status:** converted"; specs become the only source of truth.
+  --force                  Overwrite an existing .doctrina/intake.md; with
+                           --converted, convert although validate fails
+  --converted              Mark the stored intake converted (ends the
+                           bootstrap; nothing else writes that header).
+                           Refuses (exit 1) while validate reports an error
+
+Close the bootstrap with \`doctrina intake --converted\` rather than editing
+the header by hand: \`next\` branches on that value, and \`validate\` reports a
+Status that is neither pending nor converted, because every other word read
+as pending in silence. After conversion the specs are the only source of
+truth.
 `;

package/src/commands/intent.js

@@ -2,6 +2,7 @@
 import path from "node:path";
 import process from "node:process";
 import { exists, isFile, read, relPath, write } from "../lib/fs-ops.js";
+import { intentKey } from "../lib/validation-model.js";
 import { c } from "../lib/colors.js";
 import { suggest } from "../lib/suggest.js";
 import { notADoctrinaProject } from "../lib/exit-codes.js";
@@ -102,9 +103,21 @@ function intentAdd(projectRoot, textArg) {
   let id = null;
   let text = textArg;
   const pinned = textArg.match(/^([A-Z]+)(\d+)\s*:\s*(.+)$/);
+  if (pinned) text = pinned[3].trim();
+
+  // The same intent twice is two anchors for one goal: realize either and the
+  // other stays "dropped", so `trace --strict` fails on a gap nobody can
+  // close. An agent re-running a playbook step is enough to do it. Compared
+  // folded, so case, accents and spacing do not slip a twin past.
+  const twin = anchors.find((a) => intentKey(a.text) === intentKey(text));
+  if (twin) {
+    console.error(c.red("error:") + ` [${twin.id}] already states this intent in product.md`);
+    console.error(c.gray("hint: ") + `realize [${twin.id}] with a spec's \`Realizes:\` header, or reword this one if it is a different goal`);
+    return 1;
+  }
+
   if (pinned) {
     id = pinned[1] + pinned[2];
-    text = pinned[3].trim();
     if (anchors.some((a) => a.id === id)) {
       console.error(c.red("error:") + ` anchor [${id}] already exists in product.md`);
       return 1;

package/src/commands/metrics.js

@@ -1,28 +1,26 @@
 // @ts-check
 import path from "node:path";
 import process from "node:process";
-import { spawnSync } from "node:child_process";
 import { readdirSync } from "node:fs";
 import { exists, isDir, isFile, read, relPath, write } from "../lib/fs-ops.js";
 import { today } from "../lib/dates.js";
 import { flagBool, flagString } from "../lib/args.js";
 import { c } from "../lib/colors.js";
 import { EXIT } from "../lib/exit-codes.js";
-import { GIT_STATE, historyState } from "../lib/git.js";
+import { GIT_STATE, historyState, git } from "../lib/git.js";
 import { notADoctrinaProject } from "../lib/exit-codes.js";
 import { USAGE_ENV, summarise } from "../lib/usage.js";
 import { OPERATIONS } from "../lib/commands.js";
+import { REEDIT_WINDOW_DAYS, sinceWindow, computeSnapshot, parseLog, readSeries, latestSnapshot, trend, round } from "../lib/metrics-model.js";
 
 // Local-only adoption metrics derived from 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.
 
-const REEDIT_WINDOW_DAYS = 21;
-
 // 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", "save", "commands"], string: ["since"] };
+export const flags = { boolean: ["json", "save", "commands", "trend"], string: ["since"] };
 
 export async function run(_positional, flags) {
   const projectRoot = process.cwd();
@@ -33,6 +31,20 @@ export async function run(_positional, flags) {
   // the command surface are actually reached for (M8). Separate report,
   // separate source, so it never dilutes the adoption metrics.
   if (flagBool(flags, "commands", false)) return commandUsage();
+  // --trend reads the SERIES of saved snapshots rather than git. The
+  // snapshots are a time series versioned in the repository, and for two
+  // releases the only thing that read them was a delta against the most
+  // recent one (audit finding F15) — a year of measurement answering one
+  // question. Reading the series is what makes the saving worth doing.
+  if (flagBool(flags, "trend", false)) return printTrend(projectRoot);
+  // The window is the invocation's: refused the same with or without history.
+  const sinceRaw = flagString(flags, "since", "90");
+  const since = sinceWindow(sinceRaw);
+  if (since === null) {
+    console.error(c.red("error:") + ` --since expects a day count, a date (YYYY-MM-DD) or "<n> <unit>s ago", got "${sinceRaw}"`);
+    console.error(c.gray("hint: ") + "examples: --since 30 · --since 2026-01-01 · --since \"3 months ago\"");
+    return EXIT.USAGE;
+  }
   const probe = git(projectRoot, ["rev-parse", "--is-inside-work-tree"]);
   // "No history yet" is a VALID state, not a failure — a brand-new project
   // is the most common state in which someone explores this command, and it
@@ -51,15 +63,13 @@ export async function run(_positional, flags) {
     return EXIT.OK;
   }
 
-  const sinceRaw = flagString(flags, "since", "90");
-  const since = /^\d+$/.test(sinceRaw) ? `${sinceRaw} days ago` : sinceRaw;
   const save = flagBool(flags, "save", false);
 
   const log = git(projectRoot, [
     "log", `--since=${since}`, "--date=unix",
     "--pretty=format:@@%H|%ct|%s", "--name-only",
   ]);
-  if (log.status !== 0) {
+  if (log.state !== GIT_STATE.OK) {
     console.error(c.red("error:") + ` git log failed: ${log.stderr.trim()}`);
     return EXIT.ENVIRONMENT;
   }
@@ -78,7 +88,7 @@ export async function run(_positional, flags) {
   if (save) {
     const dir = path.join(projectRoot, ".doctrina", "metrics");
     const file = path.join(dir, `${today()}.json`);
-    const previous = latestSnapshot(dir, path.basename(file));
+    const previous = latestSnapshot(projectRoot, path.basename(file));
     write(file, JSON.stringify(snapshot, null, 2) + "\n", { force: true });
     console.log("");
     console.log(c.green("saved") + ` ${relPath(projectRoot, file)}`);
@@ -93,49 +103,45 @@ export async function run(_positional, flags) {
   return 0;
 }
 
-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);
+// The saved series, oldest first, with the direction each rate moved across
+// the whole span. No verdict attached: a revert rate moves with team size,
+// release cadence and how the window was drawn, and the CLI cannot tell an
+// improvement from a quieter quarter.
+function printTrend(projectRoot) {
+  const series = readSeries(projectRoot);
+  console.log(c.bold("Doctrina metrics") + c.gray(" — saved snapshots (.doctrina/metrics/)"));
+  console.log("");
+  if (series.length === 0) {
+    console.log(c.gray("no saved snapshots yet — `doctrina metrics --save` writes the first."));
+    return 0;
   }
-  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);
+  console.log(c.gray("date          commits  reverts  fix share  re-edit"));
+  for (const snap of series) {
+    console.log(
+      `${String(snap.generated).padEnd(12)}  ${String(snap.commits ?? "—").padStart(7)}  ` +
+      `${pct(snap.revert_rate).padStart(7)}  ${pct(snap.fix_share).padStart(9)}  ${pct(snap.reedit_rate).padStart(7)}`,
+    );
   }
-
-  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,
-  };
+  const t = trend(series);
+  if (t.rows.length === 0) {
+    console.log("");
+    console.log(c.gray(`one snapshot — a trend needs two. Save another with \`doctrina metrics --save\`.`));
+    return 0;
+  }
+  console.log("");
+  console.log(c.bold(`Across ${t.span} snapshots (${t.from} → ${t.to}):`));
+  for (const row of t.rows) printDelta(LABELS[row.rate] ?? row.rate, row.first, row.last);
+  console.log("");
+  console.log(c.gray("A direction, not a verdict: these rates move with team size and cadence."));
+  return 0;
 }
 
+const LABELS = {
+  revert_rate: "revert rate",
+  fix_share: "fix share",
+  reedit_rate: `${REEDIT_WINDOW_DAYS}-day re-edit rate`,
+};
+
 function printReport(s) {
   console.log(`commits                ${s.commits}`);
   console.log(`reverts                ${s.reverts} (${pct(s.revert_rate)})`);
@@ -158,50 +164,16 @@ function printDelta(label, before, after) {
   console.log(`  ${label}: ${pct(before)} → ${pct(after)} (${arrow})`);
 }
 
-function latestSnapshot(dir, excludeBase) {
-  if (!isDir(dir)) return null;
-  const files = readdirSync(dir)
-    .filter((f) => /^\d{4}-\d{2}-\d{2}\.json$/.test(f) && f !== excludeBase)
-    .sort();
-  if (files.length === 0) return null;
-  try {
-    return JSON.parse(read(path.join(dir, files[files.length - 1])));
-  } catch {
-    return null;
-  }
-}
-
-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;
-}
-
-function git(cwd, args) {
-  return spawnSync("git", args, { cwd, encoding: "utf8" });
-}
-
-function round(x) {
-  return Math.round(x * 1000) / 1000;
-}
 
 function pct(x) {
+  if (typeof x !== "number") return "—";
   return `${(x * 100).toFixed(1)}%`;
 }
 
 // Which operations were actually invoked, from the opt-in usage log. The
-// surface is 36 commands and 59 operations; the audit's charge is that some
-// exist because they were easy to add rather than because anyone reaches for
-// them. This is the evidence for that argument — or against it. Zero samples
+// audit's charge is that some of the surface exists because it was easy to
+// add rather than because anyone reaches for it (how big that surface is,
+// lib/commands.js owns — a count copied into a comment only rots). This is the evidence for that argument — or against it. Zero samples
 // is a CANDIDATE for cutting, never a verdict: a command used once a quarter
 // and a command nobody wants look identical over one week.
 function commandUsage() {
@@ -252,10 +224,15 @@ Flags:
                      opt-in usage log. Recording is OFF unless DOCTRINA_USAGE_LOG
                      names a file; only the operation is recorded, never
                      arguments, and nothing leaves the machine.
-  --since <n|date>   Window: a day count (default 90) or any git-parseable
-                     date ("2026-01-01", "3 months ago").
+  --since <n|date>   Window: a day count (default 90), a calendar date
+                     ("2026-01-01") or "<n> <unit>s ago" ("3 months ago").
+                     Anything else is refused: git reads any text as a
+                     date, so a typo would measure the wrong window.
   --save             Write .doctrina/metrics/YYYY-MM-DD.json and print the
                      deltas against the most recent prior snapshot.
+  --trend            Read the saved snapshots instead of git: every snapshot
+                     in date order, and the direction each rate moved across
+                     the whole span (first to last, not last to previous).
 
 This is the tooling half of the empirical A/B protocol in
 docs/en/validation.md: snapshot before adopting Doctrina, snapshot each