pi-gauntlet 5.11.0 → 5.12.0

package/CHANGELOG.md

@@ -1,5 +1,9 @@
 # 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)

package/README.md

@@ -69,9 +69,9 @@ 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.
 
@@ -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();

package/bin/gauntlet-performance.test.mjs

@@ -0,0 +1,350 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, mkdirSync, writeFileSync, rmSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { tmpdir } from "node:os";
+import { spawnSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+
+const CLI = join(dirname(fileURLToPath(import.meta.url)), "gauntlet-performance.mjs");
+const TDIR = ".pi/gauntlet/telemetry/doc/specs";
+const EMPTY_AGENT = mkdtempSync(join(tmpdir(), "gp-empty-agent-"));
+process.on("exit", () => rmSync(EMPTY_AGENT, { recursive: true, force: true }));
+
+const write = (root, rel, text) => {
+  mkdirSync(join(root, dirname(rel)), { recursive: true });
+  writeFileSync(join(root, rel), text);
+};
+const gitRepo = (prefix = "gp-") => {
+  const root = mkdtempSync(join(tmpdir(), prefix));
+  spawnSync("git", ["init", "-q"], { cwd: root });
+  return root;
+};
+const invoke = (cwd, args = [], env = {}) => {
+  const r = spawnSync(process.execPath, [CLI, ...args], {
+    cwd, encoding: "utf8", env: { ...process.env, PI_CODING_AGENT_DIR: EMPTY_AGENT, ...env },
+  });
+  return { status: r.status, stdout: r.stdout, stderr: r.stderr.trim(), lines: r.stdout.split("\n").filter(Boolean) };
+};
+const json = (cwd, args = []) => JSON.parse(invoke(cwd, ["--json", ...args]).stdout);
+const cleanup = (t, ...roots) => t.after(() => roots.forEach((r) => rmSync(r, { recursive: true, force: true })));
+
+const phase = (extra) => `{ started_at: 2026-09-01T00:00:00Z, completed_at: 2026-09-01T00:10:00Z, duration_s: 600, ${extra} }`;
+const tokens = (input, output, cacheRead, cacheWrite, cost) =>
+  `tokens: { input: ${input}, output: ${output}, cache_read: ${cacheRead}, cache_write: ${cacheWrite}, cost: ${cost} }`;
+
+// Complete run: cache-dominated tokens, an unphased block that must be ignored, two models.
+const COMPLETE = `schema: 1
+spec: doc/specs/a.md
+run_id: aaaaaaaa-0000-0000-0000-000000000001
+status: shipped
+created_at: 2026-09-01T00:00:00Z
+shipped_at: 2026-09-01T01:00:00Z
+versions: { pi-gauntlet: 5.9.1 }
+derived:
+  duration_s: 3600
+  phases:
+    brainstorm: ${phase(`model: m/alpha, ${tokens(100, 10, 5000, 200, 1.5)}`)}
+    plan: ${phase(`model: m/alpha, ${tokens(50, 5, 1000, 100, 0.5)}`)}
+    implement: ${phase(`model: m/beta, ${tokens(10, 1, 100, 10, 0.25)}`)}
+    verify: ${phase(`model: m/beta`)}
+    ship: ${phase(`model: m/beta`)}
+    unphased: { ${tokens(99999, 99999, 99999, 99999, 999)} }
+  personas:
+    worker: { dispatches: 3, models: [m/beta] }
+    spec-council-member: { dispatches: 4, models: [m/alpha] }
+  reviews:
+    spec-reviewer: { dispatches: 1, nonzero_exit: 0, findings: { blocker: 1, major: 2, minor: 3 } }
+    code-reviewer: { dispatches: 1, nonzero_exit: 0 }
+  conformance_loops: 2
+  conformance_open_gaps: 0
+  gates: { spec_rounds: 1, plan_rounds: 1, fix_round_grants: 1, task_reopens: 0, ship_option: squash }
+  tests: { command: npm test, result: pass }
+accumulators: {}
+events: []
+`;
+// Truncated run: stamped shipped by salvage, stale duration_s, no ship phase, zero gates.
+const TRUNCATED = `schema: 1
+spec: doc/specs/b.md
+run_id: bbbbbbbb-0000-0000-0000-000000000002
+status: shipped
+created_at: 2026-09-02T00:00:00Z
+shipped_at: 2026-09-02T02:00:00Z
+versions: { pi-gauntlet: 5.9.1 }
+derived:
+  duration_s: 2501
+  phases:
+    brainstorm: ${phase(`model: m/alpha, ${tokens(1, 1, 1, 1, 0.01)}`)}
+    plan: { started_at: 2026-09-02T00:10:00Z, model: m/alpha }
+  personas: {}
+  conformance_loops: 0
+  gates: { spec_rounds: 0, plan_rounds: 0, fix_round_grants: 0, task_reopens: 0 }
+accumulators: {}
+events: []
+`;
+const IN_PROGRESS = `schema: 1
+spec: doc/specs/c.md
+run_id: cccccccc-0000-0000-0000-000000000003
+status: in_progress
+created_at: 2026-09-03T00:00:00Z
+versions: { pi-gauntlet: 5.11.0 }
+derived:
+  duration_s: 10
+  phases: { brainstorm: { started_at: 2026-09-03T00:00:00Z } }
+  personas: {}
+  conformance_loops: 0
+  gates: { spec_rounds: 0, plan_rounds: 0, fix_round_grants: 0, task_reopens: 0 }
+accumulators: {}
+events: []
+`;
+// Second complete run on 5.9.1 with different numbers: makes p50 over an even count.
+const COMPLETE_2 = COMPLETE
+  .replace("run_id: aaaaaaaa-0000-0000-0000-000000000001", "run_id: dddddddd-0000-0000-0000-000000000004")
+  .replace("spec: doc/specs/a.md", "spec: doc/specs/d.md")
+  .replace("created_at: 2026-09-01T00:00:00Z", "created_at: 2026-09-04T00:00:00Z")
+  .replace("duration_s: 3600", "duration_s: 7200")
+  .replace("fix_round_grants: 1", "fix_round_grants: 3")
+  .replace(/reviews:[\s\S]*?conformance_loops/, "conformance_loops");
+const OLD_VERSION = COMPLETE
+  .replace("run_id: aaaaaaaa-0000-0000-0000-000000000001", "run_id: eeeeeeee-0000-0000-0000-000000000005")
+  .replace("spec: doc/specs/a.md", "spec: doc/specs/e.md")
+  .replace("pi-gauntlet: 5.9.1", "pi-gauntlet: 5.10.0");
+const BAD_GATES = IN_PROGRESS
+  .replace("run_id: cccccccc-0000-0000-0000-000000000003", "run_id: ffffffff-0000-0000-0000-000000000006")
+  .replace("spec: doc/specs/c.md", "spec: doc/specs/f.md")
+  .replace(/gates: \{[^}]*\}/, 'gates: "nope"');
+const EMPTY_REVIEWS = IN_PROGRESS
+  .replace("run_id: cccccccc-0000-0000-0000-000000000003", "run_id: gggggggg-0000-0000-0000-000000000007")
+  .replace("spec: doc/specs/c.md", "spec: doc/specs/g.md")
+  .replace("created_at: 2026-09-03T00:00:00Z", "created_at: 2026-09-05T00:00:00Z")
+  .replace("  conformance_loops: 0", "  reviews: {}\n  conformance_loops: 0");
+const REVIEW_WITHOUT_FINDINGS = IN_PROGRESS
+  .replace("run_id: cccccccc-0000-0000-0000-000000000003", "run_id: hhhhhhhh-0000-0000-0000-000000000008")
+  .replace("spec: doc/specs/c.md", "spec: doc/specs/h.md")
+  .replace("  conformance_loops: 0", "  reviews: { code-reviewer: { dispatches: 1, nonzero_exit: 0 } }\n  conformance_loops: 0");
+
+const corpus = (root) => {
+  write(root, `${TDIR}/a.yaml`, COMPLETE);
+  write(root, `${TDIR}/b.yaml`, TRUNCATED);
+  write(root, `${TDIR}/c.yaml`, IN_PROGRESS);
+  write(root, `${TDIR}/d.yaml`, COMPLETE_2);
+  write(root, `${TDIR}/e.yaml`, OLD_VERSION);
+  write(root, `${TDIR}/f.yaml`, BAD_GATES);
+  write(root, `${TDIR}/present-empty-reviews.yaml`, EMPTY_REVIEWS);
+  write(root, `${TDIR}/broken.yaml`, "schema: 1\nspec: [\n");
+  write(root, `${TDIR}/v2.yaml`, "schema: 2\nspec: doc/specs/z.md\nrun_id: z\n");
+  write(root, `${TDIR}/norec.yaml`, "schema: 1\nspec: doc/specs/z.md\n");
+  return root;
+};
+const byId = (runs, prefix) => runs.find((r) => r.run_id.startsWith(prefix));
+
+test("per-run fields: typed reads, unphased excluded, truncated wall null, findings null vs 0/0/0", (t) => {
+  const root = corpus(gitRepo()); cleanup(t, root);
+  const d = json(root);
+  assert.deepEqual(d.corpus, { [root.split("/").pop()]: 7 });
+  assert.equal(d.since, null);
+  const a = byId(d.runs, "aaaaaaaa");
+  assert.equal(a.repo, root.split("/").pop());
+  assert.equal(a.spec, "a");
+  assert.equal(a.version, "5.9.1");
+  assert.equal(a.status, "shipped");
+  assert.equal(a.truncated, false);
+  assert.equal(a.wall_s, 3600);
+  assert.deepEqual(a.phase_min, { brainstorm: 10, plan: 10, implement: 10, verify: 10, ship: 10 });
+  assert.equal(a.tokens, 100 + 10 + 5000 + 200 + 50 + 5 + 1000 + 100 + 10 + 1 + 100 + 10);
+  assert.equal(a.cost, 2.25);
+  assert.deepEqual(a.models, ["m/alpha", "m/beta"]);
+  assert.equal(a.dispatches, 7);
+  assert.equal(a.grants, 1);
+  assert.equal(a.reopens, 0);
+  assert.equal(a.spec_rounds, 1);
+  assert.equal(a.plan_rounds, 1);
+  assert.equal(a.loops, 2);
+  assert.equal(a.open_gaps, 0);
+  assert.deepEqual(a.findings, { blocker: 1, major: 2, minor: 3 });
+  assert.equal(a.council, 4);
+  assert.equal(a.ship_option, "squash");
+  assert.equal(a.tests, "pass");
+  const b = byId(d.runs, "bbbbbbbb");
+  assert.equal(b.truncated, true);
+  assert.equal(b.wall_s, null);
+  assert.deepEqual(b.phase_min, { brainstorm: 10, plan: null, implement: null, verify: null, ship: null });
+  assert.equal(b.tokens, 4);
+  assert.equal(b.dispatches, null);
+  assert.equal(b.findings, null);
+  assert.equal(b.council, null);
+  assert.equal(b.ship_option, null);
+  assert.equal(b.tests, null);
+  const dd = byId(d.runs, "dddddddd");
+  assert.equal(dd.findings, null);
+  const f = byId(d.runs, "ffffffff");
+  assert.equal(f.grants, null);
+  assert.equal(f.status, "in_progress");
+  const emptyReviews = byId(d.runs, "gggggggg");
+  assert.deepEqual(emptyReviews.findings, { blocker: 0, major: 0, minor: 0 });
+});
+
+test("review entries without findings contribute zero counters", (t) => {
+  const root = gitRepo(); cleanup(t, root);
+  write(root, `${TDIR}/review-without-findings.yaml`, REVIEW_WITHOUT_FINDINGS);
+  const d = json(root);
+  assert.deepEqual(d.runs[0].findings, { blocker: 0, major: 0, minor: 0 });
+});
+
+test("malformed findings counters remain null in JSON and render as dashes in text", (t) => {
+  const root = gitRepo(); cleanup(t, root);
+  const malformed = COMPLETE.replace(
+    "findings: { blocker: 1, major: 2, minor: 3 }",
+    'findings: { blocker: "bad", major: 2, minor: 3 }',
+  );
+  write(root, `${TDIR}/malformed-findings.yaml`, malformed);
+  const d = json(root);
+  assert.deepEqual(d.runs[0].findings, { blocker: null, major: 2, minor: 3 });
+  const row = invoke(root).lines.find((line) => line.startsWith("aaaaaaaa"));
+  assert.match(row, /\s-\/2\/3\s+4$/);
+});
+
+test("malformed reviewer entries and findings objects contribute null counters", (t) => {
+  const root = gitRepo(); cleanup(t, root);
+  const malformedFindings = COMPLETE.replace(
+    "findings: { blocker: 1, major: 2, minor: 3 }",
+    'findings: "bad"',
+  );
+  const malformedReviewer = COMPLETE.replace(
+    "spec-reviewer: { dispatches: 1, nonzero_exit: 0, findings: { blocker: 1, major: 2, minor: 3 } }",
+    'spec-reviewer: "bad"',
+  );
+  write(root, `${TDIR}/malformed-findings-object.yaml`, malformedFindings);
+  write(root, `${TDIR}/malformed-reviewer.yaml`, malformedReviewer.replace(
+    "run_id: aaaaaaaa-0000-0000-0000-000000000001",
+    "run_id: 22222222-0000-0000-0000-000000000012",
+  ));
+  const d = json(root);
+  assert.deepEqual(byId(d.runs, "aaaaaaaa").findings, { blocker: null, major: null, minor: null });
+  assert.deepEqual(byId(d.runs, "22222222").findings, { blocker: null, major: null, minor: null });
+});
+
+test("phase minutes remain unrounded in JSON", (t) => {
+  const root = gitRepo(); cleanup(t, root);
+  write(root, `${TDIR}/phase-61.yaml`, COMPLETE.replace("duration_s: 600", "duration_s: 61"));
+  const d = json(root);
+  assert.equal(d.runs[0].phase_min.brainstorm, 61 / 60);
+});
+
+test("aggregates: only shipped non-truncated rows feed p50/max; even-count p50 is the mean; models tally; unknown group", (t) => {
+  const root = corpus(gitRepo()); cleanup(t, root);
+  write(root, `${TDIR}/g.yaml`, COMPLETE.replace("run_id: aaaaaaaa-0000-0000-0000-000000000001", "run_id: 99999999-0000-0000-0000-000000000009").replace("versions: { pi-gauntlet: 5.9.1 }", "versions: {}"));
+  const d = json(root);
+  assert.deepEqual(d.by_version.map((g) => g.version), ["5.9.1", "5.10.0", "5.11.0", "unknown"]);
+  const v591 = d.by_version[0];
+  assert.equal(v591.n, 3);
+  assert.equal(v591.shipped, 2);
+  assert.equal(v591.truncated, 1);
+  assert.deepEqual(v591.wall_s, { p50: 5400, max: 7200 });
+  assert.deepEqual(v591.grants, { p50: 2, max: 3 });
+  assert.deepEqual(v591.dispatches, { p50: 7 });
+  assert.deepEqual(v591.findings, { blocker: { p50: 1 }, major: { p50: 2 }, minor: { p50: 3 } });
+  assert.deepEqual(v591.models, { "m/alpha": 2, "m/beta": 2 });
+  const v5110 = d.by_version[2];
+  assert.equal(v5110.n, 3);
+  assert.equal(v5110.shipped, 0);
+  assert.deepEqual(v5110.wall_s, { p50: null, max: null });
+  assert.deepEqual(v5110.models, {});
+  assert.equal(d.by_version[3].shipped, 1);
+});
+
+test("row order is created_at then run_id; skipped lists unparseable, schema, not a record", (t) => {
+  const root = corpus(gitRepo()); cleanup(t, root);
+  const d = json(root);
+  assert.deepEqual(d.runs.map((r) => r.run_id[0]), ["a", "e", "b", "c", "f", "d", "g"]);
+  const reasons = Object.fromEntries(d.skipped.map((s) => [s.file.split("/").pop(), s.reason]));
+  assert.equal(reasons["broken.yaml"], "unparseable");
+  assert.equal(reasons["v2.yaml"], "schema 2");
+  assert.equal(reasons["norec.yaml"], "not a record");
+});
+
+test("text output: header, shipped* marker, - cells, by version block, skipped lines", (t) => {
+  const root = corpus(gitRepo()); cleanup(t, root);
+  const r = invoke(root);
+  assert.equal(r.status, 0, r.stderr);
+  assert.equal(r.lines[0], `corpus: ${root.split("/").pop()}=7`);
+  assert.equal(r.lines[1], "runs (7)");
+  assert.match(r.lines[2], /^run_id\s+repo\s+spec\s+version\s+status\s+wall\s+b\/p\/i\/v\/s min\s+tokens\s+cost\s+models\s+disp\s+grants\s+reopens\s+loops\s+findings\s+council$/);
+  const bRow = r.lines.find((l) => l.startsWith("bbbbbbbb"));
+  assert.match(bRow, /\s5\.9\.1\s+shipped\*\s+-\s+10\/-\/-\/-\/-\s/);
+  assert.match(bRow, /\s-\s*$/);
+  const aRow = r.lines.find((l) => l.startsWith("aaaaaaaa"));
+  assert.match(aRow, /\sshipped\s+60m\s+10\/10\/10\/10\/10\s+6\.6k\s+2\.25\s+m\/alpha,m\/beta\s+7\s+1\s+0\s+2\s+1\/2\/3\s+4$/);
+  assert.ok(r.lines.includes("by version"));
+  const v = r.lines.find((l) => l.startsWith("5.9.1"));
+  assert.match(v, /^5\.9\.1\s+3\s+2\s+1\s+90m\/120m\s/);
+  assert.ok(r.lines.some((l) => /^skipped: .*broken\.yaml: unparseable$/.test(l)));
+});
+
+test("--since numeric compare: 5.10.0 > 5.9.1, unknown and malformed versions dropped; no rows -> no records found, exit 0", (t) => {
+  const root = corpus(gitRepo()); cleanup(t, root);
+  write(root, `${TDIR}/g.yaml`, COMPLETE.replace("run_id: aaaaaaaa-0000-0000-0000-000000000001", "run_id: 99999999-0000-0000-0000-000000000009").replace("versions: { pi-gauntlet: 5.9.1 }", "versions: {}"));
+  write(root, `${TDIR}/malformed-version.yaml`, COMPLETE.replace("run_id: aaaaaaaa-0000-0000-0000-000000000001", "run_id: 11111111-0000-0000-0000-000000000011").replace("pi-gauntlet: 5.9.1", "pi-gauntlet: 5.9.1garbage"));
+  write(root, `${TDIR}/leading-zero-version.yaml`, COMPLETE.replace("run_id: aaaaaaaa-0000-0000-0000-000000000001", "run_id: 33333333-0000-0000-0000-000000000013").replace("pi-gauntlet: 5.9.1", "pi-gauntlet: 5.09.1"));
+  assert.equal(byId(json(root).runs, "11111111").version, "unknown");
+  assert.equal(byId(json(root).runs, "33333333").version, "unknown");
+  const sinceFive = json(root, ["--since", "5.0.0"]);
+  assert.equal(byId(sinceFive.runs, "33333333"), undefined);
+  const d = json(root, ["--since", "5.10.0"]);
+  assert.equal(d.since, "5.10.0");
+  assert.deepEqual(d.runs.map((r) => r.version).sort(), ["5.10.0", "5.11.0", "5.11.0", "5.11.0"]);
+  const r = invoke(root, ["--since", "9.9.9"]);
+  assert.equal(r.status, 0);
+  assert.equal(r.lines[0], `corpus: ${root.split("/").pop()}=0   since: 9.9.9`);
+  assert.match(r.lines[1], /^no records found in .*\.pi\/gauntlet\/telemetry$/);
+  assert.equal(r.lines.length, 2);
+});
+
+test("--dir: repo root with telemetry dir, repo root without (skipped, checkout not walked), bare telemetry dir; duplicate run_id collapses", (t) => {
+  const root = corpus(gitRepo());
+  const other = gitRepo("gp-other-");
+  write(other, `${TDIR}/dup.yaml`, COMPLETE);
+  write(other, `${TDIR}/h.yaml`, COMPLETE.replace("run_id: aaaaaaaa-0000-0000-0000-000000000001", "run_id: 88888888-0000-0000-0000-000000000008"));
+  const empty = gitRepo("gp-empty-");
+  write(empty, "doc/specs/decoy.yaml", COMPLETE.replace("run_id: aaaaaaaa-0000-0000-0000-000000000001", "run_id: 77777777-0000-0000-0000-000000000007"));
+  const bare = mkdtempSync(join(tmpdir(), "gp-bare-"));
+  write(bare, "x.yaml", COMPLETE.replace("run_id: aaaaaaaa-0000-0000-0000-000000000001", "run_id: 66666666-0000-0000-0000-000000000006"));
+  cleanup(t, root, other, empty, bare);
+  const d = json(root, ["--dir", other, "--dir", empty, "--dir", bare, "--dir", join(bare, "missing")]);
+  assert.equal(d.corpus[other.split("/").pop()], 1);
+  assert.equal(d.corpus[bare.split("/").pop()], 1);
+  assert.equal(d.corpus[empty.split("/").pop()], undefined);
+  assert.ok(d.runs.some((r) => r.run_id.startsWith("88888888")));
+  assert.ok(d.runs.some((r) => r.run_id.startsWith("66666666")));
+  assert.ok(!d.runs.some((r) => r.run_id.startsWith("77777777")));
+  assert.equal(d.runs.filter((r) => r.run_id.startsWith("aaaaaaaa")).length, 1);
+  assert.ok(d.skipped.some((s) => s.file.endsWith("dup.yaml") && s.reason === "duplicate run_id"));
+  assert.ok(d.skipped.some((s) => s.file === empty && s.reason === "no telemetry dir"));
+  assert.ok(d.skipped.some((s) => s.file === join(bare, "missing") && s.reason === "not found"));
+});
+
+test("--dir skips an existing regular file as not a directory", (t) => {
+  const root = gitRepo();
+  const file = join(root, "telemetry.yaml");
+  writeFileSync(file, COMPLETE);
+  cleanup(t, root);
+  const r = invoke(root, ["--json", "--dir", file]);
+  assert.equal(r.status, 0, r.stderr);
+  const d = JSON.parse(r.stdout);
+  assert.ok(d.skipped.some((s) => s.file === file && s.reason === "not a directory"));
+});
+
+test("repo .pi/settings.json telemetry.dir is honoured for the default corpus", (t) => {
+  const root = gitRepo(); cleanup(t, root);
+  write(root, ".pi/settings.json", JSON.stringify({ piGauntlet: { telemetry: { dir: "custom/dir" } } }));
+  write(root, "custom/dir/doc/specs/a.yaml", COMPLETE);
+  const d = json(root);
+  assert.equal(d.runs.length, 1);
+});
+
+test("usage error exits 1", (t) => {
+  const root = gitRepo(); cleanup(t, root);
+  assert.equal(invoke(root, ["--bogus"]).status, 1);
+  assert.equal(invoke(root, ["--since", "abc"]).status, 1);
+  assert.equal(invoke(root, ["--since", "5.09.1"]).status, 1);
+});

