pi-gauntlet 5.10.0 → 5.10.2

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## 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.
+
+## v5.10.1 - 2026-09-18
+
+- `skills/brainstorming/SKILL.md`: restore precision the 5.10.0 dedup dropped - first-feature round 1 lists the concrete decisions (public types/files/routes/identifiers; abstraction location/responsibility/boundary; schema entity names/field types/indexing), doc updates ship in the same commit as the code, the premise note is full sentences and an unverified claim is not a stop, a multi-concern request is decomposed rather than designed as one spec, 300-500 words is a target per round, and the gather-stop red flag links to `gatherer.md`.
+
 ## v5.10.0 - 2026-09-18
 
 - Council provenance: member findings (except `over-spec`) end with `probed: <source or check> - <result> | none`; the chair tags each suggested edit `grounded:` or `hypothesis:` (`external-ref:` and `over-spec:` clusters stay untagged); `roasting-the-spec` probes `hypothesis` data-shape claims once (bounded, read-only, artifact at hand) before applying, else lands them as one grouped Open Question per artifact; `Applied:` audit lines carry the probe.

package/README.md

@@ -71,7 +71,7 @@ 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>]`.
 - **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) 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 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.
 

package/bin/gauntlet-telemetry-salvage.mjs

@@ -0,0 +1,141 @@
+#!/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";
+import { homedir } from "node:os";
+import { isAbsolute, join } from "node:path";
+import { spawnSync } from "node:child_process";
+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";
+
+const GIT_TIMEOUT_MS = 10_000;
+const COMMIT_TIMEOUT_MS = Number(process.env.GAUNTLET_SALVAGE_COMMIT_TIMEOUT_MS) || 30_000;
+const GIT_ENV = { ...process.env, GIT_TERMINAL_PROMPT: "0", GIT_EDITOR: "true" };
+
+const usage = () => {
+  process.stderr.write("usage: gauntlet-telemetry-salvage --worktree <abs path> [--base <ref>] [--dir <telemetry dir>] [--check]\n");
+  process.exit(1);
+};
+
+function parseArgs(argv) {
+  const opts = { worktree: undefined, base: undefined, dir: undefined, check: false };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--worktree" && argv[i + 1] !== undefined && !argv[i + 1].startsWith("--")) opts.worktree = argv[++i];
+    else if (a === "--base" && argv[i + 1] !== undefined && !argv[i + 1].startsWith("--")) opts.base = argv[++i];
+    else if (a === "--dir" && argv[i + 1] !== undefined && !argv[i + 1].startsWith("--")) opts.dir = argv[++i];
+    else if (a === "--check") opts.check = true;
+    else usage();
+  }
+  if (!opts.worktree || !isAbsolute(opts.worktree)) usage();
+  return opts;
+}
+
+function git(cwd, args, timeout = GIT_TIMEOUT_MS) {
+  const r = spawnSync("git", args, { cwd, encoding: "utf8", env: GIT_ENV, timeout });
+  const timedOut = r.error?.code === "ETIMEDOUT";
+  const stderr = timedOut ? "timed out" : (r.stderr ?? "").trim().split("\n")[0] || r.error?.message || `git exited ${r.status}`;
+  return { ok: !timedOut && r.status === 0, stdout: (r.stdout ?? "").trim(), stderr, timedOut };
+}
+
+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 reads (gauntlet-settings-loader.ts), without the pi import.
+function telemetrySettings(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"));
+  return resolveTelemetry(mergeGauntlet(preset?.piGauntlet, repo?.piGauntlet));
+}
+
+function resolveBase(root, explicit) {
+  for (const ref of explicit ? [explicit] : BASE_REFS) {
+    if (git(root, ["rev-parse", "--verify", "-q", `${ref}^{commit}`]).ok) return ref;
+  }
+  return undefined;
+}
+
+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}`;
+  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}`;
+  const deletion = git(root, ["log", "-1", "--diff-filter=D", "--format=%H", `${base}..HEAD`, "--", rec]);
+  if (deletion.timedOut) return `restore failed ${rec}: timed out`;
+  const del = deletion.stdout;
+  if (!del) return `never written ${rec}`;
+  if (check) return `stripped ${rec} in ${del}`;
+
+  const abs = join(root, rec);
+  const onDisk = existsSync(abs);
+  const preStaged = git(root, ["ls-files", "--", rec]).stdout !== "";
+  // A pre-staged record is user-owned and can only be committed when the worktree matches it.
+  if (preStaged && (!onDisk || !git(root, ["diff", "--quiet", "--", rec]).ok)) {
+    return `restore failed ${rec}: staged copy differs from worktree`;
+  }
+  let created = false;
+  let stagedByScript = false;
+  const rollback = () => {
+    if (stagedByScript) git(root, ["reset", "-q", "--", rec]);
+    if (created) rmSync(abs, { force: true });
+  };
+  const failed = (reason) => {
+    rollback();
+    return `restore failed ${rec}: ${reason}`;
+  };
+
+  if (!onDisk) {
+    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;
+  }
+  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}`;
+}
+
+function main() {
+  const opts = parseArgs(process.argv.slice(2));
+  const override = opts.dir === undefined
+    ? undefined
+    : resolveTelemetry({ telemetry: { enabled: true, dir: opts.dir } });
+  if (override?.warning) usage();
+  const top = git(opts.worktree, ["rev-parse", "--show-toplevel"]);
+  if (!existsSync(opts.worktree) || !top.ok) {
+    process.stderr.write(`not a git worktree: ${opts.worktree}\n`);
+    return;
+  }
+  const root = top.stdout;
+  const telemetry = telemetrySettings(root);
+  if (telemetry.warning) process.stderr.write(`warning: ${telemetry.warning}\n`);
+  if (!telemetry.enabled) return console.log("telemetry disabled");
+  const dir = override?.dir ?? telemetry.dir;
+  const base = resolveBase(root, opts.base);
+  if (!base) return console.log("no base ref");
+  const diff = git(root, ["diff", "--name-only", `${base}...HEAD`]);
+  if (!diff.ok) return console.log("no base ref");
+  const specs = diff.stdout.split("\n").filter((f) => f && isSpecPath(f) && git(root, ["cat-file", "-e", `HEAD:${f}`]).ok);
+  if (specs.length === 0) return console.log("no spec on branch");
+  for (const spec of specs) console.log(salvage(root, recordPathFor(dir, spec), base, opts.check));
+}
+
+main();

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

