pi-gauntlet 5.10.2 → 5.12.0

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## v5.12.0 - 2026-09-19
+
+- New human-only `/skill:gauntlet-performance` and parse-only `gauntlet-performance` bin: the CLI digests committed telemetry records (current repo, plus `--dir <path>` repos; `--since <version>` narrows; `--json`) into per-run rows and per-version p50/max, and the skill turns the digest into one example-led recommendation, cornerstones, and a three-item menu (render on request, ticket via `shape-ticket`, drill-down). `gauntlet-telemetry-salvage` now stamps a record still `in_progress` with no ship phase as `status: shipped` + `shipped_at` at landing (`present`/`restored ... (marked shipped)`, `unfinished` under `--check`); `finishing-a-development-branch` and `gatekeep-pr` carry the new lines. The gh-37 record on this repo is backfilled to `shipped`. (#35)
+
+## v5.11.0 - 2026-09-18
+
+- `checkoutOf` falls back to `jj root` when `git rev-parse` fails, so `plan_check`, Guard 2, and telemetry resolve the checkout inside a plain (non-colocated) jj workspace; colocated jj repos still resolve through git first. The settings loader goes through the same resolution via a new sync `checkoutOfSync`, and telemetry records bound to a jj workspace carry a one-time `record written, not committed: not a git checkout` warning instead of a failed `git commit` per checkpoint. (#38)
+
 ## v5.10.2 - 2026-09-18
 
 - The telemetry record is a deliverable: brainstorming, `finishing-a-development-branch`, and `gatekeep-pr` name it beside the spec, and a new shipped `gauntlet-telemetry-salvage` bin restores a record that a plan strip or a fix commit deleted (from the deleting commit's parent, as one `telemetry: ` commit, exit 0 for valid invocations, never pushes). Finishing strips the plan on the feature branch before the Option 1 squash; gatekeep-pr checks at assessment, restores after each fix wave, and restores as the first step of a merge course. CI pins the bin, its test, its tarball imports, and the rule's presence in the three skills.

package/README.md

@@ -69,13 +69,13 @@ Everything between gate 1 and gate 2 - task breakdown, implementation, both revi
 
 pi-gauntlet ships three kinds of pieces, layered on top of pi-cohort's dispatch:
 
-- **18 skills** - the workflow logic. Thirteen activate automatically when pi sees the matching kind of task, and each one gates the next: `brainstorming`, `writing-plans`, `roasting-the-spec`, `test-driven-development`, `subagent-driven-development`, `dispatching-parallel-agents`, `verification-before-completion`, `requesting-code-review`, `receiving-code-review`, `using-git-worktrees`, `finishing-a-development-branch`, `writing-skills`, `linear` (reads/searches/comments on/manages Linear tickets via the `linearis` CLI; owns all linearis mechanics and the `## Issue tracker` overrides schema; tracker-facing skills route to it). Five more are explicit-invocation-only (`disable-model-invocation: true`): `shape-ticket` creates or repairs one tracker issue per run against a Context/Problem/Idea/Acceptance-Criteria template, gated by an AC integrity check, a cheap council roast, and a single human-confirmed write - run it with `/skill:shape-ticket`. `gatekeep-pr` is consent-gated pre-merge verification of a PR against its issue - read-only gathering, verification evidence resolved CI-first (green checks on the exact assessed head count as evidence; the project's verification command runs only as fallback), a rubric-based review, then a deterministic authorship-aware menu with stable finding IDs (P#/L#/C#/F#) and numbered pre-composed courses (fixes execute as a single parallel-safe wave: one gate run, one re-review, one push); nothing mutates (fixes, pushes, reviews, merges) until you pick a row - run it with `/skill:gatekeep-pr <pr>`. `check-delivery` is a post-merge detective control: proves an issue actually shipped (default-branch landing, delivery target, per-AC evidence) before its tracker status advances; it never writes a terminal status - run it with `/skill:check-delivery <ref>`. `chase-bug` is human-only bug triage: read-only root-cause discovery to an evidenced verdict menu (real bug -> ticket/brainstorm/hotfix/respond; five negative verdicts), then a gated response to the reporter for addressable origins (GitHub issue / tracker ticket) and a rendered verdict summary otherwise - it never fixes during triage; the hotfix row hands off to `skills/chase-bug/hotfix.md` after the menu - run it with `/skill:chase-bug`. `gauntlet-resume` is the only way back into an interrupted flow from a fresh session: it takes a pi-cohort `/handoff` brief (file or pasted) or a bare worktree that already holds a spec, restores phase/plan tracker state through the legal arming sequence (`start brainstorm`, `skip` with `resume:` reasons, `plan_check` before implement-or-later), never creates a worktree, and never infers approval from artifacts - run it with `/skill:gauntlet-resume [<brief>] [<worktree>]`.
+- **19 skills** - the workflow logic. Thirteen activate automatically when pi sees the matching kind of task, and each one gates the next: `brainstorming`, `writing-plans`, `roasting-the-spec`, `test-driven-development`, `subagent-driven-development`, `dispatching-parallel-agents`, `verification-before-completion`, `requesting-code-review`, `receiving-code-review`, `using-git-worktrees`, `finishing-a-development-branch`, `writing-skills`, `linear` (reads/searches/comments on/manages Linear tickets via the `linearis` CLI; owns all linearis mechanics and the `## Issue tracker` overrides schema; tracker-facing skills route to it). Six more are explicit-invocation-only (`disable-model-invocation: true`): `shape-ticket` creates or repairs one tracker issue per run against a Context/Problem/Idea/Acceptance-Criteria template, gated by an AC integrity check, a cheap council roast, and a single human-confirmed write - run it with `/skill:shape-ticket`. `gatekeep-pr` is consent-gated pre-merge verification of a PR against its issue - read-only gathering, verification evidence resolved CI-first (green checks on the exact assessed head count as evidence; the project's verification command runs only as fallback), a rubric-based review, then a deterministic authorship-aware menu with stable finding IDs (P#/L#/C#/F#) and numbered pre-composed courses (fixes execute as a single parallel-safe wave: one gate run, one re-review, one push); nothing mutates (fixes, pushes, reviews, merges) until you pick a row - run it with `/skill:gatekeep-pr <pr>`. `check-delivery` is a post-merge detective control: proves an issue actually shipped (default-branch landing, delivery target, per-AC evidence) before its tracker status advances; it never writes a terminal status - run it with `/skill:check-delivery <ref>`. `chase-bug` is human-only bug triage: read-only root-cause discovery to an evidenced verdict menu (real bug -> ticket/brainstorm/hotfix/respond; five negative verdicts), then a gated response to the reporter for addressable origins (GitHub issue / tracker ticket) and a rendered verdict summary otherwise - it never fixes during triage; the hotfix row hands off to `skills/chase-bug/hotfix.md` after the menu - run it with `/skill:chase-bug`. `gauntlet-performance` reads the committed run telemetry (current repo by default, `--dir <path>` adds others) through the parse-only `gauntlet-performance` CLI and answers with one example-led recommendation, 3-5 cornerstone numbers, and a menu of at most three actions (render a report file, open the recommendation as a ticket via `shape-ticket`, drill into one run); it writes nothing unless you pick render - run it with `/skill:gauntlet-performance [--dir <path>]... [--since <version>]`. `gauntlet-resume` is the only way back into an interrupted flow from a fresh session: it takes a pi-cohort `/handoff` brief (file or pasted) or a bare worktree that already holds a spec, restores phase/plan tracker state through the legal arming sequence (`start brainstorm`, `skip` with `resume:` reasons, `plan_check` before implement-or-later), never creates a worktree, and never infers approval from artifacts - run it with `/skill:gauntlet-resume [<brief>] [<worktree>]`.
 - **7 subagent personas** - the specialized child agents the skills dispatch via pi-cohort: `implementer`, `code-reviewer`, `spec-reviewer`, `conformance-reviewer`, `spec-summarizer`, `spec-council-member`, `spec-council-synthesizer`. See [doc/personas.md](./doc/personas.md) for what each one does and why its permissions are scoped the way they are.
-- **4 runtime extensions** - the enforcement layer. `plan-tracker` and `phase-tracker` are tools skills call to track progress (with a TUI widget); `verify-before-ship` is a hook that warns if you push or open a PR without a passing test run since your last edit; a phase-tracker flow guard reminds on implement-phase commits missing spec/code review. In a brainstorming-entered flow, phase-tracker rejects `implement` or `verify` completion while tracker tasks remain pending or in progress; see [its configuration reference](./doc/configuration.md#phase-tracker). phase-tracker also registers `plan_check`, which verifies a plan against its spec and against the grammar in [skills/writing-plans/reference/plan-contract.md](./skills/writing-plans/reference/plan-contract.md), including that each task's `Tests:` commands are selective and never the full suite; a pass stamps the plan for implementation. `telemetry` records one committed YAML record per gauntlet run (phase timing, models, personas, gate/fix rounds, diff at ship) that ships in the squash beside the spec - finishing and the PR gate restore a stripped record with `gauntlet-telemetry-salvage` - and blocks a brainstorm `write` into an already-shipped spec; see [its configuration reference](./doc/configuration.md#telemetry). See [doc/configuration.md](./doc/configuration.md) for the settings each one reads.
+- **4 runtime extensions** - the enforcement layer. `plan-tracker` and `phase-tracker` are tools skills call to track progress (with a TUI widget); `verify-before-ship` is a hook that warns if you push or open a PR without a passing test run since your last edit; a phase-tracker flow guard reminds on implement-phase commits missing spec/code review. In a brainstorming-entered flow, phase-tracker rejects `implement` or `verify` completion while tracker tasks remain pending or in progress; see [its configuration reference](./doc/configuration.md#phase-tracker). phase-tracker also registers `plan_check`, which verifies a plan against its spec and against the grammar in [skills/writing-plans/reference/plan-contract.md](./skills/writing-plans/reference/plan-contract.md), including that each task's `Tests:` commands are selective and never the full suite; a pass stamps the plan for implementation. `telemetry` records one committed YAML record per gauntlet run (phase timing, models, personas, gate/fix rounds, diff at ship) that ships in the squash beside the spec - finishing and the PR gate restore a stripped record, and stamp a record left `in_progress` with no ship phase as `shipped`, with `gauntlet-telemetry-salvage` - and blocks a brainstorm `write` into an already-shipped spec; see [its configuration reference](./doc/configuration.md#telemetry). See [doc/configuration.md](./doc/configuration.md) for the settings each one reads.
 
 pi-gauntlet is **opinionated**: every non-trivial change is *meant* to ride this one pipeline, entered through `brainstorming`. Enforcement is opt-in by entry, not ambient: once brainstorming starts a flow, the phase-tracker extension mechanically blocks a phase from closing before its gate runs, and warns once if the main loop writes code during implement (subagents own implement-phase edits). A change made *without* entering the flow (a typo, a formatting run, a dependency bump - see "When to use / when NOT to use") is not gated; the discipline of routing real work through the pipeline is a convention the tooling supports, not a trap it springs on every edit.
 
-**Worktree contract.** pi runs in the primary checkout; the work happens in `.worktrees/<branch>`. Skills never `cd` there - the worktree path is a value from the `using-git-worktrees` report (or the handoff brief on `gauntlet-resume`), carried as dispatch `cwd: "<path>"`, as `git -C <path>`, or as `(cd "<path>" && <cmd>)` for other cwd-bound commands; the runtime extensions derive the checkout from the artifact path they act on. Requires git >= 2.31.
+**Worktree contract.** pi runs in the primary checkout; the work happens in `.worktrees/<branch>`. Skills never `cd` there - the worktree path is a value from the `using-git-worktrees` report (or the handoff brief on `gauntlet-resume`), carried as dispatch `cwd: "<path>"`, as `git -C <path>`, or as `(cd "<path>" && <cmd>)` for other cwd-bound commands; the runtime extensions derive the checkout from the artifact path they act on. Requires git >= 2.31; a plain (non-colocated) jj workspace has no `.git`, so the resolver falls back to `jj root` there, reading primary-vs-workspace from `.jj/repo` (a directory in the primary checkout, a pointer file in added workspaces).
 
 ## Key concepts
 
@@ -122,6 +122,10 @@ Pin an exact release with `npm:pi-gauntlet@X.Y.Z`. See [doc/install-internals.md
 
 `gauntlet-spec-index` provides lexical search across `doc/specs/*.md` at the repository root and one service level down. From a repository worktree, run `node <pi-gauntlet-package>/bin/gauntlet-spec-index.mjs --query "<text>" [--limit N]`; it requires Node >=24.15.0, refreshes its FTS5 index on every query, and prints tab-separated `score`, `path`, `service`, `title`, `status`, `shipped_at`, `files`, and `snippet` columns. The per-worktree cache lives at `.pi/gauntlet/index.sqlite`, and its first creation adds `/.pi/gauntlet/index.sqlite*` to Git's `info/exclude` so the database and SQLite sidecars stay out of `git status`.
 
+## Performance digest
+
+`gauntlet-performance` digests telemetry records without judging them: `node <pi-gauntlet-package>/bin/gauntlet-performance.mjs [--dir <repo root or telemetry dir>]... [--since <version>] [--json]` prints a `corpus:` line, one row per run (`run_id`, repo, spec, version, status - `shipped*` when the record has no ship phase - wall, per-phase minutes, tokens, cost, models, dispatches, `fix_round_grants`, reopens, conformance loops, reviewer findings, council dispatches), a `by version` block of p50/max over shipped, non-truncated runs, and `skipped:` lines for files it could not use. Default corpus is the current repo's telemetry dir; each `--dir` adds a repo root (its own `telemetry.dir` setting is honoured) or a bare telemetry dir. `--since` compares versions numerically. Exit 0 always except usage errors. `/skill:gauntlet-performance` is the reasoning layer on top.
+
 For local development against a checkout instead of npm:
 
 ```bash

package/bin/gauntlet-performance.mjs

@@ -0,0 +1,283 @@
+#!/usr/bin/env node
+// Digest committed gauntlet telemetry records: one row per run plus p50/max per pi-gauntlet
+// version. Parse and aggregate only; the gauntlet-performance skill reasons over the output.
+import { existsSync, readdirSync, readFileSync, realpathSync, statSync } from "node:fs";
+import { homedir } from "node:os";
+import { basename, join, resolve } from "node:path";
+import { spawnSync } from "node:child_process";
+import process from "node:process";
+import { parse as parseYaml } from "yaml";
+import { mergeGauntlet, resolveTelemetry } from "../extensions/lib/gauntlet-settings.ts";
+
+const PHASES = ["brainstorm", "plan", "implement", "verify", "ship"];
+const TOKEN_KEYS = ["input", "output", "cache_read", "cache_write"];
+const RUN_HEADER = ["run_id", "repo", "spec", "version", "status", "wall", "b/p/i/v/s min", "tokens", "cost", "models", "disp", "grants", "reopens", "loops", "findings", "council"];
+const VERSION_HEADER = ["version", "n", "shipped", "truncated", "wall p50/max", "tokens p50/max", "cost p50/max", "disp p50", "grants p50/max", "reopens p50/max", "loops p50/max", "findings p50 b/M/m", "models"];
+
+const usage = () => {
+  process.stderr.write("usage: gauntlet-performance [--dir <repo root or telemetry dir>]... [--since <version>] [--json]\n");
+  process.exit(1);
+};
+
+const semver = (s) => {
+  const m = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$/.exec(typeof s === "string" ? s.trim() : "");
+  return m ? [Number(m[1]), Number(m[2]), Number(m[3])] : undefined;
+};
+const cmpSemver = (a, b) => a[0] - b[0] || a[1] - b[1] || a[2] - b[2];
+
+function parseArgs(argv) {
+  const opts = { dirs: [], since: undefined, json: false };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--dir" && argv[i + 1] !== undefined && !argv[i + 1].startsWith("--")) opts.dirs.push(argv[++i]);
+    else if (a === "--since" && argv[i + 1] !== undefined && !argv[i + 1].startsWith("--")) opts.since = argv[++i];
+    else if (a === "--json") opts.json = true;
+    else usage();
+  }
+  if (opts.since !== undefined && !semver(opts.since)) usage();
+  return opts;
+}
+
+function readLayer(file) {
+  if (!existsSync(file)) return {};
+  try {
+    return JSON.parse(readFileSync(file, "utf8"));
+  } catch (e) {
+    process.stderr.write(`warning: ${file}: ${e.message}; using {} for this layer\n`);
+    return {};
+  }
+}
+
+// Same two layers the recorder and salvage read.
+function telemetryDirOf(root) {
+  const agentDir = process.env.PI_CODING_AGENT_DIR || join(homedir(), ".pi", "agent");
+  const preset = readLayer(join(agentDir, "settings.json"));
+  const repo = readLayer(join(root, ".pi", "settings.json"));
+  const t = resolveTelemetry(mergeGauntlet(preset?.piGauntlet, repo?.piGauntlet));
+  if (t.warning) process.stderr.write(`warning: ${t.warning}\n`);
+  return join(root, t.dir);
+}
+
+const gitToplevel = (cwd) => {
+  const r = spawnSync("git", ["-C", cwd, "rev-parse", "--show-toplevel"], { encoding: "utf8", timeout: 10_000 });
+  return r.status === 0 ? r.stdout.trim() : undefined;
+};
+
+// A git toplevel contributes its resolved telemetry dir; anything else is a telemetry dir itself.
+function corpusFor(path) {
+  const label = basename(resolve(path));
+  if (!existsSync(path)) return { label, skip: "not found" };
+  const abs = realpathSync(path);
+  const top = gitToplevel(abs);
+  if (top !== undefined && realpathSync(top) === abs) {
+    const dir = telemetryDirOf(abs);
+    return existsSync(dir) ? { label, dir } : { label, skip: "no telemetry dir" };
+  }
+  if (!statSync(abs).isDirectory()) return { label, skip: "not a directory" };
+  return { label, dir: abs };
+}
+
+function* yamlFiles(dir) {
+  if (!existsSync(dir)) return;
+  for (const e of readdirSync(dir, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
+    const p = join(dir, e.name);
+    if (e.isDirectory()) yield* yamlFiles(p);
+    else if (e.isFile() && e.name.endsWith(".yaml")) yield p;
+  }
+}
+
+const num = (v) => (typeof v === "number" && Number.isFinite(v) ? v : null);
+const str = (v) => (typeof v === "string" ? v : null);
+const obj = (v) => (v && typeof v === "object" && !Array.isArray(v) ? v : null);
+const sumOrNull = (vals) => {
+  const xs = vals.filter((v) => v !== null);
+  return xs.length ? xs.reduce((a, b) => a + b, 0) : null;
+};
+
+function loadRecord(file, label) {
+  let doc;
+  try {
+    doc = parseYaml(readFileSync(file, "utf8"));
+  } catch {
+    return { skip: "unparseable" };
+  }
+  const d = obj(doc);
+  if (!d) return { skip: "unparseable" };
+  if (d.schema !== 1) return { skip: `schema ${d.schema === undefined ? "missing" : String(d.schema)}` };
+  if (typeof d.spec !== "string" || typeof d.run_id !== "string") return { skip: "not a record" };
+  const derived = obj(d.derived) ?? {};
+  const phases = obj(derived.phases) ?? {};
+  const ph = (p) => obj(phases[p]);
+  const tok = (p) => obj(ph(p)?.tokens);
+  const personas = obj(derived.personas) ?? {};
+  const reviews = obj(derived.reviews);
+  const gates = obj(derived.gates) ?? {};
+  const version = str(obj(d.versions)?.["pi-gauntlet"]);
+  const reviewEntries = reviews === null ? null : Object.values(reviews);
+  const findings = reviewEntries === null
+    ? null
+    : reviewEntries.length === 0
+      ? { blocker: 0, major: 0, minor: 0 }
+      : Object.fromEntries(["blocker", "major", "minor"].map((severity) => {
+        const counters = reviewEntries.map((r) => {
+          const review = obj(r);
+          if (review === null) return null;
+          if (!Object.hasOwn(review, "findings")) return 0;
+          const reviewFindings = obj(review.findings);
+          if (reviewFindings === null) return null;
+          return Object.hasOwn(reviewFindings, severity) ? num(reviewFindings[severity]) : 0;
+        });
+        return [severity, counters.includes(null) ? null : counters.reduce((a, b) => a + b, 0)];
+      }));
+  const truncated = ph("ship") === null;
+  return {
+    row: {
+      run_id: d.run_id,
+      repo: label,
+      spec: basename(file, ".yaml"),
+      version: semver(version) ? version.trim() : "unknown",
+      status: str(d.status),
+      created_at: str(d.created_at),
+      truncated,
+      wall_s: truncated ? null : num(derived.duration_s),
+      phase_min: Object.fromEntries(PHASES.map((p) => {
+        const s = num(ph(p)?.duration_s);
+        return [p, s === null ? null : s / 60];
+      })),
+      tokens: sumOrNull(PHASES.flatMap((p) => TOKEN_KEYS.map((k) => num(tok(p)?.[k])))),
+      cost: sumOrNull(PHASES.map((p) => num(tok(p)?.cost))),
+      models: [...new Set(PHASES.map((p) => str(ph(p)?.model)).filter((m) => m !== null))].sort(),
+      dispatches: sumOrNull(Object.values(personas).map((p) => num(obj(p)?.dispatches))),
+      grants: num(gates.fix_round_grants),
+      reopens: num(gates.task_reopens),
+      spec_rounds: num(gates.spec_rounds),
+      plan_rounds: num(gates.plan_rounds),
+      loops: num(derived.conformance_loops),
+      open_gaps: num(derived.conformance_open_gaps),
+      findings,
+      council: num(obj(personas["spec-council-member"])?.dispatches),
+      ship_option: str(gates.ship_option),
+      tests: str(obj(derived.tests)?.result),
+    },
+  };
+}
+
+const p50 = (xs) => {
+  const s = [...xs].sort((a, b) => a - b);
+  const m = s.length >> 1;
+  return s.length % 2 ? s[m] : (s[m - 1] + s[m]) / 2;
+};
+const stat = (rows, pick) => {
+  const xs = rows.map(pick).filter((v) => v !== null && v !== undefined);
+  return xs.length ? { p50: p50(xs), max: Math.max(...xs) } : { p50: null, max: null };
+};
+const versionOrder = (a, b) => {
+  const x = semver(a), y = semver(b);
+  return x && y ? cmpSemver(x, y) : x ? -1 : y ? 1 : 0;
+};
+
+function aggregate(rows) {
+  const groups = new Map();
+  for (const r of rows) {
+    if (!groups.has(r.version)) groups.set(r.version, []);
+    groups.get(r.version).push(r);
+  }
+  return [...groups.entries()].sort(([a], [b]) => versionOrder(a, b)).map(([version, all]) => {
+    const shipped = all.filter((r) => r.status === "shipped" && !r.truncated);
+    const models = {};
+    for (const r of shipped) for (const m of r.models) models[m] = (models[m] ?? 0) + 1;
+    return {
+      version,
+      n: all.length,
+      shipped: shipped.length,
+      truncated: all.filter((r) => r.truncated).length,
+      wall_s: stat(shipped, (r) => r.wall_s),
+      tokens: stat(shipped, (r) => r.tokens),
+      cost: stat(shipped, (r) => r.cost),
+      dispatches: { p50: stat(shipped, (r) => r.dispatches).p50 },
+      grants: stat(shipped, (r) => r.grants),
+      reopens: stat(shipped, (r) => r.reopens),
+      loops: stat(shipped, (r) => r.loops),
+      findings: {
+        blocker: { p50: stat(shipped, (r) => r.findings?.blocker ?? null).p50 },
+        major: { p50: stat(shipped, (r) => r.findings?.major ?? null).p50 },
+        minor: { p50: stat(shipped, (r) => r.findings?.minor ?? null).p50 },
+      },
+      models,
+    };
+  });
+}
+
+const dash = (v) => (v === null || v === undefined ? "-" : String(v));
+const fmtMin = (s) => (s === null ? "-" : `${Math.round(s / 60)}m`);
+const fmtCount = (n) => (n === null ? "-" : n >= 1e6 ? `${(n / 1e6).toFixed(1)}M` : n >= 1e3 ? `${(n / 1e3).toFixed(1)}k` : String(n));
+const fmtCost = (c) => (c === null ? "-" : c.toFixed(2));
+const pair = (s, f) => `${f(s.p50)}/${f(s.max)}`;
+const findingsCell = (f) => (f === null ? "-" : `${dash(f.blocker)}/${dash(f.major)}/${dash(f.minor)}`);
+const table = (header, rows) => {
+  const w = header.map((h, i) => Math.max(h.length, ...rows.map((r) => r[i].length)));
+  return [header, ...rows].map((r) => r.map((c, i) => c.padEnd(w[i])).join("  ").trimEnd()).join("\n");
+};
+const runRow = (r) => [
+  r.run_id.slice(0, 8), r.repo, r.spec, r.version, `${dash(r.status)}${r.truncated ? "*" : ""}`, fmtMin(r.wall_s),
+  PHASES.map((p) => (r.phase_min[p] === null ? "-" : String(Math.round(r.phase_min[p])))).join("/"),
+  fmtCount(r.tokens), fmtCost(r.cost), r.models.join(",") || "-", dash(r.dispatches), dash(r.grants), dash(r.reopens), dash(r.loops),
+  findingsCell(r.findings), dash(r.council),
+];
+const versionRow = (g) => [
+  g.version, String(g.n), String(g.shipped), String(g.truncated), pair(g.wall_s, fmtMin), pair(g.tokens, fmtCount), pair(g.cost, fmtCost),
+  dash(g.dispatches.p50), pair(g.grants, dash), pair(g.reopens, dash), pair(g.loops, dash),
+  `${dash(g.findings.blocker.p50)}/${dash(g.findings.major.p50)}/${dash(g.findings.minor.p50)}`,
+  Object.entries(g.models).map(([m, n]) => `${m}:${n}`).join(",") || "-",
+];
+
+function main() {
+  const opts = parseArgs(process.argv.slice(2));
+  const corpora = [];
+  const skipped = [];
+  const top = gitToplevel(process.cwd());
+  if (top === undefined) process.stderr.write(`not a git checkout: ${process.cwd()}\n`);
+  else corpora.push({ label: basename(top), dir: telemetryDirOf(top) });
+  for (const p of opts.dirs) {
+    const c = corpusFor(p);
+    if (c.skip) skipped.push({ file: p, reason: c.skip });
+    else corpora.push(c);
+  }
+  const since = opts.since === undefined ? undefined : semver(opts.since);
+  const seen = new Set();
+  const corpus = {};
+  const rows = [];
+  for (const c of corpora) {
+    corpus[c.label] = corpus[c.label] ?? 0;
+    for (const file of yamlFiles(c.dir)) {
+      const res = loadRecord(file, c.label);
+      if (res.skip) { skipped.push({ file, reason: res.skip }); continue; }
+      if (seen.has(res.row.run_id)) { skipped.push({ file, reason: "duplicate run_id" }); continue; }
+      seen.add(res.row.run_id);
+      const v = semver(res.row.version);
+      if (since && (!v || cmpSemver(v, since) < 0)) continue;
+      corpus[c.label]++;
+      rows.push(res.row);
+    }
+  }
+  rows.sort((a, b) => (a.created_at ?? "").localeCompare(b.created_at ?? "") || a.run_id.localeCompare(b.run_id));
+  const byVersion = rows.length ? aggregate(rows) : [];
+  if (opts.json) {
+    console.log(JSON.stringify({ corpus, since: opts.since ?? null, runs: rows, by_version: byVersion, skipped }, null, 2));
+    return;
+  }
+  console.log(`corpus: ${Object.entries(corpus).map(([k, v]) => `${k}=${v}`).join(", ")}${opts.since === undefined ? "" : `   since: ${opts.since}`}`);
+  if (rows.length === 0) {
+    console.log(`no records found in ${corpora.map((c) => c.dir).join(", ") || process.cwd()}`);
+  } else {
+    console.log(`runs (${rows.length})`);
+    console.log(table(RUN_HEADER, rows.map(runRow)));
+    console.log("");
+    console.log("by version");
+    console.log(table(VERSION_HEADER, byVersion.map(versionRow)));
+  }
+  if (rows.length && skipped.length) console.log("");
+  if (rows.length) for (const s of skipped) console.log(`skipped: ${s.file}: ${s.reason}`);
+}
+
+main();