package/bin/gauntlet-telemetry-salvage.mjs

@@ -1,9 +1,10 @@
 #!/usr/bin/env node
 // Restore a gauntlet telemetry record that a plan strip or a gate fix commit removed
 // from the branch. The recorder pathspec-commits the record at every checkpoint, so the
-// newest copy is always in the deleting commit's parent. Exit 0 on every outcome: the
-// callers are ship paths and this script never blocks one.
-import { existsSync, readFileSync, rmSync } from "node:fs";
+// newest copy is always in the deleting commit's parent. An in_progress record with no
+// ship phase is stamped shipped at landing. Exit 0 on every outcome: the callers are ship
+// paths and this script never blocks one.
+import { existsSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { isAbsolute, join } from "node:path";
 import { spawnSync } from "node:child_process";
@@ -11,6 +12,7 @@ import process from "node:process";
 import { mergeGauntlet, resolveTelemetry } from "../extensions/lib/gauntlet-settings.ts";
 import { isSpecPath, recordPathFor } from "../extensions/lib/telemetry-paths.ts";
 import { BASE_REFS } from "../extensions/lib/telemetry-ship.ts";
+import { parseRecord, serializeRecord } from "../extensions/lib/telemetry-record.ts";
 
 const GIT_TIMEOUT_MS = 10_000;
 const COMMIT_TIMEOUT_MS = Number(process.env.GAUNTLET_SALVAGE_COMMIT_TIMEOUT_MS) || 30_000;
@@ -67,10 +69,40 @@ function resolveBase(root, explicit) {
   return undefined;
 }
 
+// in_progress with no ship phase: the recorder lost its binding before the ship, so the
+// landing finishes the record instead of leaving it in_progress on main forever.
+const unfinished = (rec) => {
+  const phases = rec?.derived?.phases;
+  return rec?.status === "in_progress" && (phases === null || typeof phases !== "object" || !("ship" in phases));
+};
+const stamped = (rec, now) => serializeRecord({ ...rec, status: "shipped", shipped_at: now });
+
+function stampPresent(root, rec, check) {
+  const line = `present ${rec}`;
+  const abs = join(root, rec);
+  // Only a copy identical to HEAD in both worktree and index is script-owned.
+  if (!existsSync(abs) || !git(root, ["diff", "--quiet", "HEAD", "--", rec]).ok || !git(root, ["diff", "--quiet", "--cached", "HEAD", "--", rec]).ok) return line;
+  const parsed = parseRecord(readFileSync(abs, "utf8"));
+  if (!unfinished(parsed)) return line;
+  if (check) return `unfinished ${rec}`;
+  const prior = readFileSync(abs);
+  const failed = (reason) => {
+    writeFileSync(abs, prior);
+    git(root, ["reset", "-q", "--", rec]);
+    return `restore failed ${rec}: ${reason}`;
+  };
+  writeFileSync(abs, stamped(parsed, new Date().toISOString()));
+  const add = git(root, ["add", "-f", "--", rec]);
+  if (!add.ok) return failed(add.stderr);
+  const commit = git(root, ["commit", "-q", "-m", `telemetry: mark ${rec} shipped at landing`, "--", rec], COMMIT_TIMEOUT_MS);
+  if (!commit.ok) return failed(commit.stderr);
+  return `${line} (marked shipped)`;
+}
+
 function salvage(root, rec, base, check) {
   const presence = git(root, ["cat-file", "-e", `HEAD:${rec}`]);
   if (presence.timedOut) return `restore failed ${rec}: timed out`;
-  if (presence.ok) return `present ${rec}`;
+  if (presence.ok) return stampPresent(root, rec, check);
   const history = git(root, ["log", `${base}..HEAD`, "--grep=^telemetry: ", "-1", "--format=%H"]);
   if (history.timedOut) return `restore failed ${rec}: timed out`;
   if (!history.stdout) return `no telemetry run ${rec}`;
@@ -89,7 +121,12 @@ function salvage(root, rec, base, check) {
   }
   let created = false;
   let stagedByScript = false;
+  let priorBytes;
   const rollback = () => {
+    if (priorBytes !== undefined) {
+      writeFileSync(abs, priorBytes);
+      if (preStaged) git(root, ["add", "-f", "--", rec]);
+    }
     if (stagedByScript) git(root, ["reset", "-q", "--", rec]);
     if (created) rmSync(abs, { force: true });
   };
@@ -102,15 +139,20 @@ function salvage(root, rec, base, check) {
     const co = git(root, ["checkout", `${del}^`, "--", rec]);
     if (!co.ok) return `restore failed ${rec}: ${co.stderr}`;
     created = true;
-    stagedByScript = true;
-  } else if (!preStaged) {
-    const add = git(root, ["add", "-f", "--", rec]);
-    if (!add.ok) return failed(add.stderr);
-    stagedByScript = true;
   }
+  stagedByScript = !preStaged;
+  let suffix = "";
+  const parsed = parseRecord(readFileSync(abs, "utf8"));
+  if (unfinished(parsed)) {
+    priorBytes = readFileSync(abs);
+    writeFileSync(abs, stamped(parsed, new Date().toISOString()));
+    suffix = " (marked shipped)";
+  }
+  const add = git(root, ["add", "-f", "--", rec]);
+  if (!add.ok) return failed(add.stderr);
   const commit = git(root, ["commit", "-q", "-m", `telemetry: restore record stripped in ${del.slice(0, 10)}`, "--", rec], COMMIT_TIMEOUT_MS);
   if (!commit.ok) return failed(commit.stderr);
-  return `restored ${rec} from ${del}`;
+  return `restored ${rec} from ${del}${suffix}`;
 }
 
 function main() {

package/bin/gauntlet-telemetry-salvage.test.mjs

@@ -11,6 +11,11 @@
   const REC = ".pi/gauntlet/telemetry/doc/specs/x.yaml";
   const RECORD_V1 = "schema: 1\nspec: doc/specs/x.md\nstatus: in_progress\n";
   const RECORD_V2 = "schema: 1\nspec: doc/specs/x.md\nstatus: shipped\n";
+  // Records parseRecord accepts (run_id present). UNFINISHED: in_progress, no ship phase.
+  const UNFINISHED = "schema: 1\nspec: doc/specs/x.md\nrun_id: r-1\nstatus: in_progress\ncreated_at: 2026-09-17T16:11:45Z\nderived:\n  duration_s: 60\n  phases:\n    brainstorm: { started_at: 2026-09-17T16:11:45Z, duration_s: 60 }\n";
+  const SHIP_PHASE = UNFINISHED.replace("    brainstorm:", "    ship: { started_at: 2026-09-17T16:12:45Z }\n    brainstorm:");
+  const SCALAR_PHASES = UNFINISHED.replace("  phases:\n    brainstorm: { started_at: 2026-09-17T16:11:45Z, duration_s: 60 }", "  phases: nope");
+  const FINISHED = UNFINISHED.replace("status: in_progress", "status: shipped\nshipped_at: 2026-09-17T18:56:13Z");
 
   const git = (cwd, args, env = {}) =>
     spawnSync("git", ["-c", "user.name=t", "-c", "user.email=t@t", "-c", "commit.gpgsign=false", ...args], {
@@ -32,7 +37,7 @@
     return out(root, ["rev-parse", "HEAD"]);
   };
   // main: README only. feat: spec (+ record when withRecord).
-  const repo = ({ withRecord = true } = {}) => {
+  const repo = ({ withRecord = true, record = RECORD_V1 } = {}) => {
     const root = mkdtempSync(join(tmpdir(), "gts-"));
     git(root, ["init", "-q", "-b", "main"]);
     write(root, "README.md", "# fixture\n");
@@ -41,7 +46,7 @@
     write(root, SPEC, "# Spec X\n\n**Goal:** g.\n");
     commit(root, "Add spec", SPEC);
     if (withRecord) {
-      write(root, REC, RECORD_V1);
+      write(root, REC, record);
       commit(root, "telemetry: doc/specs/x.md", REC);
     }
     return root;
@@ -348,6 +353,103 @@ PATH="${process.env.PATH.split(":").filter((part) => part !== bin).join(":")}" e
     assert.equal(out(remote, ["for-each-ref"]), remoteBefore);
   });
 
+  test("present + unfinished -> stamped shipped, one telemetry: commit, clean tree", (t) => {
+    const root = repo({ record: UNFINISHED }); cleanup(t, root);
+    const n = commitCount(root);
+    const r = run(root);
+    assert.equal(r.status, 0, r.stderr);
+    assert.deepEqual(r.lines, [`present ${REC} (marked shipped)`]);
+    const text = readFileSync(join(root, REC), "utf8");
+    assert.match(text, /^status: shipped$/m);
+    assert.match(text, /^shipped_at: \d{4}-\d{2}-\d{2}T/m);
+    assert.doesNotMatch(text, /in_progress/);
+    assert.equal(commitCount(root), n + 1);
+    assert.equal(headSubject(root), `telemetry: mark ${REC} shipped at landing`);
+    assert.deepEqual(headFiles(root), [REC]);
+    assert.equal(porcelain(root), "");
+  });
+
+  test("present + scalar phases -> stamped shipped, exit 0", (t) => {
+    const root = repo({ record: SCALAR_PHASES }); cleanup(t, root);
+    const r = run(root);
+    assert.equal(r.status, 0, r.stderr);
+    assert.deepEqual(r.lines, [`present ${REC} (marked shipped)`]);
+    assert.match(readFileSync(join(root, REC), "utf8"), /^status: shipped$/m);
+  });
+
+  test("present + in_progress with a ship phase -> untouched", (t) => {
+    const root = repo({ record: SHIP_PHASE }); cleanup(t, root);
+    const before = head(root);
+    const r = run(root);
+    assert.deepEqual(r.lines, [`present ${REC}`]);
+    assert.equal(head(root), before);
+    assert.equal(readFileSync(join(root, REC), "utf8"), SHIP_PHASE);
+  });
+
+  test("present + unfinished but worktree copy dirty -> untouched, present", (t) => {
+    const root = repo({ record: UNFINISHED }); cleanup(t, root);
+    write(root, REC, UNFINISHED + "# local edit\n");
+    const before = head(root);
+    const r = run(root);
+    assert.deepEqual(r.lines, [`present ${REC}`]);
+    assert.equal(head(root), before);
+    assert.equal(readFileSync(join(root, REC), "utf8"), UNFINISHED + "# local edit\n");
+  });
+
+  test("present + already shipped -> byte-identical, no commit", (t) => {
+    const root = repo({ record: FINISHED }); cleanup(t, root);
+    const before = head(root);
+    const r = run(root);
+    assert.deepEqual(r.lines, [`present ${REC}`]);
+    assert.equal(head(root), before);
+    assert.equal(readFileSync(join(root, REC), "utf8"), FINISHED);
+  });
+
+  test("restore with scalar phases -> stamped shipped, exit 0", (t) => {
+    const root = repo({ record: SCALAR_PHASES }); cleanup(t, root);
+    const del = rmCommit(root, "strip", REC);
+    const r = run(root);
+    assert.equal(r.status, 0, r.stderr);
+    assert.deepEqual(r.lines, [`restored ${REC} from ${del} (marked shipped)`]);
+    assert.match(out(root, ["show", `HEAD:${REC}`]), /^status: shipped$/m);
+  });
+
+  test("restore of an unfinished record -> one commit whose bytes carry the stamp", (t) => {
+    const root = repo({ record: UNFINISHED }); cleanup(t, root);
+    const del = rmCommit(root, "strip", REC);
+    write(root, REC, UNFINISHED);
+    const n = commitCount(root);
+    const r = run(root);
+    assert.deepEqual(r.lines, [`restored ${REC} from ${del} (marked shipped)`]);
+    assert.equal(commitCount(root), n + 1);
+    const committed = out(root, ["show", `HEAD:${REC}`]);
+    assert.match(committed, /^status: shipped$/m);
+    assert.match(committed, /^shipped_at: /m);
+    assert.equal(porcelain(root), "");
+  });
+
+  test("--check on present + unfinished -> unfinished <rec>, nothing changes", (t) => {
+    const root = repo({ record: UNFINISHED }); cleanup(t, root);
+    const before = head(root);
+    const r = run(root, ["--check"]);
+    assert.deepEqual(r.lines, [`unfinished ${REC}`]);
+    assert.equal(head(root), before);
+    assert.equal(readFileSync(join(root, REC), "utf8"), UNFINISHED);
+    assert.equal(porcelain(root), "");
+  });
+
+  test("present + unfinished, rejecting pre-commit hook -> restore failed, HEAD bytes and index restored", (t) => {
+    const root = repo({ record: UNFINISHED }); cleanup(t, root);
+    write(root, ".git/hooks/pre-commit", "#!/bin/sh\nexit 1\n");
+    chmodSync(join(root, ".git/hooks/pre-commit"), 0o755);
+    const before = head(root);
+    const r = run(root);
+    assert.match(r.stdout, new RegExp(`^restore failed ${REC.replace(/\./g, "\\.")}: `));
+    assert.equal(head(root), before);
+    assert.equal(readFileSync(join(root, REC), "utf8"), UNFINISHED);
+    assert.equal(porcelain(root), "");
+  });
+
   test("finishing Option 1 fixture: strip-on-branch + salvage + merge --squash leaves the record, not the plan, staged", (t) => {
     const root = repo(); cleanup(t, root);
     const plan = "doc/plans/x.md";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-gauntlet",
-  "version": "5.11.0",
+  "version": "5.12.0",
   "description": "Opinionated, gated workflow skills, subagent personas, and runtime extensions for the pi coding agent.",
   "author": "Jacek Juraszek",
   "type": "module",
@@ -33,7 +33,8 @@
   ],
   "bin": {
     "gauntlet-spec-index": "bin/gauntlet-spec-index.mjs",
-    "gauntlet-telemetry-salvage": "bin/gauntlet-telemetry-salvage.mjs"
+    "gauntlet-telemetry-salvage": "bin/gauntlet-telemetry-salvage.mjs",
+    "gauntlet-performance": "bin/gauntlet-performance.mjs"
   },
   "engines": {
     "node": ">=24.15.0"

package/skills/finishing-a-development-branch/SKILL.md

@@ -177,7 +177,7 @@ fi
 node <bin>/gauntlet-telemetry-salvage.mjs --worktree "$WORKTREE" --base <base-branch>
 ```
 
-The salvage prints one line per spec on the branch (`present`, `restored <path> from <sha>`, `no telemetry run`, `never written`, `restore failed <path>: <reason>`) and always exits 0. Print its stdout verbatim in the ship completion message. A `restore failed` line is reported, never retried, and never blocks the ship - the record stays recoverable from the branch ref.
+The salvage prints one line per spec on the branch (`present`, `present <path> (marked shipped)`, `restored <path> from <sha>`, `restored <path> from <sha> (marked shipped)`, `no telemetry run`, `never written`, `restore failed <path>: <reason>`) and always exits 0. `(marked shipped)` means the record was still `in_progress` with no ship phase (the recorder lost its binding) and the salvage committed `status: shipped` + `shipped_at` as one `telemetry:` commit; it rides the squash or push like any branch commit. Print its stdout verbatim in the ship completion message. A `restore failed` line is reported, never retried, and never blocks the ship - the record stays recoverable from the branch ref.
 
 #### Option 1: Squash-merge to base
 

package/skills/gatekeep-pr/SKILL.md

@@ -174,6 +174,7 @@ verification command may write to the tree while the Reviewer reads it):
   squash. On a cell with no push row (fork overlay, report-only states) the same
   finding is a non-blocking follow-up instead: the record stays recoverable from the
   PR head ref after merge, and blocking would stop a ship the gate cannot repair.
+  `unfinished <path>` (record still `in_progress` with no ship phase) also lands in `## Evidence` as one line and is non-blocking: pre-landing `in_progress` is normal, and the merge course's salvage run stamps it.
 - **Evidence:** On the CI path, list each satisfying check's name, conclusion, assessed SHA, and run URL - there is no command or raw_tail to paste. On the local path, paste each run's `command` and `raw_tail` verbatim, fenced - never
   paraphrased. Any authored summary is labeled as a summary and never substitutes for
   `raw_tail`.
@@ -256,7 +257,7 @@ are never bundled into one selection, with one scoped exception: the selected me
 course first runs `node <bin>/gauntlet-telemetry-salvage.mjs --worktree <provisioned
 path> --base origin/<baseRefName>` (no `--check`). `present` -> merge as-is. `restored
 <path> from <sha>` -> push that single `telemetry: restore` commit as part of this
-course, re-fetch `headRefOid`, and pass the new SHA to `--match-head-commit`. `restore
+course, re-fetch `headRefOid`, and pass the new SHA to `--match-head-commit`. A line ending `(marked shipped)` (`present` or `restored`) is handled the same way: push that single `telemetry:` commit, re-fetch `headRefOid`, pass the new SHA. `restore
 failed` -> merge proceeds, the reason is printed, and the follow-up names recovery
 from the PR head ref.
 
@@ -508,7 +509,7 @@ The menu is a state machine, not a one-shot report:
    reviewed doc edits selected alongside them (one commit, or one per batch
    sequentially; subjects name the fixes) - then re-resolves the evidence for the new head **once** (the brief's stale-head row: prior evidence is stale; the local command executes only on a fallback/opt-out resolution). Before the push, run
    `node <bin>/gauntlet-telemetry-salvage.mjs --worktree <provisioned path> --base
-   origin/<baseRefName>` (no `--check`); a `restored` commit rides the wave's single
+   origin/<baseRefName>` (no `--check`); a `restored` or `(marked shipped)` commit rides the wave's single
    push and the pushed SHA becomes the assessed head under the course's-own-push rule
    in step 1. Print its stdout in the re-rendered report's `## Evidence`. **On
    green**, push **once**; gate and push are per-wave invariants, never per-fix or

package/skills/gauntlet-performance/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: gauntlet-performance
+description: Use when a human asks how gauntlet runs perform across the recorded telemetry - explicit invocation only (/skill:gauntlet-performance [--dir <path>]... [--since <version>]).
+disable-model-invocation: true
+---
+
+# Gauntlet Performance
+
+The CLI parses and aggregates; you reason. Never open a telemetry YAML record yourself.
+
+## Run the digest
+
+1. Resolve the CLI: `<directory of this SKILL.md>/../../bin/gauntlet-performance.mjs`.
+2. Run it from the repo root, passing the user's `--dir` and `--since` arguments verbatim:
+   `node <bin>/gauntlet-performance.mjs [--dir <path>]... [--since <version>]`.
+   Default corpus is the current repo; each `--dir` adds a repo root or a telemetry dir.
+3. If the command is missing or the output contains `no records found`, relay that line and stop - no menu.
+
+## Read the digest
+
+`runs` has one row per record; `shipped*` marks a truncated run (no ship phase recorded - salvage stamped it at landing; its `wall` is `-` and it feeds no aggregate). `by version` groups by pi-gauntlet version: `n` counts every row, `shipped` counts the rows behind the p50/max columns. `grants` is `fix_round_grants` - the fix-round proxy (human-granted extra review rounds); schema 1 has no code-review round count.
+
+## Reply - exactly this, in this order
+
+1. **Recommendation** (2-4 sentences). One claim, led by the run that exemplifies it: quote its `spec` slug, `run_id`, and the 1-3 numbers that carry the claim. When `grants` is the evidence, call it the fix-round proxy. If no version group has `shipped >= 2`, the recommendation is "sample too small" with the `n`/`shipped` counts per version.
+2. **Cornerstones**: 3-5 bullets of aggregate facts from `by version` - corpus size, truncated count, the p50s and model tallies that moved between versions.
+3. **Menu**, numbered, at most 3 items, rendered exactly as:
+   - `1. render report` - ask for a target path; write markdown there: the digest verbatim, then the recommendation and cornerstones above. If the file exists, ask before overwriting. Write nothing unless this item is chosen.
+   - `2. open recommendation as ticket` - hand the claim and its numbers to `/skill:shape-ticket`; never create a ticket directly.
+   - `3. drill into <slug>` - re-run the CLI with `--json` and show that run's fields.
+
+Nothing else: no preamble, no restated digest, no file written before item 1 is chosen.
+
+## Project overrides
+
+If a gauntlet overrides file exists - checked in order:
+`.pi/gauntlet-overrides.md`, `<repo root>/gauntlet-overrides.md`,
+`<repo root>/doc/gauntlet-overrides.md`; first found wins - read it. Any
+sections relevant to this skill - by name match, by topic (routing,
+verification, worktrees, etc.), or by workflow convention - override or
+extend the instructions above. Project-local `AGENTS.md` is already in
+context - check it for project-specific routing tables, service paths, and
+verification commands.