@@ -0,0 +1,364 @@
+  import { test } from "node:test";
+  import assert from "node:assert/strict";
+  import { mkdtempSync, mkdirSync, writeFileSync, readFileSync, rmSync, existsSync, chmodSync } 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-telemetry-salvage.mjs");
+  const SPEC = "doc/specs/x.md";
+  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";
+
+  const git = (cwd, args, env = {}) =>
+    spawnSync("git", ["-c", "user.name=t", "-c", "user.email=t@t", "-c", "commit.gpgsign=false", ...args], {
+      cwd, encoding: "utf8", env: { ...process.env, ...env },
+    });
+  const out = (cwd, args) => git(cwd, args).stdout.trim();
+  const write = (root, rel, text) => {
+    mkdirSync(join(root, dirname(rel)), { recursive: true });
+    writeFileSync(join(root, rel), text);
+  };
+  const commit = (root, msg, ...paths) => {
+    git(root, ["add", "-f", "--", ...paths]);
+    git(root, ["commit", "-q", "-m", msg, "--", ...paths]);
+    return out(root, ["rev-parse", "HEAD"]);
+  };
+  const rmCommit = (root, msg, ...paths) => {
+    git(root, ["rm", "-q", "--", ...paths]);
+    git(root, ["commit", "-q", "-m", msg, "--", ...paths]);
+    return out(root, ["rev-parse", "HEAD"]);
+  };
+  // main: README only. feat: spec (+ record when withRecord).
+  const repo = ({ withRecord = true } = {}) => {
+    const root = mkdtempSync(join(tmpdir(), "gts-"));
+    git(root, ["init", "-q", "-b", "main"]);
+    write(root, "README.md", "# fixture\n");
+    commit(root, "init", "README.md");
+    git(root, ["checkout", "-q", "-b", "feat"]);
+    write(root, SPEC, "# Spec X\n\n**Goal:** g.\n");
+    commit(root, "Add spec", SPEC);
+    if (withRecord) {
+      write(root, REC, RECORD_V1);
+      commit(root, "telemetry: doc/specs/x.md", REC);
+    }
+    return root;
+  };
+  // An empty preset dir by default: the developer's real ~/.pi/agent/settings.json must never leak into fixtures.
+  const EMPTY_AGENT = mkdtempSync(join(tmpdir(), "gts-empty-agent-"));
+  process.on("exit", () => rmSync(EMPTY_AGENT, { recursive: true, force: true }));
+  // The CLI commits with whatever identity git resolves, like the recorder; CI runners have none.
+  const IDENTITY = { GIT_AUTHOR_NAME: "t", GIT_AUTHOR_EMAIL: "t@t", GIT_COMMITTER_NAME: "t", GIT_COMMITTER_EMAIL: "t@t" };
+  const invoke = (args, env = {}, options = {}) => {
+    const r = spawnSync(process.execPath, [CLI, ...args], {
+      encoding: "utf8", env: { ...process.env, ...IDENTITY, PI_CODING_AGENT_DIR: EMPTY_AGENT, ...env }, timeout: options.timeout,
+    });
+    return { status: r.status, stdout: r.stdout.trim(), stderr: r.stderr.trim(), lines: r.stdout.split("\n").filter(Boolean) };
+  };
+  const run = (root, args = [], env = {}) => invoke(["--worktree", root, "--base", "main", ...args], env);
+  const head = (root) => out(root, ["rev-parse", "HEAD"]);
+  const commitCount = (root) => Number(out(root, ["rev-list", "--count", "HEAD"]));
+  const headSubject = (root) => out(root, ["log", "-1", "--format=%s"]);
+  const headFiles = (root) => out(root, ["show", "--name-only", "--format=", "HEAD"]).split("\n").filter(Boolean);
+  const porcelain = (root) => out(root, ["status", "--porcelain"]);
+  const cleanup = (t, ...roots) => t.after(() => roots.forEach((r) => rmSync(r, { recursive: true, force: true })));
+
+  test("present: record in HEAD tree -> present, no commit", (t) => {
+    const root = repo(); cleanup(t, root);
+    const before = head(root);
+    const r = run(root);
+    assert.equal(r.status, 0, r.stderr);
+    assert.deepEqual(r.lines, [`present ${REC}`]);
+    assert.equal(head(root), before);
+  });
+
+  test("deleted once -> restored from <sha>, byte-identical, one telemetry: commit touching only the record", (t) => {
+    const root = repo(); cleanup(t, root);
+    const del = rmCommit(root, "Strip ephemeral plan and telemetry scaffolding", REC);
+    const n = commitCount(root);
+    const r = run(root);
+    assert.equal(r.status, 0, r.stderr);
+    assert.deepEqual(r.lines, [`restored ${REC} from ${del}`]);
+    assert.equal(readFileSync(join(root, REC), "utf8"), RECORD_V1);
+    assert.equal(commitCount(root), n + 1);
+    assert.equal(headSubject(root), `telemetry: restore record stripped in ${del.slice(0, 10)}`);
+    assert.deepEqual(headFiles(root), [REC]);
+    assert.equal(porcelain(root), "");
+  });
+
+  test("deleted twice -> restores the newest (second) content", (t) => {
+    const root = repo(); cleanup(t, root);
+    rmCommit(root, "strip 1", REC);
+    write(root, REC, RECORD_V2);
+    commit(root, "telemetry: doc/specs/x.md", REC);
+    const del2 = rmCommit(root, "strip 2", REC);
+    const r = run(root);
+    assert.deepEqual(r.lines, [`restored ${REC} from ${del2}`]);
+    assert.equal(readFileSync(join(root, REC), "utf8"), RECORD_V2);
+  });
+
+  test("deleted, then rewritten on disk untracked -> on-disk copy committed, not DEL^", (t) => {
+    const root = repo(); cleanup(t, root);
+    const del = rmCommit(root, "strip", REC);
+    write(root, REC, RECORD_V2);
+    const r = run(root);
+    assert.deepEqual(r.lines, [`restored ${REC} from ${del}`]);
+    assert.equal(out(root, ["show", `HEAD:${REC}`]), RECORD_V2.trim());
+    assert.equal(porcelain(root), "");
+  });
+
+  test("deleted and staged again uncommitted -> not present; staged copy committed", (t) => {
+    const root = repo(); cleanup(t, root);
+    const del = rmCommit(root, "strip", REC);
+    write(root, REC, RECORD_V2);
+    git(root, ["add", "-f", "--", REC]);
+    const r = run(root);
+    assert.deepEqual(r.lines, [`restored ${REC} from ${del}`]);
+    assert.equal(out(root, ["show", `HEAD:${REC}`]), RECORD_V2.trim());
+    assert.equal(porcelain(root), "");
+  });
+
+  test("pre-staged record missing from worktree -> failure preserves index and HEAD", (t) => {
+    const root = repo(); cleanup(t, root);
+    rmCommit(root, "strip", REC);
+    write(root, REC, RECORD_V2);
+    git(root, ["add", "-f", "--", REC]);
+    rmSync(join(root, REC));
+    const before = head(root);
+    const r = run(root);
+    assert.equal(r.stdout, `restore failed ${REC}: staged copy differs from worktree`);
+    assert.equal(out(root, ["show", `:${REC}`]), RECORD_V2.trim());
+    assert.equal(head(root), before);
+    assert.equal(existsSync(join(root, REC)), false);
+  });
+
+  test("pre-staged record differing from worktree -> failure preserves both copies and HEAD", (t) => {
+    const root = repo(); cleanup(t, root);
+    rmCommit(root, "strip", REC);
+    write(root, REC, RECORD_V2);
+    git(root, ["add", "-f", "--", REC]);
+    write(root, REC, RECORD_V1);
+    const before = head(root);
+    const r = run(root);
+    assert.equal(r.stdout, `restore failed ${REC}: staged copy differs from worktree`);
+    assert.equal(out(root, ["show", `:${REC}`]), RECORD_V2.trim());
+    assert.equal(readFileSync(join(root, REC), "utf8"), RECORD_V1);
+    assert.equal(head(root), before);
+  });
+
+  test("deleted in its introducing commit (amended away) -> nothing to restore, no file, clean index", (t) => {
+    const root = repo(); cleanup(t, root);
+    // The record's only commit is rewritten without it: git records no D entry whose parent lacks the blob,
+    // so the spec's "introducing commit" limitation surfaces as `never written` and the script leaves nothing behind.
+    git(root, ["rm", "-q", "--", REC]);
+    git(root, ["commit", "-q", "--amend", "--allow-empty", "-m", "telemetry: doc/specs/x.md"]);
+    const before = head(root);
+    const r = run(root);
+    assert.equal(r.status, 0, r.stderr);
+    assert.deepEqual(r.lines, [`never written ${REC}`]);
+    assert.equal(head(root), before);
+    assert.equal(existsSync(join(root, REC)), false);
+    assert.equal(porcelain(root), "");
+  });
+
+  test("no telemetry: commit on branch -> no telemetry run, no commit", (t) => {
+    const root = repo({ withRecord: false }); cleanup(t, root);
+    const n = commitCount(root);
+    const r = run(root);
+    assert.deepEqual(r.lines, [`no telemetry run ${REC}`]);
+    assert.equal(commitCount(root), n);
+  });
+
+  test("telemetry: commit for another path, no deletion of this one -> never written", (t) => {
+    const root = repo({ withRecord: false }); cleanup(t, root);
+    write(root, ".pi/gauntlet/telemetry/doc/specs/other.yaml", "x\n");
+    commit(root, "telemetry: doc/specs/other.md", ".pi/gauntlet/telemetry/doc/specs/other.yaml");
+    const r = run(root);
+    assert.deepEqual(r.lines, [`never written ${REC}`]);
+  });
+
+  test("--check on a stripped record -> stripped ... in <sha>, no commit, no file", (t) => {
+    const root = repo(); cleanup(t, root);
+    const del = rmCommit(root, "strip", REC);
+    const before = head(root);
+    const r = run(root, ["--check"]);
+    assert.deepEqual(r.lines, [`stripped ${REC} in ${del}`]);
+    assert.equal(head(root), before);
+    assert.equal(existsSync(join(root, REC)), false);
+    assert.equal(porcelain(root), "");
+  });
+
+  test("repo .pi/settings.json telemetry.enabled false -> telemetry disabled only", (t) => {
+    const root = repo(); cleanup(t, root);
+    write(root, ".pi/settings.json", JSON.stringify({ piGauntlet: { telemetry: { enabled: false } } }));
+    commit(root, "settings", ".pi/settings.json");
+    rmCommit(root, "strip", REC);
+    const r = run(root);
+    assert.equal(r.stdout, "telemetry disabled");
+  });
+
+  test("preset-only telemetry.dir via PI_CODING_AGENT_DIR resolves; --dir overrides both layers", (t) => {
+    const root = repo({ withRecord: false });
+    const agent = mkdtempSync(join(tmpdir(), "gts-agent-"));
+    cleanup(t, root, agent);
+    writeFileSync(join(agent, "settings.json"), JSON.stringify({ piGauntlet: { telemetry: { dir: "custom/dir" } } }));
+    const custom = "custom/dir/doc/specs/x.yaml";
+    write(root, custom, RECORD_V1);
+    commit(root, "telemetry: doc/specs/x.md", custom);
+    const del = rmCommit(root, "strip", custom);
+    const r = run(root, [], { PI_CODING_AGENT_DIR: agent });
+    assert.deepEqual(r.lines, [`restored ${custom} from ${del}`]);
+    const r2 = run(root, ["--dir", "elsewhere"], { PI_CODING_AGENT_DIR: agent });
+    assert.deepEqual(r2.lines, [`never written elsewhere/doc/specs/x.yaml`]);
+  });
+
+  test("rejecting pre-commit hook -> restore failed, index and worktree identical to before", (t) => {
+    const root = repo(); cleanup(t, root);
+    const del = rmCommit(root, "strip", REC);
+    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.equal(r.status, 0);
+    assert.match(r.stdout, new RegExp(`^restore failed ${REC.replace(/\./g, "\\.")}: `));
+    assert.equal(head(root), before);
+    assert.equal(existsSync(join(root, REC)), false);
+    assert.equal(porcelain(root), "");
+  });
+
+  test("hanging pre-commit hook -> restore failed ... timed out within the bound, state rolled back", (t) => {
+    const root = repo(); cleanup(t, root);
+    rmCommit(root, "strip", REC);
+    write(root, ".git/hooks/pre-commit", "#!/bin/sh\nsleep 60\n");
+    chmodSync(join(root, ".git/hooks/pre-commit"), 0o755);
+    const before = head(root);
+    const r = invoke(["--worktree", root, "--base", "main"], { GAUNTLET_SALVAGE_COMMIT_TIMEOUT_MS: "2000" }, { timeout: 20_000 });
+    assert.equal(r.status, 0);
+    assert.equal(r.stdout, `restore failed ${REC}: timed out`);
+    assert.equal(head(root), before);
+    assert.equal(existsSync(join(root, REC)), false);
+    assert.equal(porcelain(root), "");
+  });
+
+  test("timed-out record presence query -> restore failed, no mutation", (t) => {
+    const root = repo();
+    const bin = mkdtempSync(join(tmpdir(), "gts-bin-"));
+    cleanup(t, root, bin);
+    const wrapper = join(bin, "git");
+    writeFileSync(wrapper, `#!/bin/sh
+case "$*" in
+  *"cat-file -e HEAD:${REC}"*) sleep 60 ;;
+esac
+PATH="${process.env.PATH.split(":").filter((part) => part !== bin).join(":")}" exec git "$@"
+`);
+    chmodSync(wrapper, 0o755);
+    const before = head(root);
+    const r = invoke(["--worktree", root, "--base", "main"], { PATH: `${bin}:${process.env.PATH}` }, { timeout: 20_000 });
+    assert.equal(r.status, 0);
+    assert.equal(r.stdout, `restore failed ${REC}: timed out`);
+    assert.equal(head(root), before);
+    assert.equal(porcelain(root), "");
+  });
+
+  test("two specs on the branch, one record stripped -> two lines, one restore", (t) => {
+    const root = repo(); cleanup(t, root);
+    const spec2 = "doc/specs/y.md"; const rec2 = ".pi/gauntlet/telemetry/doc/specs/y.yaml";
+    write(root, spec2, "# Y\n"); commit(root, "Add y", spec2);
+    write(root, rec2, RECORD_V1); commit(root, "telemetry: doc/specs/y.md", rec2);
+    const del = rmCommit(root, "strip", REC);
+    const n = commitCount(root);
+    const r = run(root);
+    assert.deepEqual(r.lines.sort(), [`present ${rec2}`, `restored ${REC} from ${del}`].sort());
+    assert.equal(commitCount(root), n + 1);
+  });
+
+  test("spec deleted on the branch -> no spec on branch", (t) => {
+    const root = repo(); cleanup(t, root);
+    rmCommit(root, "reap superseded spec", SPEC, REC);
+    const r = run(root);
+    assert.equal(r.stdout, "no spec on branch");
+  });
+
+  test("unresolvable base without --base -> no base ref; --base main works", (t) => {
+    const root = repo(); cleanup(t, root);
+    git(root, ["branch", "-m", "main", "trunk"]);
+    const bare = invoke(["--worktree", root]);
+    assert.equal(bare.status, 0);
+    assert.equal(bare.stdout, "no base ref");
+    const r = invoke(["--worktree", root, "--base", "trunk"]);
+    assert.equal(r.stdout, `present ${REC}`);
+  });
+
+  test("--worktree at a non-git directory -> stderr not a git worktree, empty stdout, exit 0", (t) => {
+    const dir = mkdtempSync(join(tmpdir(), "gts-nogit-")); cleanup(t, dir);
+    const r = invoke(["--worktree", dir]);
+    assert.equal(r.status, 0);
+    assert.equal(r.stdout, "");
+    assert.match(r.stderr, /^not a git worktree: /);
+  });
+
+  test("relative --worktree -> usage on stderr, exit 1, empty stdout", () => {
+    const r = invoke(["--worktree", "relative/path"]);
+    assert.equal(r.status, 1);
+    assert.equal(r.stdout, "");
+    assert.match(r.stderr, /^usage: gauntlet-telemetry-salvage/);
+  });
+
+  test("escaping --dir -> usage on stderr, exit 1", (t) => {
+    const root = repo(); cleanup(t, root);
+    const r = invoke(["--worktree", root, "--dir", "../outside"]);
+    assert.equal(r.status, 1);
+    assert.equal(r.stdout, "");
+    assert.match(r.stderr, /^usage: gauntlet-telemetry-salvage/);
+  });
+
+  test("trailing slash in --dir is normalized", (t) => {
+    const root = repo({ withRecord: false }); cleanup(t, root);
+    const custom = "custom/dir/doc/specs/x.yaml";
+    write(root, custom, RECORD_V1);
+    commit(root, "telemetry: doc/specs/x.md", custom);
+    const del = rmCommit(root, "strip", custom);
+    const r = run(root, ["--dir", "custom/dir/"]);
+    assert.deepEqual(r.lines, [`restored ${custom} from ${del}`]);
+  });
+
+  test("value flag followed by another flag -> usage, exit 1, no git call", (t) => {
+    const root = repo(); cleanup(t, root);
+    const before = head(root);
+    const r = invoke(["--worktree", root, "--base", "--check"]);
+    assert.equal(r.status, 1);
+    assert.match(r.stderr, /^usage:/);
+    assert.equal(head(root), before);
+    assert.equal(invoke(["--worktree"]).status, 1);
+  });
+
+  test("never pushes: remote refs unchanged after a successful restore", (t) => {
+    const root = repo();
+    const remote = mkdtempSync(join(tmpdir(), "gts-remote-"));
+    cleanup(t, root, remote);
+    git(remote, ["init", "-q", "--bare"]);
+    git(root, ["remote", "add", "origin", remote]);
+    git(root, ["push", "-q", "origin", "main", "feat"]);
+    const remoteBefore = out(remote, ["for-each-ref"]);
+    rmCommit(root, "strip", REC);
+    const r = run(root);
+    assert.match(r.stdout, /^restored /);
+    assert.equal(out(remote, ["for-each-ref"]), remoteBefore);
+  });
+
+  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";
+    write(root, plan, "# plan\n"); commit(root, "Add plan", plan);
+    rmCommit(root, "Strip ephemeral plan and telemetry scaffolding", plan, REC);
+    const r = run(root);
+    assert.match(r.stdout, /^restored /);
+    git(root, ["checkout", "-q", "main"]);
+    git(root, ["merge", "--squash", "-q", "feat"]);
+    const staged = out(root, ["diff", "--cached", "--name-only"]).split("\n");
+    assert.ok(staged.includes(REC), "record staged");
+    assert.ok(staged.includes(SPEC), "spec staged");
+    assert.ok(!staged.includes(plan), "plan not staged");
+  });

package/package.json

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

package/skills/brainstorming/SKILL.md

@@ -66,7 +66,7 @@ The spec is the first commit in a dedicated worktree, never a separate commit on
 2. Carry its `Worktree ready at <full-path>` value: spec path `<full-path>/doc/specs/<filename>.md`; every dispatch uses that `cwd`; git uses `git -C <full-path>`. Keep the process cwd unchanged.
 3. Write, review, and commit there.
 
-Spec, plan, and implementation share this worktree; finishing strips the ephemeral plan before squash. Explicit trivial one-off edits outside this flow need no worktree.
+Spec, plan, and implementation share this worktree. The spec and its telemetry record (`<telemetry.dir>/<spec path with .md -> .yaml>`, default `.pi/gauntlet/telemetry/doc/specs/<spec>.yaml`) are deliverables and ship in the squash; only the plan is stripped. `/skill:finishing-a-development-branch` strips the plan before landing and restores a stripped record with `gauntlet-telemetry-salvage`. Explicit trivial one-off edits outside this flow need no worktree.
 
 ## The Process
 
@@ -82,7 +82,7 @@ One spec is default. Test seemingly independent concerns against `../shape-ticke
     outcome: <what a user observes once it ships>
     axis: <one item from the closed list>
 
-If any test fails, offer no split. Never split by service, package, repo, layer, or team. If all pass, ask whether to brainstorm the independent specs separately or explain their coupling.
+If any test fails, offer no split. Never split by service, package, repo, layer, or team. If all pass, ask whether to brainstorm the independent specs separately or explain their coupling. Decompose a genuinely multi-concern request; never design it as one spec.
 
 ### 3. Understand the idea
 
@@ -92,7 +92,7 @@ Ask one question per message, preferably multiple choice, about purpose, constra
 
 Append only citable findings - schemas, hard constraints, contradictions, and scope-changing answers - to `## Appended during questionary` using `edit`.
 
-Before approaches, state in chat the supported, disproved, corrected, and unverified premises with sources and attempted lookups. Put unverified claims in Open Questions or assumptions. If a load-bearing claim is contradicted, the premise note is your next message - even as question one - and asks the user to accept the corrected fact or override it; ask nothing else and propose nothing until answered. Record the outcome in the draft for `## Problem` or the relevant design decision.
+Before approaches, state in chat the supported, disproved, corrected, and unverified premises with sources and attempted lookups, in full sentences - no status-keyword lists, no template; if the design depends on no claims, one sentence says so. An unverified claim is not a stop: put it in Open Questions or a stated assumption. If a load-bearing claim is contradicted, the premise note is your next message - even as question one - and asks the user to accept the corrected fact or override it; ask nothing else and propose nothing until answered. Record the outcome in the draft for `## Problem` or the relevant design decision.
 
 ### 4. Explore approaches
 
@@ -104,7 +104,7 @@ Prefer clear testable boundaries, YAGNI, existing conventions, the owning schema
 
 ### 6. Present the design in two rounds
 
-Use two 300-500-word rounds with one approval each; revisions remain within that approval point. Ask once per round; round-1 approval without correction confirms the predecessor. Round 1 covers architecture, responsibilities, data flow, and `supersedes <path>, <scope>` when applicable. Round 2 covers errors, edges, tests, and `## Documentation impact`.
+Use two rounds, targeting 300-500 words each, with one approval each; revisions remain within that approval point. Ask once per round; round-1 approval without correction confirms the predecessor. Round 1 covers architecture, responsibilities, data flow, and `supersedes <path>, <scope>` when applicable. Round 2 covers errors, edges, tests, and `## Documentation impact`.
 
 `## Documentation impact` is required. Cite `reference/documentation-impact.md` by relative path, do not restate its categories, and reproduce this template verbatim:
 
@@ -115,7 +115,7 @@ Use two 300-500-word rounds with one approval each; revisions remain within that
   - Derived / memory docs invalidated: <routers / AGENTS.md sections / topic guides / indexes, or "none">
   ```
 
-Use doc names, `none`, or `deferred: <trigger>`. Apply `reference/documentation-impact.md`; amend an owner before creating a standalone file. Put project taxonomy in the overrides file's `## documentation` block. Ship doc updates with code and verify them at conformance. Clarify when needed.
+Use doc names, `none`, or `deferred: <trigger>`. Apply `reference/documentation-impact.md`; amend the existing owner; create a standalone file only where no doc owns the topic. Put project taxonomy in the overrides file's `## documentation` block (guidance only; no settings key). Doc updates ship in the same commit as the code and the conformance gate verifies them against the spec. Clarify when needed.
 
 ## Ticket Handling
 
@@ -123,7 +123,7 @@ A ticket is guidance, not sole truth. Fetch it; propose scope, approach, or acce
 
 ## First-Feature Oversight (Early Project Stages)
 
-For the first two features of a new module, long-lived component, schema area, or repeatable pattern, round 1 explicitly covers structure, naming, shared abstractions, persistence/schema, and proposed AGENTS.md/docs changes. Use no separate confirmation; later features follow established patterns.
+For the first two features of a new module, long-lived component, schema area, or repeatable pattern, round 1 explicitly lists: directory and module structure; naming of public types, files, routes, and identifiers; each new shared abstraction's location, responsibility, and boundary; persistence/schema entity names, field types, and indexing; proposed AGENTS.md/docs additions. Use no separate confirmation; later features follow established patterns.
 
 ## Anti-Pattern: "Too simple to need a design"
 
@@ -267,7 +267,7 @@ One question at a time, YAGNI, 2-3 approaches, two design rounds, clarify freely
 - Inline scope or ambiguity checks ([owner](#spec-council-optional)).
 - Gate after failed/skipped critique or before placeholder re-scan ([owner](#spec-self-review-before-user-review-gate)).
 - Gate without summary `Read` last, or with a paraphrased summary ([owner](#user-review-gate)).
-- Human stop between gather and question one ([owner](#the-process)).
+- Human stop between gather and question one ([owner](gatherer.md)).
 - Proposed-change execution before approval ([owner](#hard-constraint)).
 - Plan before approval; brainstorming invocation for an amend ([owner](#user-review-gate)).
 - Missing predecessor banner; invalid multi-spec split ([owner](#spec-self-review-before-user-review-gate); [owner](#2-scope-check)).

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

@@ -162,18 +162,38 @@ Which option?
 
 ### Step 5: Execute Choice
 
+#### Strip the plan, keep the record (Options 1 and 2)
+
+Run this on the feature branch before either landing path. The spec and its telemetry record (`<telemetry.dir>/<spec path with .md -> .yaml>`, default `.pi/gauntlet/telemetry/doc/specs/<spec>.yaml`) are deliverables and ship in the squash; only the plan is stripped. `<bin>` is `<directory of this skill's SKILL.md>/../../bin`, resolved from the skill's `<location>` in the system prompt.
+
+```bash
+# Plans are ephemeral - if one was committed on this branch, remove it before landing.
+PLAN_PATH=doc/plans/<plan-file>.md   # or <service>/doc/plans/<plan-file>.md
+if git -C "$WORKTREE" ls-files --error-unmatch "$PLAN_PATH" >/dev/null 2>&1; then
+  git -C "$WORKTREE" rm "$PLAN_PATH" && git -C "$WORKTREE" commit -m "Remove ephemeral plan doc"
+fi
+
+# The telemetry record is a deliverable - restore it if a strip or a stray delete removed it.
+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.
+
 #### Option 1: Squash-merge to base
 
+Run the strip-and-salvage block above first (plan stripped, telemetry record kept), then:
+
 ```bash
 git -C "$PRIMARY" checkout <base-branch>
 git -C "$PRIMARY" pull
 git -C "$PRIMARY" merge --squash "$FEATURE"
-git -C "$PRIMARY" rm doc/plans/<plan-file>.md   # or <service>/doc/plans/<plan-file>.md
 git -C "$PRIMARY" commit -m "<imperative summary> (ref <ticket-id>)"
 (cd "$PRIMARY" && <Step 1 command for the service(s) touched>)
 ```
 
-The post-squash re-verify is not optional — `git merge --squash` can surface conflict-resolution mistakes the worktree-side run couldn't catch.
+The plan was already removed on the branch, so the staged squash tree carries the spec, the telemetry record, and the implementation - never the plan.
+
+The post-squash re-verify is not optional - `git merge --squash` can surface conflict-resolution mistakes the worktree-side run couldn't catch.
 
 Cleanup worktree (Step 6), then, if Step 6 removed the worktree, `git -C "$PRIMARY" branch -D "$FEATURE"`.
 
@@ -181,16 +201,14 @@ Cleanup worktree (Step 6), then, if Step 6 removed the worktree, `git -C "$PRIMA
 
 #### Option 2: Push and Create PR
 
-```bash
-# Plans are ephemeral - if one was committed on this branch, remove it before the PR diff is opened.
-PLAN_PATH=doc/plans/<plan-file>.md   # or <service>/doc/plans/<plan-file>.md
-if git -C "$WORKTREE" ls-files --error-unmatch "$PLAN_PATH" >/dev/null 2>&1; then
-  git -C "$WORKTREE" rm "$PLAN_PATH" && git -C "$WORKTREE" commit -m "Remove ephemeral plan doc"
-fi
+Run the strip-and-salvage block above first (plan stripped, telemetry record kept), then:
 
+```bash
 # Push branch
 git -C "$WORKTREE" push -u origin "$FEATURE"
+```
 
+```bash
 # Create PR
 (cd "$WORKTREE" && gh pr create --title "<title>" --body "$(cat <<'EOF'
 ## Summary
@@ -245,10 +263,10 @@ Removal precedes branch deletion in both options; `git branch -d`/`-D` fails whi
 
 ## Quick Reference
 
-| Option | Merge | Push | Keep Worktree | Cleanup Branch | Plan-doc removal |
+| Option | Merge | Push | Keep Worktree | Cleanup Branch | Plan strip + record salvage |
 |---|---|---|---|---|---|
-| 1. Squash-merge locally | yes (squash) | - | - | yes (after Step 6 removal) | yes (unconditional) |
-| 2. Create PR | - | yes | yes | - | yes (guarded, before push) |
+| 1. Squash-merge locally | yes (squash) | - | - | yes (after Step 6 removal) | yes (guarded, on the branch before squash) |
+| 2. Create PR | - | yes | yes | - | yes (guarded, on the branch before push) |
 | 3. Keep as-is | - | - | yes | - | - |
 | 4. Discard | - | - | - | yes (force, after Step 6 removal) | - |
 
@@ -284,9 +302,13 @@ A host-owned worktree (Step 6 "Otherwise") keeps both the worktree and the branc
 - **Problem:** Accidentally delete work
 - **Fix:** Require typed "discard" confirmation
 
-**Skipping the plan-doc deletion in Options 1 and 2 (any path that lands on base)**
-- **Problem:** Plan docs are ephemeral and shouldn't land on `<base-branch>`. Forgetting `git -C "$PRIMARY" rm doc/plans/<plan-file>.md` ships scaffolding to main.
-- **Fix:** The plan stays in the deleted branch's git history (`git -C "$PRIMARY" log --all -- doc/plans/...`). Spec stays on `<base-branch>`; plan does not.
+**Skipping the strip-and-salvage block in Options 1 and 2 (any path that lands on base)**
+- **Problem:** Plan docs are ephemeral and shouldn't land on `<base-branch>`; the telemetry record is a deliverable and must. Skipping the block ships the plan, or drops the record the spec index reads.
+- **Fix:** Run the block on `$WORKTREE` before the squash or the push. The plan stays in the branch's git history (`git -C "$PRIMARY" log --all -- doc/plans/...`). Spec and telemetry record stay on `<base-branch>`; plan does not.
+
+**Widening the plan strip to the telemetry record**
+- **Problem:** `.pi/gauntlet/telemetry/**` looks like scaffolding next to the plan and gets deleted in the same commit - main then has no record for the run.
+- **Fix:** Never `git rm` under the telemetry dir. The salvage restores a stripped record, but the deletion should not happen in the first place.
 
 ## Completion
 
@@ -309,10 +331,12 @@ Once the merge (and any deploy) has landed, `/skill:check-delivery <ticket-ref>`
 - Clean up worktrees you didn't create (provenance check)
 - Run any step without the `<worktree-path>` argument
 - Auto-proceed past an undispositioned carried-open gap
-- Skip the guarded plan-doc removal before push on Option 2 when a plan doc was committed
+- Skip the strip-and-salvage block before the Option 1 squash or the Option 2 push
+- Delete the telemetry record (`.pi/gauntlet/telemetry/**` or the configured `telemetry.dir`) on any path
 
 **Always:**
 - Verify tests before offering options
+- Print the `gauntlet-telemetry-salvage.mjs` output verbatim in the ship completion message
 - Derive `$PRIMARY` and `$FEATURE` from `<worktree-path>` before presenting the menu
 - Present exactly 4 options (or 3 for detached HEAD)
 - Get typed confirmation for Option 4

package/skills/gatekeep-pr/SKILL.md

@@ -164,6 +164,16 @@ verification command may write to the tree while the Reviewer reads it):
   `<sha>` is the assessed `headRefOid`, `<url>` degrades to `unavailable` when
   absent. Provenance checks on `worktree_root`/`run_cwd` bind only to the local
   path.
+- **Telemetry record:** run `node <bin>/gauntlet-telemetry-salvage.mjs --worktree
+  <provisioned path> --base origin/<baseRefName> --check` (`<bin>` = `<directory of
+  this skill's SKILL.md>/../../bin`). Detect-only: it never mutates. `present` / `no
+  telemetry run` / `never written` land in `## Evidence` as one line each. `stripped
+  <path> in <sha>` mints a blocking `P#` (`source_ref`:
+  `gauntlet-telemetry-salvage`) whose drafted fix is "run the salvage without
+  `--check`" - the spec and its telemetry record are deliverables that ship in the
+  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.
 - **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`.
@@ -242,7 +252,13 @@ head (fixes pushed first); explicit selection with a head compare-and-swap that
 passes. A merge selection while any precondition fails is refused, naming the failing
 precondition, and the menu re-renders - never a dead end, never a silent merge. Merge
 always executes as `gh pr merge --match-head-commit <assessed-sha>`; push and merge
-are never bundled into one selection.
+are never bundled into one selection, with one scoped exception: the selected merge
+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
+failed` -> merge proceeds, the reason is printed, and the follow-up names recovery
+from the PR head ref.
 
 **Consent menu** (deterministic - this table is the golden-scenario oracle):
 
@@ -364,7 +380,8 @@ Actions (compose freely in the custom row):
                                                                         reviewed doc edits exist
                                                                         in the worktree)
   merge-squash | merge-commit                                          (preconditions per Verdict;
-                                                                        never bundled with a push)
+                                                                        never bundled with a push,
+                                                                        except the telemetry: restore commit)
   request-changes | review-comment | approve                           (approve: never own PR)
   reply <C#s>      post drafted thread replies
   tracker <act>    tracker action                                      (only when a tracker tool resolved)
@@ -474,8 +491,11 @@ The menu is a state machine, not a one-shot report:
    orchestrator owns commit, gate, and push - never a child. Every dispatched
    child gets `cwd` = the PR worktree, **`worktree: true` forbidden** (a separate
    isolated worktree breaks the shared-tree contract - see Inline-first
-   execution); is **edit-only, no git commands, no verification runs**; and its
-   task is that batch's `P#` lines **plus the drafted edit already keyed to each
+   execution); is **edit-only, no git commands, no verification runs**, and must
+   never delete `.pi/gauntlet/telemetry/**` or anything under the configured
+   telemetry dir (a fix that "cleans up" the run's telemetry record is a defect in
+   the fix - the record is a deliverable); and its task is that batch's `P#` lines
+   **plus the drafted edit already keyed to each
    ID** in `## Drafted fixes / review` - the child applies the consented payload,
    it does not re-solve the finding. Below the cutoff (<= 2 worktree-fixable findings), the orchestrator
    applies inline instead of dispatching - the no-cohort path stays available at
@@ -486,7 +506,11 @@ The menu is a state machine, not a one-shot report:
    Once every dispatched/inline batch returns, the orchestrator commits the golden
    course as one local commit set - the code fixes plus any already-applied
    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). **On
+   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
+   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
    per-batch. **On red**, do not push: leave the commit(s) local, re-render with
    the unresolved `P#`s still open, and warn that unpushed fix commits sit in the