pi-gauntlet 8.4.2 → 8.4.3

package/CHANGELOG.md

@@ -1,5 +1,9 @@
 # Changelog
 
+## v8.4.3 - 2026-11-08
+
+- Telemetry publishes and reads `refs/telemetry/records` outside branch namespaces. The migration guide orders machine upgrades, repeatable record carry with `--migrate-branch`, verified remote retirement with `--retire-branch`, local cleanup and removal of the old CI exclusion. (#130)
+
 ## v8.4.2 - 2026-11-07
 
 ### Fixed

package/README.md

@@ -99,7 +99,7 @@ pi-gauntlet ships three kinds of pieces, layered on top of pi-cohort's dispatch:
 
 - **21 skills** - the workflow logic. Sixteen activate automatically when pi sees the matching kind of task, and the workflow skills chain through their gates: `shape-ticket` (creates one tracker issue or repairs a comma/whitespace list of refs against a Context/Problem/Idea/Acceptance-Criteria template, with a grounded repo audit, an AC integrity check, a cheap council roast, and sequential per-ticket exact-diff write confirmations; model-invocable so other skills and commands can route "file a ticket" to it, the gate still needs your yes), `gatekeep-pr` (model-invocable on an explicit ask that names the PR and the verb; the gates still need your selection - is consent-gated pre-merge verification of a PR against the scope contract at its head - the approved spec's acceptance-criteria dispositions and Design when the PR carries one, else the PR's stated intent; the ticket is cross-checked, never judged here (`check-delivery` owns it) - read-only gathering, verification evidence resolved CI-first (green checks on the exact assessed head count as evidence; a pending commit status that GitHub does not report as blocking the gating actor (`mergeStateStatus` not `BLOCKED`) is not waited for - external-CI commit statuses included - while a running Actions check and an unknown merge state still withhold; a viewer GitHub reports as a ruleset bypass actor merges a `BLOCKED` PR on the ordinary `merge` row with CI evidence still binding and all other merge preconditions unchanged; false or unreadable bypass eligibility keeps `BLOCKED` withheld, and live non-admin bypass behavior remains unverified; the project's verification command runs only as fallback), a rubric-based review, a compact bottom-up report (what the PR delivers, including rows deferred or deviating per spec, PR comments, nits, blockers, then a `mergeable` / `fixable` verdict) and course and terminal menus whose rows derive from the actor's permissions on the PR; nothing mutates (repairs, pushes, reviews, merges, tracker comments) until you pick a course or terminal row, except the opt-in `--rebase [base]` sync that rebases, reviews, and lease-pushes the head before verification, or holds the rebased head locally when a conflict stop's scoped tests fail, so a selected delivery course resolves it before the lease push; after your own merge two opt-in rows post the `AC coverage` block to the ticket or the PR; own-merge, approved, and closed-PR menus offer a recommended `cleanup` row that tears down the gate's worktree and branch and runs the overrides file's `## cleanup` steps - run it with `/skill:gatekeep-pr [<pr>] [--rebase [base]]` (no argument: your open PRs)), `check-delivery` (model-invocable on an explicit ask that names the ticket and the verb; the gates still need your selection - 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>` or, in pi, `/skill:check-delivery #12 #15` for fresh parallel verification and one gate and write per ticket in turn), `writing-plans`, `roasting-the-spec`, `test-driven-development`, `subagent-driven-development`, `loop-implementation` (the plan-free implement driver that iterates a fresh `loop-implementer` over the spec's acceptance-criteria ledger when approval picks the loop engine), `dispatching-parallel-agents`, `verification-before-completion`, `requesting-code-review`, `receiving-code-review`, `using-git-worktrees`, `finishing-a-development-branch`, `forge-skill`, `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 require explicit entry (`disable-model-invocation: true`): `brainstorming` starts the gated workflow on explicit consent - use `/skill:brainstorming` for reliable discovery, or opt in through reachable explicit prose or a human-selected handoff; after spec approval, downstream planning and implementation still chain automatically. `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, a council assessment when available, 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-handoff` ends a session whose flow a fresh session will continue: it invokes pi-cohort's `handoff` skill (`--out <path>` or `--key <name>`, default key = the run worktree's branch with `/` flattened to `-`, default file `<tmpdir>/pi-handoff/<key>.md`), then appends the gauntlet process-state section (phase/plan tracker status) per the shared contract `skills/gauntlet-resume/reference/brief-contract.md` - run it with `/skill:gauntlet-handoff [--out <path> | --key <name>]`. `gauntlet-resume` is the only way back into an interrupted flow from a fresh session: it takes a `gauntlet-handoff` brief (a file path, pasted text, or - with no arguments - a pick from the briefs under `<tmpdir>/pi-handoff/`), a bare worktree that already holds a spec, or a spec tracked on main under a configured spec dir (a spec seed: it creates or reuses the worktree through `using-git-worktrees` and pins the spec), restores phase/plan tracker state through the legal arming sequence (`start brainstorm`, `skip` with `resume:` reasons, `plan_check` before implement-or-later), and never infers approval from artifacts - run it with `/skill:gauntlet-resume [<brief-file> | <spec>.md | <worktree-name-or-path>]`.
 - **11 subagent personas** - the specialized child agents the skills dispatch via pi-cohort: `implementer`, `loop-implementer`, `wave-reviewer`, `conformance-reviewer`, `spec-summarizer`, `plan-writer`, `spec-council-member`, `spec-council-synthesizer`, `spec-council-applier`, `pr-gatekeeper`, `delivery-checker`. 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 (expected when a loop gate set does not match its patterns; the scoped `Verification:` line answers it, not a full local run); a phase-tracker flow guard reminds on implement-phase commits missing spec/code review. Both engines use the tracker: waves manages plan tasks, while loop calls `plan_tracker refresh` to project ledger rows and preserve conformance tasks. Loop implement completes when every row is closed, then verify step 1 runs the ledger's gate set in the owning checkouts. 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, and that every test command carries a passing base-commit result; a pass stamps the plan and spec content hashes for implementation and returns a bounded task manifest; see the [manifest contract and size limit](./doc/configuration.md#phase-tracker). `telemetry` publishes YAML records on the orphan `gauntlet/telemetry` branch, outside the product diff: one sealed brainstorming run plus one session leg per settled `shape-ticket`, `gatekeep-pr` or `check-delivery` invocation. In-progress runs live in Git common-dir metadata; `gauntlet-telemetry-seal` publishes before landing without changing checkout HEAD or index. Publication failure warns without blocking ship; plain jj keeps local metadata and reports no Git remote. A fetched shipped record blocks a brainstorm `write` into that spec. See [the record layout, settings and migration guide](./doc/configuration.md#telemetry). See [doc/configuration.md](./doc/configuration.md) for the settings each one reads. `phase_tracker`, `plan_check`, and `plan_tracker` are model-only (not callable from codemode scripts) because their state is rebuilt from transcript tool results, which nested calls do not persist.
+- **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 (expected when a loop gate set does not match its patterns; the scoped `Verification:` line answers it, not a full local run); a phase-tracker flow guard reminds on implement-phase commits missing spec/code review. Both engines use the tracker: waves manages plan tasks, while loop calls `plan_tracker refresh` to project ledger rows and preserve conformance tasks. Loop implement completes when every row is closed, then verify step 1 runs the ledger's gate set in the owning checkouts. 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, and that every test command carries a passing base-commit result; a pass stamps the plan and spec content hashes for implementation and returns a bounded task manifest; see the [manifest contract and size limit](./doc/configuration.md#phase-tracker). `telemetry` publishes YAML records on the `refs/telemetry/records` ref, outside the product diff: one sealed brainstorming run plus one session leg per settled `shape-ticket`, `gatekeep-pr` or `check-delivery` invocation. In-progress runs live in Git common-dir metadata; `gauntlet-telemetry-seal` publishes before landing without changing checkout HEAD or index. Publication failure warns without blocking ship; plain jj keeps local metadata and reports no Git remote. A fetched shipped record blocks a brainstorm `write` into that spec. See [the record layout, settings and migration guide](./doc/configuration.md#telemetry). See [doc/configuration.md](./doc/configuration.md) for the settings each one reads. `phase_tracker`, `plan_check`, and `plan_tracker` are model-only (not callable from codemode scripts) because their state is rebuilt from transcript tool results, which nested calls do not persist.
 
 pi-gauntlet is **opinionated**: it recommends this pipeline for non-trivial changes, but starts `brainstorming` only after explicit user consent. 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.
 
@@ -142,7 +142,7 @@ Run by a human against pi-cohort >= 7.1.0, before a pi-gauntlet release claims t
 ## Requirements
 
 - [pi-coding-agent](https://github.com/earendil-works/pi) >= 1.5.0 - supports model-only tracker exposure and sequential tracker execution, so updates persist as transcript tool results rather than nested calls.
-- [pi-cohort](https://github.com/jjuraszek/pi-cohort) >= 7.6.6 - required peer package, including binary-safe worktree patches; it also lets a persona with `subagent` in `tools:` start with inherited extensions ([pi-cohort #26](https://github.com/jjuraszek/pi-cohort/issues/26)), which multi-PR `gatekeep-pr` needs. Skills that dispatch agents (`requesting-code-review`, `subagent-driven-development`, `dispatching-parallel-agents`, `writing-plans`, `forge-skill`, `shape-ticket`, `roasting-the-spec`) call `subagent({})`, which pi-cohort provides. pi-gauntlet does not vendor the dispatch tool; without pi-cohort those skills have nothing to call. Gauntlet execution dispatches explicitly use `async: false`; do not enable pi-cohort's incompatible `forceTopLevelAsync` setting. See pi-cohort's [dispatch configuration](https://github.com/jjuraszek/pi-cohort/blob/main/doc/configuration.md) for that setting's owner and semantics. A wave of N >= 1 tasks dispatches its implementers and first spec reviews as one chain call. `subagent-driven-development` stops before dispatch on unsupported installs; there is no older-runtime fallback.
+- [pi-cohort](https://github.com/jjuraszek/pi-cohort) >= 7.6.7 - required peer package, including binary-safe worktree patches; it also lets a persona with `subagent` in `tools:` start with inherited extensions ([pi-cohort #26](https://github.com/jjuraszek/pi-cohort/issues/26)), which multi-PR `gatekeep-pr` needs. Skills that dispatch agents (`requesting-code-review`, `subagent-driven-development`, `dispatching-parallel-agents`, `writing-plans`, `forge-skill`, `shape-ticket`, `roasting-the-spec`) call `subagent({})`, which pi-cohort provides. pi-gauntlet does not vendor the dispatch tool; without pi-cohort those skills have nothing to call. Gauntlet execution dispatches explicitly use `async: false`; do not enable pi-cohort's incompatible `forceTopLevelAsync` setting. See pi-cohort's [dispatch configuration](https://github.com/jjuraszek/pi-cohort/blob/main/doc/configuration.md) for that setting's owner and semantics. A wave of N >= 1 tasks dispatches its implementers and first spec reviews as one chain call. `subagent-driven-development` stops before dispatch on unsupported installs; there is no older-runtime fallback.
 
 Both packages must be listed in your `.pi/settings.json#packages` array (pi adds them automatically when you `pi install`). pi-gauntlet and pi-cohort are versioned independently but release together whenever dispatch semantics change - pin compatible versions of both. At each pi-gauntlet release, set the pi-cohort peer minimum and README floor together to the newest released pi-cohort version; `/skill:release` checks the registry before proceeding.
 
@@ -170,7 +170,7 @@ Pin an exact release with `npm:pi-gauntlet@X.Y.Z`. See [doc/install-internals.md
 
 ## Performance digest
 
-`gauntlet-performance` digests telemetry records without judging them: `node <pi-gauntlet-package>/bin/gauntlet-performance.mjs [--dir <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, `disp/task`, `coord`, `fix_round_grants`, reopens, conformance loops, reviewer findings, council dispatches, and `big` - the count of parent calls whose cache write exceeded 50k tokens with their share of the run's parent cache-write tokens (`-` for records without `parent_calls`)), a `by version` block of p50/max over shipped, non-truncated runs, a `council` block grouped by member roster, and `skipped:` lines for files it could not use. Each council table shows member `total`, `unique`, `applied`, `uniq_appl`, `deferred`, `rejected` blocker/major/minor counts and `uniq_appl_nonminor/run`; `chair:` shows runs, average clusters and members reported, and retried runs. Roster flags (JSON `flags[].rule`: `low_unique_applied` - fewer than 0.2 unique-and-applied blocker/major findings per run; `high_rejection` - over 50% rejected while another member is below 25%) require five runs and print as `flag: <member> - <detail>`. Smaller groups print `not enough runs to assess (N of 5)`; absent council data prints `no council data in selected records`. JSON includes `council: [{ roster, runs, members, chairs, flags }]`. By default it refreshes the configured `gauntlet/telemetry` branch and reads under the current repository's own `<owner>/<name>/` prefix; `--dir <path>` reads a bare directory of YAML records without fetching. Network failure warns and serves the last fetched ref, or an empty corpus when none exists. The `tickets`, `prs` and `unattributed` tables include session-leg costs and split shared batch costs evenly; see [allocation and record fields](doc/configuration.md#telemetry). `--since` compares versions numerically. Exit 0 always except usage errors. `/skill:gauntlet-performance` is the reasoning layer on top.
+`gauntlet-performance` digests telemetry records without judging them: `node <pi-gauntlet-package>/bin/gauntlet-performance.mjs [--dir <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, `disp/task`, `coord`, `fix_round_grants`, reopens, conformance loops, reviewer findings, council dispatches, and `big` - the count of parent calls whose cache write exceeded 50k tokens with their share of the run's parent cache-write tokens (`-` for records without `parent_calls`)), a `by version` block of p50/max over shipped, non-truncated runs, a `council` block grouped by member roster, and `skipped:` lines for files it could not use. Each council table shows member `total`, `unique`, `applied`, `uniq_appl`, `deferred`, `rejected` blocker/major/minor counts and `uniq_appl_nonminor/run`; `chair:` shows runs, average clusters and members reported, and retried runs. Roster flags (JSON `flags[].rule`: `low_unique_applied` - fewer than 0.2 unique-and-applied blocker/major findings per run; `high_rejection` - over 50% rejected while another member is below 25%) require five runs and print as `flag: <member> - <detail>`. Smaller groups print `not enough runs to assess (N of 5)`; absent council data prints `no council data in selected records`. JSON includes `council: [{ roster, runs, members, chairs, flags }]`. By default it refreshes the `refs/telemetry/records` ref from the configured telemetry remote and reads under the current repository's own `<owner>/<name>/` prefix; `--dir <path>` reads a bare directory of YAML records without fetching. Network failure warns and serves the last fetched ref, or an empty corpus when none exists. The `tickets`, `prs` and `unattributed` tables include session-leg costs and split shared batch costs evenly; see [allocation and record fields](doc/configuration.md#telemetry). `--since` compares versions numerically. Exit 0 always except usage errors. `/skill:gauntlet-performance` is the reasoning layer on top.
 
 `disp/task` counts recorded implement-phase dispatch-result events divided by `plan.tasks - plan.skipped`; missing plan data, zero denominator or dropped events print `n/a`. `coord` is `yes` only for a non-empty sealed `legs:` list. Telemetry also records `verification_runs`: parent bash matcher hits from implement start through seal, not child checks or an assertion that verification passed. See [the telemetry reference](doc/configuration.md#telemetry) for the counter window and name-based reopen rules.
 

package/bin/gauntlet-performance.mjs

@@ -29,7 +29,7 @@ function resolveTelemetry(g) {
   const warnings = [];
   const enabled = t?.enabled !== false;
   if (t && Object.hasOwn(t, "dir")) {
-    warnings.push("piGauntlet.telemetry.dir is retired; records live on the gauntlet/telemetry branch - set piGauntlet.telemetry.remote to redirect them");
+    warnings.push("piGauntlet.telemetry.dir is retired; records live on the refs/telemetry/records ref - set piGauntlet.telemetry.remote to redirect them");
   }
   let buckets = DEFAULT_TELEMETRY_BUCKETS;
   if (t?.buckets !== void 0) {
@@ -128,7 +128,7 @@ var runBinary = (bin) => (args, cwd, timeoutMs = 1e4, options = {}) => {
 var gitRun = runBinary("git");
 
 // extensions/lib/telemetry-branch.ts
-var TELEMETRY_REF = "refs/heads/gauntlet/telemetry";
+var TELEMETRY_REF = "refs/telemetry/records";
 function telemetryRepo(root) {
   const result = gitRun(["config", "--get", "remote.origin.url"], root);
   const match = result.stdout.match(/^(?:https?:\/\/[^/]+\/|ssh:\/\/(?:[^@/]+@)?[^/]+\/|(?:[^@\s]+@)?[^:\s/]+:)(.+)$/);
@@ -147,7 +147,7 @@ function telemetryRepo(root) {
   const primary = worktrees.ok ? /^worktree ([^\0]+)/.exec(worktrees.stdout)?.[1] : void 0;
   return `local/${basename(primary ?? top)}`;
 }
-var trackingRef = (remote) => `refs/remotes/${remote === "origin" ? "origin" : "telemetry"}/gauntlet/telemetry`;
+var trackingRef = (remote) => `refs/telemetry/fetched/${remote === "origin" ? "origin" : "telemetry"}`;
 var fetchBranch = (root, remote) => gitRun(["fetch", "--no-tags", remote, `+${TELEMETRY_REF}:${trackingRef(remote)}`], root);
 function syncTelemetryBranch(root, records, remote = "origin") {
   const scratch = mkdtempSync(join2(tmpdir(), "gauntlet-telemetry-index-"));

package/bin/gauntlet-performance.test.mjs

@@ -585,7 +585,7 @@ test("shipped seal preserves verification runs and plan totals for performance",
     GIT_AUTHOR_NAME: "t", GIT_AUTHOR_EMAIL: "t@t", GIT_COMMITTER_NAME: "t", GIT_COMMITTER_EMAIL: "t@t",
   }, join(dirname(CLI), "gauntlet-telemetry-seal.mjs"));
   assert.equal(result.status, 0, result.stderr);
-  const sealed = parseYaml(git(["show", "gauntlet/telemetry:team/product/brainstorming/doc/specs/seal.yaml"]));
+  const sealed = parseYaml(git(["show", "refs/telemetry/records:team/product/brainstorming/doc/specs/seal.yaml"]));
   assert.equal(sealed.status, "shipped");
   assert.equal(sealed.derived.verification_runs, 2);
   assert.deepEqual(sealed.derived.plan, { tasks: 2, complete: 1, skipped: 1, failed: 0 });

package/bin/gauntlet-spec-index.mjs

@@ -42,7 +42,7 @@ function resolveTelemetry(g) {
   const warnings = [];
   const enabled = t?.enabled !== false;
   if (t && Object.hasOwn(t, "dir")) {
-    warnings.push("piGauntlet.telemetry.dir is retired; records live on the gauntlet/telemetry branch - set piGauntlet.telemetry.remote to redirect them");
+    warnings.push("piGauntlet.telemetry.dir is retired; records live on the refs/telemetry/records ref - set piGauntlet.telemetry.remote to redirect them");
   }
   let buckets = DEFAULT_TELEMETRY_BUCKETS;
   if (t?.buckets !== void 0) {
@@ -141,7 +141,7 @@ var runBinary = (bin) => (args, cwd, timeoutMs = 1e4, options = {}) => {
 var gitRun = runBinary("git");
 
 // extensions/lib/telemetry-branch.ts
-var TELEMETRY_REF = "refs/heads/gauntlet/telemetry";
+var TELEMETRY_REF = "refs/telemetry/records";
 function telemetryRepo(root) {
   const result = gitRun(["config", "--get", "remote.origin.url"], root);
   const match = result.stdout.match(/^(?:https?:\/\/[^/]+\/|ssh:\/\/(?:[^@/]+@)?[^/]+\/|(?:[^@\s]+@)?[^:\s/]+:)(.+)$/);
@@ -160,7 +160,7 @@ function telemetryRepo(root) {
   const primary = worktrees.ok ? /^worktree ([^\0]+)/.exec(worktrees.stdout)?.[1] : void 0;
   return `local/${basename(primary ?? top)}`;
 }
-var trackingRef = (remote) => `refs/remotes/${remote === "origin" ? "origin" : "telemetry"}/gauntlet/telemetry`;
+var trackingRef = (remote) => `refs/telemetry/fetched/${remote === "origin" ? "origin" : "telemetry"}`;
 var fetchBranch = (root, remote) => gitRun(["fetch", "--no-tags", remote, `+${TELEMETRY_REF}:${trackingRef(remote)}`], root);
 function syncTelemetryBranch(root, records, remote = "origin") {
   const scratch = mkdtempSync(join2(tmpdir(), "gauntlet-telemetry-index-"));

package/bin/gauntlet-spec-index.test.mjs

@@ -21,12 +21,12 @@ const git = (root, args, options = {}) => {
 };
 const telemetry = (root, path, text) => {
   const env = { GIT_INDEX_FILE: join(root, ".git/telemetry-index") };
-  git(root, ["read-tree", "gauntlet/telemetry"], { env });
+  git(root, ["read-tree", "refs/telemetry/records"], { env });
   const blob = git(root, ["hash-object", "-w", "--stdin"], { input: text });
   git(root, ["update-index", "--add", "--cacheinfo", "100644", blob, `team/product/brainstorming/${path}`], { env });
   const tree = git(root, ["write-tree"], { env });
-  const commit = git(root, ["commit-tree", tree, "-p", "gauntlet/telemetry", "-m", "telemetry fixture"]);
-  git(root, ["update-ref", "refs/heads/gauntlet/telemetry", commit]);
+  const commit = git(root, ["commit-tree", tree, "-p", "refs/telemetry/records", "-m", "telemetry fixture"]);
+  git(root, ["update-ref", "refs/telemetry/records", commit]);
 };
 const DRAFT = "# CONTEXT DRAFT - NOT A SPEC - fully replaced at spec-writing";
 const HEADER = ["score", "path", "service", "title", "status", "shipped_at", "state", "files", "snippet"];
@@ -59,7 +59,7 @@ const gitRepo = () => {
   git(root, ["config", `url.${root}.insteadOf`, "https://example.test/team/product.git"]);
   const tree = git(root, ["mktree"], { input: "" });
   const tip = git(root, ["commit-tree", tree, "-m", "empty telemetry fixture"]);
-  git(root, ["update-ref", "refs/heads/gauntlet/telemetry", tip]);
+  git(root, ["update-ref", "refs/telemetry/records", tip]);
   return root;
 };
 const commit = (root) => {

package/bin/gauntlet-telemetry-seal.mjs

@@ -1,8 +1,9 @@
 #!/usr/bin/env node
 
 // src/bins/gauntlet-telemetry-seal.mjs
-import { existsSync as existsSync3, readdirSync, readFileSync as readFileSync2, realpathSync, unlinkSync, writeFileSync } from "node:fs";
-import { homedir } from "node:os";
+import { existsSync as existsSync3, mkdtempSync as mkdtempSync2, readdirSync, readFileSync as readFileSync2, realpathSync, rmSync as rmSync2, unlinkSync, writeFileSync } from "node:fs";
+import { homedir, tmpdir as tmpdir2 } from "node:os";
+import { spawnSync as spawnSync2 } from "node:child_process";
 import { isAbsolute as isAbsolute2, join as join3, relative as relative2, resolve as resolve2 } from "node:path";
 import process2 from "node:process";
 
@@ -41,7 +42,7 @@ function resolveTelemetry(g) {
   const warnings = [];
   const enabled = t?.enabled !== false;
   if (t && Object.hasOwn(t, "dir")) {
-    warnings.push("piGauntlet.telemetry.dir is retired; records live on the gauntlet/telemetry branch - set piGauntlet.telemetry.remote to redirect them");
+    warnings.push("piGauntlet.telemetry.dir is retired; records live on the refs/telemetry/records ref - set piGauntlet.telemetry.remote to redirect them");
   }
   let buckets = DEFAULT_TELEMETRY_BUCKETS;
   if (t?.buckets !== void 0) {
@@ -275,7 +276,7 @@ function changedNames(vcs, base) {
 import { existsSync as existsSync2, mkdtempSync, readFileSync, rmSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { basename, join as join2 } from "node:path";
-var TELEMETRY_REF = "refs/heads/gauntlet/telemetry";
+var TELEMETRY_REF = "refs/telemetry/records";
 function trackerRefs(text) {
   const tokens = text.match(/https?:\/\/[^\s<>\])]+|[\w.-]+\/[\w.-]+#\d+|#\d+|\b[A-Z][A-Z0-9]*-\d+\b|\bgh-\d+\b/g) ?? [];
   return [...new Set(tokens.map((ref) => ref.replace(/[.,;]+$/, "")).filter((ref) => !ref.startsWith("http") || /\/(?:issues\/\d+|pull\/\d+|issue\/[A-Z][A-Z0-9]*-\d+)(?:\/[^\s]*)?$/.test(ref)).map((ref) => ref.startsWith("gh-") ? `#${ref.slice(3)}` : ref))];
@@ -302,8 +303,38 @@ function telemetryRepo(root) {
   const primary = worktrees.ok ? /^worktree ([^\0]+)/.exec(worktrees.stdout)?.[1] : void 0;
   return `local/${basename(primary ?? top)}`;
 }
-var trackingRef = (remote) => `refs/remotes/${remote === "origin" ? "origin" : "telemetry"}/gauntlet/telemetry`;
+var trackingRef = (remote) => `refs/telemetry/fetched/${remote === "origin" ? "origin" : "telemetry"}`;
 var fetchBranch = (root, remote) => gitRun(["fetch", "--no-tags", remote, `+${TELEMETRY_REF}:${trackingRef(remote)}`], root);
+function compareRecords(root, sources, destination) {
+  const snapshots = [...sources, destination].map((source) => {
+    const blobs = /* @__PURE__ */ new Map();
+    if (source.oid) {
+      const tree = gitRun(["ls-tree", "-r", "-z", source.oid], root, void 0, { raw: true });
+      if (!tree.ok) throw new Error(tree.stderr);
+      for (const entry of tree.stdout.split("\0").filter(Boolean)) {
+        const tab = entry.indexOf("	");
+        const [, type, oid] = entry.slice(0, tab).split(" ");
+        if (type === "blob") blobs.set(entry.slice(tab + 1), oid);
+      }
+    }
+    return { source, blobs };
+  });
+  const conflicts = [];
+  const missing = /* @__PURE__ */ new Map();
+  const dest = snapshots.at(-1);
+  for (let i = 0; i < sources.length; i++) {
+    const { source, blobs } = snapshots[i];
+    for (const [path, oid] of blobs) {
+      if (!dest.blobs.has(path) && !missing.has(path)) missing.set(path, source);
+      for (const other of snapshots.slice(i + 1)) {
+        if (other.blobs.has(path) && other.blobs.get(path) !== oid) {
+          conflicts.push({ path, a: source.label, b: other.source.label });
+        }
+      }
+    }
+  }
+  return { conflicts, missing: [...missing].map(([path, source]) => ({ path, source })) };
+}
 function syncTelemetryBranch(root, records, remote = "origin") {
   const scratch = mkdtempSync(join2(tmpdir(), "gauntlet-telemetry-index-"));
   const env = { GIT_INDEX_FILE: join2(scratch, "index") };
@@ -509,7 +540,7 @@ var fail = (code, message) => {
   process2.stderr.write(message + "\n");
   process2.exit(code);
 };
-var usage = () => fail(1, "usage: gauntlet-telemetry-seal --worktree <abs path> --option <pr|squash> --base <ref> [--spec <spec path inside the checkout>]\n       gauntlet-telemetry-seal [--worktree <abs path>] --migrate [<telemetry dir>]");
+var usage = () => fail(1, "usage: gauntlet-telemetry-seal --worktree <abs path> --option <pr|squash> --base <ref> [--spec <spec path inside the checkout>]\n       gauntlet-telemetry-seal [--worktree <abs path>] --migrate [<telemetry dir>]\n       gauntlet-telemetry-seal [--worktree <abs path>] <--migrate-branch|--retire-branch>");
 function parseArgs(argv) {
   const opts = { worktree: void 0, option: void 0, base: void 0, spec: void 0, legs: [] };
   for (let i = 0; i < argv.length; i++) {
@@ -520,6 +551,8 @@ function parseArgs(argv) {
       opts[key] = argv[++i];
     };
     if (a === "--migrate") opts.migrate = value !== void 0 && !value.startsWith("--") ? argv[++i] : ".pi/gauntlet/telemetry";
+    else if (a === "--migrate-branch") opts.migrateBranch = true;
+    else if (a === "--retire-branch") opts.retireBranch = true;
     else if (a === "--worktree") takes("worktree");
     else if (a === "--option") takes("option");
     else if (a === "--base") takes("base");
@@ -534,7 +567,9 @@ function parseArgs(argv) {
       opts.legs.push(leg);
     } else usage();
   }
-  if (opts.migrate !== void 0) {
+  const modes = [opts.migrate !== void 0, opts.migrateBranch, opts.retireBranch].filter(Boolean).length;
+  if (modes > 1) usage();
+  if (modes) {
     opts.worktree ??= process2.cwd();
     if (opts.option || opts.base || opts.spec || opts.legs.length) usage();
   } else if (!opts.base || !OPTIONS.has(opts.option)) usage();
@@ -585,6 +620,74 @@ function migrate(root, dir, repo, remote) {
   if (!result.ok) return console.log(`telemetry: not pushed (${result.reason})`);
   console.log(`migrated ${writes.size} records from ${dir}`);
 }
+var LEGACY_REF = "refs/heads/gauntlet/telemetry";
+function branchMigration(root, remote = "origin", retire) {
+  const required = (args, options) => {
+    const result = gitRun(args, root, void 0, options);
+    if (!result.ok) throw new Error(result.stderr || `git ${args[0]} failed`);
+    return result.stdout;
+  };
+  const discover = (ref, tracking) => {
+    const found = gitRun(["ls-remote", "--exit-code", remote, ref], root);
+    if (found.code === 2) return void 0;
+    if (!found.ok) throw new Error(found.stderr || "git ls-remote failed");
+    required(["fetch", "--no-tags", remote, tracking ? `+${ref}:${tracking}` : ref]);
+    return required(["rev-parse", "--verify", tracking ?? "FETCH_HEAD"]);
+  };
+  const oldRemote = discover(LEGACY_REF);
+  if (retire && !oldRemote) return console.log("nothing to retire");
+  const sources = oldRemote ? [{ label: `${remote}/${LEGACY_REF}`, oid: oldRemote }] : [];
+  const local = gitRun(["show-ref", "--verify", "--quiet", LEGACY_REF], root);
+  if (local.ok) sources.push({ label: LEGACY_REF, oid: required(["rev-parse", "--verify", LEGACY_REF]) });
+  else if (local.code !== 1) throw new Error(local.stderr || "git show-ref failed");
+  if (!sources.length) return console.log("nothing to migrate");
+  let destOid = discover(TELEMETRY_REF, trackingRef(remote));
+  let compared = compareRecords(root, sources, { label: `${remote}/${TELEMETRY_REF}`, oid: destOid ?? null });
+  if (compared.conflicts.length) throw new Error(compared.conflicts.map(({ path, a, b }) => `conflict: ${path} differs between ${a} and ${b}`).join("\n"));
+  if (retire && compared.missing.length) throw new Error(compared.missing.map(({ path }) => `not carried: ${path}`).join("\n"));
+  const push = (args, config = []) => {
+    const result = spawnSync2("git", [...config, "push", ...args], { cwd: root, encoding: "utf8", timeout: 3e4 });
+    if (result.status !== 0) {
+      const stderr = result.stderr?.trim() || result.error?.message || "git push failed";
+      const retry = retire ? "gauntlet/telemetry moved since verification - re-run --migrate-branch then --retire-branch" : "destination changed since comparison - re-run --migrate-branch";
+      throw new Error(`${stderr}
+${retry}`);
+    }
+  };
+  if (retire) {
+    const remotes = required(["remote"]).split("\n");
+    const pushRemote = remotes.includes(remote) ? required(["remote", "get-url", "--push", remote]) : remote;
+    let alias = `gauntlet-retire-${process2.pid}`;
+    while (remotes.includes(alias)) alias += "-";
+    push([`--force-with-lease=${LEGACY_REF}:${oldRemote}`, alias, `:${LEGACY_REF}`], ["-c", `remote.${alias}.url=${pushRemote}`]);
+    console.log(`retired: gauntlet/telemetry on ${remote}`);
+    console.log(`if git show-ref --verify --quiet ${LEGACY_REF}; then git branch -D gauntlet/telemetry; fi`);
+    return console.log(`git update-ref -d refs/remotes/${trackingRef(remote).split("/").at(-1)}/gauntlet/telemetry`);
+  }
+  if (!destOid && oldRemote) {
+    push([`--force-with-lease=${TELEMETRY_REF}:`, remote, `${oldRemote}:${TELEMETRY_REF}`]);
+    destOid = oldRemote;
+    compared = compareRecords(root, sources, { label: `${remote}/${TELEMETRY_REF}`, oid: destOid });
+  }
+  if (!compared.missing.length) return console.log("carried: 0 records");
+  const scratch = mkdtempSync2(join3(tmpdir2(), "gauntlet-ref-migration-"));
+  try {
+    const env = { GIT_INDEX_FILE: join3(scratch, "index") };
+    required(destOid ? ["read-tree", destOid] : ["read-tree", "--empty"], { env });
+    for (const { path, source } of compared.missing) {
+      const entry = required(["ls-tree", "-z", source.oid, "--", path], { raw: true });
+      const [mode, , blob] = entry.slice(0, entry.indexOf("	")).split(" ");
+      required(["update-index", "--add", "--cacheinfo", `${mode},${blob},${path}`], { env });
+    }
+    const tree = required(["write-tree"], { env });
+    const author = { ...env, GIT_AUTHOR_NAME: "gauntlet", GIT_AUTHOR_EMAIL: "gauntlet@local", GIT_COMMITTER_NAME: "gauntlet", GIT_COMMITTER_EMAIL: "gauntlet@local" };
+    const commit = required(["-c", "commit.gpgsign=false", "commit-tree", tree, ...destOid ? ["-p", destOid] : [], "-m", "Carry legacy gauntlet telemetry"], { env: author });
+    push([`--force-with-lease=${TELEMETRY_REF}:${destOid ?? ""}`, remote, `${commit}:${TELEMETRY_REF}`]);
+    console.log(`carried: ${compared.missing.length} records from ${[...new Set(compared.missing.map(({ source }) => source.label))].join(", ")}`);
+  } finally {
+    rmSync2(scratch, { recursive: true, force: true });
+  }
+}
 var isoNow = () => (/* @__PURE__ */ new Date()).toISOString().replace(/\.\d{3}Z$/, "Z");
 function runTickets(vcs, record, base) {
   const log = gitRun(["log", "--format=%B", `${base}..HEAD`], vcs.root);
@@ -598,7 +701,7 @@ var normalized = (legs) => [...new Set(legs.map((leg) => JSON.stringify([leg.rep
 var sameLegs = (record, legs) => JSON.stringify(normalized(record.legs ?? [])) === JSON.stringify(normalized(legs));
 function branchBlob(root, path, remote) {
   const local = gitRun(["rev-parse", "--verify", TELEMETRY_REF], root);
-  const tracking = `refs/remotes/${!remote || remote === "origin" ? "origin" : "telemetry"}/gauntlet/telemetry`;
+  const tracking = trackingRef(remote ?? "origin");
   const fetched = local.ok && gitRun(["merge-base", "--is-ancestor", TELEMETRY_REF, tracking], root).ok;
   const ref = !local.ok || fetched ? tracking : TELEMETRY_REF;
   const blob = gitRun(["show", `${ref}:${path}`], root, void 0, { raw: true });
@@ -660,6 +763,13 @@ async function main() {
 `);
   if (!telemetry.enabled) return console.log("telemetry disabled");
   if (vcs.kind === "jj") return console.log("telemetry: not pushed (jj workspace: no git remote)");
+  if (opts.migrateBranch || opts.retireBranch) {
+    try {
+      return branchMigration(root, telemetry.remote, opts.retireBranch);
+    } catch (error) {
+      fail(1, error.message);
+    }
+  }
   const dir = DEFAULT_TELEMETRY_DIR;
   if (opts.migrate === void 0 && !validateBase(vcs, opts.base)) fail(1, `no base ref ${opts.base}`);
   const store = telemetryDir(root);

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

@@ -11,7 +11,7 @@ import { isolatedGitEnv } from "../extensions/test-support/git-env.mjs";
 const CLI = join(dirname(fileURLToPath(import.meta.url)), "gauntlet-telemetry-seal.mjs");
 const SPEC = "doc/specs/x.md";
 const REC = ".git/gauntlet/telemetry/doc/specs/x.yaml";
-const REF = "refs/heads/gauntlet/telemetry";
+const REF = "refs/telemetry/records";
 const BLOB = "team/product/brainstorming/doc/specs/x.yaml";
 const RECORD = `schema: 1
 spec: doc/specs/x.md
@@ -168,7 +168,7 @@ fi
   assert.equal(result.status, 0, result.stderr);
   assert.match(result.stderr, /telemetry: not pushed.*(?:EISDIR|EPERM)/);
   assert.equal(record(root).status, "shipped", "the published record survives failed cleanup");
-  assert.equal(git(root, ["rev-parse", REF]), git(root, ["rev-parse", "refs/remotes/origin/gauntlet/telemetry"]));
+  assert.equal(git(root, ["ls-remote", "origin", REF]), `${git(root, ["rev-parse", REF])}\t${REF}`);
 });
 
 test("shipped CLI rejects malformed leg values before sealing", () => {

package/extensions/lib/gauntlet-settings.test.ts

@@ -284,7 +284,7 @@ test("telemetry: retired dir setting is ignored with one migration warning", ()
   ]) {
     const r = resolveTelemetry(mergeGauntlet(undefined, { telemetry: { dir } }));
     assert.equal("dir" in r, false);
-    assert.equal(r.warning, "piGauntlet.telemetry.dir is retired; records live on the gauntlet/telemetry branch - set piGauntlet.telemetry.remote to redirect them");
+    assert.equal(r.warning, "piGauntlet.telemetry.dir is retired; records live on the refs/telemetry/records ref - set piGauntlet.telemetry.remote to redirect them");
   }
 });
 
@@ -307,7 +307,7 @@ test("telemetry: malformed buckets -> default + warning", () => {
 
 test("telemetry: retired dir and invalid buckets each warn once", () => {
   const r = resolveTelemetry(mergeGauntlet(undefined, { telemetry: { dir: 1, buckets: 2 } }));
-  assert.equal(r.warning, "piGauntlet.telemetry.dir is retired; records live on the gauntlet/telemetry branch - set piGauntlet.telemetry.remote to redirect them; telemetry.buckets is not an object of non-empty glob arrays; using the defaults");
+  assert.equal(r.warning, "piGauntlet.telemetry.dir is retired; records live on the refs/telemetry/records ref - set piGauntlet.telemetry.remote to redirect them; telemetry.buckets is not an object of non-empty glob arrays; using the defaults");
 });
 
 test("DEFAULT_TEST_COMMANDS + buildTestCmdRegex match the documented entrypoints", () => {

package/extensions/lib/gauntlet-settings.ts

@@ -240,7 +240,7 @@ export function resolveTelemetry(g: PiGauntlet): TelemetryResolved {
   const warnings: string[] = [];
   const enabled = t?.enabled !== false;
   if (t && Object.hasOwn(t, "dir")) {
-    warnings.push("piGauntlet.telemetry.dir is retired; records live on the gauntlet/telemetry branch - set piGauntlet.telemetry.remote to redirect them");
+    warnings.push("piGauntlet.telemetry.dir is retired; records live on the refs/telemetry/records ref - set piGauntlet.telemetry.remote to redirect them");
   }
 
   let buckets = DEFAULT_TELEMETRY_BUCKETS;

package/extensions/lib/telemetry-branch.test.ts

@@ -68,7 +68,34 @@ test("failed telemetry ref commit reports committed: false and preserves the fea
   assert.match(result.reason, /rejected|reference transaction/);
   assert.equal(f.git("rev-parse", "HEAD"), before);
   assert.deepEqual(readFileSync(join(f.root, ".git/index")), index);
-  assert.equal(f.git("for-each-ref", "refs/heads/gauntlet/telemetry"), "");
+  assert.equal(f.git("for-each-ref", "refs/telemetry/records"), "");
+});
+
+test("record comparison reports missing paths and every conflicting snapshot pair", () => {
+  const f = fixture();
+  const snapshots = ["remote", "local", "destination"].map(label => {
+    writeFileSync(join(f.root, "record.yaml"), label + "\n");
+    f.git("add", "."); f.git("commit", "-m", label);
+    return { label, oid: f.git("rev-parse", "HEAD") };
+  });
+  const [remote, local, destination] = snapshots;
+  const empty = { label: "empty", oid: null };
+  for (const [sources, dest, conflicts, missing] of [
+    [[remote], remote, [], []],
+    [[remote], empty, [], [{ path: "record.yaml", source: remote }]],
+    [[remote], destination, [{ path: "record.yaml", a: "remote", b: "destination" }], []],
+    [[remote, local], empty, [{ path: "record.yaml", a: "remote", b: "local" }], [{ path: "record.yaml", source: remote }]],
+    [[remote, local], destination, [
+      { path: "record.yaml", a: "remote", b: "local" },
+      { path: "record.yaml", a: "remote", b: "destination" },
+      { path: "record.yaml", a: "local", b: "destination" },
+    ], []],
+  ]) {
+    const result = JSON.parse(f.run(process.execPath, ["--input-type=module", "--eval",
+      `import { compareRecords } from ${JSON.stringify(library)}; console.log(JSON.stringify(compareRecords(process.cwd(), ${JSON.stringify(sources)}, ${JSON.stringify(dest)})));`,
+    ]));
+    assert.deepEqual(result, { conflicts, missing });
+  }
 });
 
 test("origin-less identity uses repo from the first-found overrides Issue tracker section", () => {

package/extensions/lib/telemetry-branch.ts

@@ -4,7 +4,7 @@ import { basename, join } from "node:path";
 import { checkoutOfSync } from "./checkout.ts";
 import { gitRun } from "./vcs.ts";
 
-export const TELEMETRY_REF = "refs/heads/gauntlet/telemetry";
+export const TELEMETRY_REF = "refs/telemetry/records";
 
 export function trackerRefs(text: string): string[] {
   const tokens = text.match(/https?:\/\/[^\s<>\])]+|[\w.-]+\/[\w.-]+#\d+|#\d+|\b[A-Z][A-Z0-9]*-\d+\b|\bgh-\d+\b/g) ?? [];
@@ -39,9 +39,45 @@ export function telemetryRepo(root: string): string {
   return `local/${basename(primary ?? top)}`;
 }
 
-const trackingRef = (remote: string) => `refs/remotes/${remote === "origin" ? "origin" : "telemetry"}/gauntlet/telemetry`;
+export const trackingRef = (remote: string) => `refs/telemetry/fetched/${remote === "origin" ? "origin" : "telemetry"}`;
 const fetchBranch = (root: string, remote: string) => gitRun(["fetch", "--no-tags", remote, `+${TELEMETRY_REF}:${trackingRef(remote)}`], root);
 
+type RecordSnapshot = { label: string; oid: string | null };
+
+export function compareRecords(root: string, sources: RecordSnapshot[], destination: RecordSnapshot): {
+  conflicts: { path: string; a: string; b: string }[];
+  missing: { path: string; source: RecordSnapshot }[];
+} {
+  const snapshots = [...sources, destination].map(source => {
+    const blobs = new Map<string, string>();
+    if (source.oid) {
+      const tree = gitRun(["ls-tree", "-r", "-z", source.oid], root, undefined, { raw: true });
+      if (!tree.ok) throw new Error(tree.stderr);
+      for (const entry of tree.stdout.split("\0").filter(Boolean)) {
+        const tab = entry.indexOf("\t");
+        const [, type, oid] = entry.slice(0, tab).split(" ");
+        if (type === "blob") blobs.set(entry.slice(tab + 1), oid);
+      }
+    }
+    return { source, blobs };
+  });
+  const conflicts: { path: string; a: string; b: string }[] = [];
+  const missing = new Map<string, RecordSnapshot>();
+  const dest = snapshots.at(-1)!;
+  for (let i = 0; i < sources.length; i++) {
+    const { source, blobs } = snapshots[i];
+    for (const [path, oid] of blobs) {
+      if (!dest.blobs.has(path) && !missing.has(path)) missing.set(path, source);
+      for (const other of snapshots.slice(i + 1)) {
+        if (other.blobs.has(path) && other.blobs.get(path) !== oid) {
+          conflicts.push({ path, a: source.label, b: other.source.label });
+        }
+      }
+    }
+  }
+  return { conflicts, missing: [...missing].map(([path, source]) => ({ path, source })) };
+}
+
 export function syncTelemetryBranch(root: string, records: ReadonlyMap<string, string>, remote = "origin"): { ok: boolean; committed: boolean; pushed: boolean; reason?: string; warning?: string } {
   const scratch = mkdtempSync(join(tmpdir(), "gauntlet-telemetry-index-"));
   const env = { GIT_INDEX_FILE: join(scratch, "index") };

package/extensions/telemetry-leg.test.ts

@@ -16,7 +16,7 @@ Object.assign(process.env, gitEnv);
 const { default: registerTelemetry, realDeps } = await import("./telemetry.ts");
 const { registerLegTelemetry } = await import("./lib/telemetry-leg.ts");
 
-const ref = "refs/heads/gauntlet/telemetry";
+const ref = "refs/telemetry/records";
 const originalDepth = process.env.PI_SUBAGENT_DEPTH;
 process.env.PI_SUBAGENT_DEPTH = "0";
 after(() => {
@@ -99,6 +99,7 @@ for (const [skill, outcome, activation, empty] of [
   test(`${skill} ${outcome}${empty ? " with no items" : ""} seals one session leg only after the final settlement and follow-on work`, async () => {
     const marker = outcome === "stopped" ? "stuck" : "done";
     const h = harness(skill);
+    const localHeads = h.git(h.root, "show-ref", "--heads");
     await h.emit("session_start");
     // Terminal-looking text outside a selected skill is not a leg.
     await h.say(`gauntlet: done ${outcome}\n#42: ${outcome}`);
@@ -147,5 +148,8 @@ for (const [skill, outcome, activation, empty] of [
     assert.deepEqual(readFileSync(join(h.root, ".git/index")), h.index);
     assert.equal(readFileSync(join(h.root, "file.txt"), "utf8"), "unstaged user change\n");
     assert.equal(h.git(h.root, "rev-parse", ref), tip);
+    assert.equal(h.git(h.root, "show-ref", "--heads"), localHeads, "settlement must not create a local branch");
+    assert.equal(h.git(h.root, "ls-remote", "--heads", "origin"), "", "settlement must not create a remote branch");
+    assert.equal(h.git(h.root, "ls-remote", "origin", "refs/telemetry/*"), `${tip}\t${ref}`);
   });
 }

package/extensions/telemetry.test.ts

@@ -981,7 +981,7 @@
     h2.fetchedRecords.set("test/repo/brainstorming/doc/specs/a.yaml", before);
     await h2.phaseResult("start", P({ brainstorm: "in_progress" }));
     const [blocked] = await h2.emit("tool_call", { toolName: "write", toolCallId: "w", input: { path: "doc/specs/a.md" } });
-    assert.deepEqual(blocked, { block: true, reason: guardReason("doc/specs/a.md", rec.shipped_at, "gauntlet/telemetry") });
+    assert.deepEqual(blocked, { block: true, reason: guardReason("doc/specs/a.md", rec.shipped_at, "refs/telemetry/records") });
     assert.equal(readFileSync(h.recordPath(), "utf8"), before);
     assert.equal(h.readRecord().derived.spec_edits_after_ship, 0);
   });
@@ -1313,7 +1313,7 @@
     h2.fetchedRecords.set("test/repo/brainstorming/doc/specs/a.yaml", before);
     await h2.phaseResult("start", P({ brainstorm: "in_progress" }));
     const [blocked] = await h2.emit("tool_call", { toolName: "write", toolCallId: "w1", input: { path: "doc/specs/a.md", content: "# again" } });
-    assert.deepEqual(blocked, { block: true, reason: guardReason("doc/specs/a.md", h.readRecord().shipped_at!, "gauntlet/telemetry") });
+    assert.deepEqual(blocked, { block: true, reason: guardReason("doc/specs/a.md", h.readRecord().shipped_at!, "refs/telemetry/records") });
     assert.equal(readFileSync(h.recordPath(), "utf8"), before, "shipped record byte-identical");
     const [editPass] = await h2.emit("tool_call", { toolName: "edit", toolCallId: "e1", input: { path: "doc/specs/a.md", edits: [] } });
     assert.equal(editPass, undefined);

package/extensions/telemetry.ts

@@ -789,7 +789,7 @@
           const loc = await locate(ctx, rawPath);
           if (loc?.via === "git" && isSpecPath(loc.rel, snap.specDirs)) {
             const shippedAt = shippedRecords(loc.toplevel, snap).get(loc.rel);
-            if (shippedAt) return { block: true, reason: guardReason(loc.rel, shippedAt, "gauntlet/telemetry") };
+            if (shippedAt) return { block: true, reason: guardReason(loc.rel, shippedAt, "refs/telemetry/records") };
           }
         }
         return undefined;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-gauntlet",
-  "version": "8.4.2",
+  "version": "8.4.3",
   "description": "Opinionated, gated workflow skills, subagent personas, and runtime extensions for the pi coding agent.",
   "author": "Jacek Juraszek",
   "type": "module",
@@ -62,7 +62,7 @@
     "test": "node scripts/ci.mjs"
   },
   "peerDependencies": {
-    "pi-cohort": ">=7.6.6"
+    "pi-cohort": ">=7.6.7"
   },
   "dependencies": {
     "yaml": "^2.9.0"

package/skills/brainstorming/SKILL.md

@@ -69,7 +69,7 @@ The spec is the first commit in a dedicated worktree, never a separate commit on
 
 Read [reference/legs.md](reference/legs.md) and settle membership before creation. Invoke `/skill:using-git-worktrees` for each member with explicit `$ROOT` = its primary and `$BRANCH` = the shared branch; carry every `Worktree ready at <full-path>` value, home first. Root the home spec at `<home worktree>/<home spec dir>/<filename>.md`; root each dispatch and `git -C` in its owning leg's worktree. Keep the process cwd unchanged. Gather each leg's rules and record portable contracts and companion artifacts using that reference; a one-member run adds only its one-block `## Legs` section.
 
-Keep spec, plan, and implementation in this worktree. Ship the spec and implementation; strip only the plan. Let `/skill:finishing-a-development-branch` seal and publish the telemetry record to the orphan `gauntlet/telemetry` branch before landing; keep recorder state in Git common-dir metadata, outside the working tree. In a plain jj workspace, retain local metadata and report that publication is unavailable. Use no worktree for explicit trivial one-off edits outside this flow.
+Keep spec, plan, and implementation in this worktree. Ship the spec and implementation; strip only the plan. Let `/skill:finishing-a-development-branch` seal and publish the telemetry record to the `refs/telemetry/records` ref before landing; keep recorder state in Git common-dir metadata, outside the working tree. In a plain jj workspace, retain local metadata and report that publication is unavailable. Use no worktree for explicit trivial one-off edits outside this flow.
 
 ## The Process
 

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

@@ -226,7 +226,7 @@ Rows 1-2 run the Option 1/2 blocks; row 3 runs the Keep block and row 4 the Disc
 
 #### Strip the plan, seal the record (Options 1-3)
 
-Run this on the feature branch before any landing path. Ship the spec and implementation; strip only the plan. Let the seal publish the telemetry record to the orphan `gauntlet/telemetry` branch without changing the product checkout, index or HEAD. Keep in-progress records in Git common-dir metadata, outside the working tree. Resolve `<bin>` as `<directory of this skill's SKILL.md>/../../bin` from the skill's `<location>` in the system prompt.
+Run this on the feature branch before any landing path. Ship the spec and implementation; strip only the plan. Let the seal publish the telemetry record to the `refs/telemetry/records` ref without changing the product checkout, index or HEAD. Keep in-progress records in Git common-dir metadata, outside the working tree. Resolve `<bin>` as `<directory of this skill's SKILL.md>/../../bin` from the skill's `<location>` in the system prompt.
 
 Read the existing artifact's path-only `**Spec:**` header (repo-relative, backticks stripped) before removal; pass that value as `--spec`, including for a line-1 ledger. Resolve the spec dirs with `gauntlet_setting({ key: "flowGuards" })` and use their sibling `plans` dirs for plan paths. Enumerate both PLAN_PATH candidates: the task plan paired by basename and `<sibling plans dir>/<spec stem>-ledger.md`. Preserve the spec and telemetry.
 
@@ -242,7 +242,7 @@ elif [ -f "$WORKTREE/$PLAN_PATH" ] && jj -R "$WORKTREE" root >/dev/null 2>&1; th
 fi
 done
 
-# Seal the telemetry record: stamp shipped, compute the diff, publish to gauntlet/telemetry.
+# Seal the telemetry record: stamp shipped, compute the diff, publish to refs/telemetry/records.
 # The bin reports publication unavailable in a plain jj workspace and keeps local metadata.
 # --option is pr for Options 1-2 and squash for Option 3; --spec is the artifact header's **Spec:** value (omit when no artifact is known).
 node <bin>/gauntlet-telemetry-seal.mjs --worktree "$WORKTREE" --option <pr|squash> --base <base-branch> --spec <spec path>
@@ -346,7 +346,7 @@ git -C "$PRIMARY" commit -m "<imperative summary> (ref <ticket-id>)"
 (cd "$PRIMARY" && <the Step 1 set>)
 ```
 
-Keep only the spec and implementation in the staged squash tree; the stripped plan stays in feature history and the sealed telemetry record belongs to `gauntlet/telemetry`.
+Keep only the spec and implementation in the staged squash tree; the stripped plan stays in feature history and the sealed telemetry record belongs to `refs/telemetry/records`.
 
 The post-squash re-verify is not optional - `git merge --squash` can surface conflict-resolution mistakes the worktree-side run couldn't catch. For a ledger, run the per-pair post-squash recipe in [verification-set.md](reference/verification-set.md) instead of the non-ledger subshell above.
 
@@ -450,10 +450,10 @@ A host-owned worktree (Step 6: no `home:` match, or the legacy "Otherwise") keep
 
 **Skipping the strip-and-seal block in Options 1-3 (any path that lands on base)**
 - **Problem:** Skipping the block ships an ephemeral plan or skips publication of the record the spec index reads.
-- **Fix:** Run the block on `$WORKTREE` before the squash or push. Preserve the spec on `<base-branch>` and the telemetry record on `gauntlet/telemetry`; retain the plan only in feature history.
+- **Fix:** Run the block on `$WORKTREE` before the squash or push. Preserve the spec on `<base-branch>` and the telemetry record on `refs/telemetry/records`; retain the plan only in feature history.
 
 **Treating telemetry as a checkout deliverable**
-- **Problem:** Staging a recorder file pollutes the product diff and bypasses branch publication.
+- **Problem:** Staging a recorder file pollutes the product diff and bypasses ref publication.
 - **Fix:** Let the seal own publication from common-dir metadata; stage no telemetry record in the product checkout.
 
 ## Completion

package/skills/gauntlet-resume/reference/seed.md

@@ -13,7 +13,7 @@ Before starting the seed sequence, read the seed's header. A `**Home:**` header
    stop: `not tracked: <seed> - commit it first`. Line 1 of `<seed>` equal to
    `# CONTEXT DRAFT - NOT A SPEC - fully replaced at spec-writing` -> stop:
    `context draft, not a spec: <seed> - finish brainstorming`.
-3. **Not shipped.** Resolve `piGauntlet.telemetry` from preset and primary project settings; `enabled: false` skips this check. Run `git -C <primary> rev-parse --git-common-dir`; resolve a relative result against `<primary>` and read `<git common dir>/gauntlet/telemetry/<rel with .md -> .yaml>`. When git resolution fails and `jj root` in `<primary>` succeeds, read `<jj root>/.jj/gauntlet/telemetry/<rel with .md -> .yaml>` instead. When the local record is absent, fetch `gauntlet/telemetry` from `telemetry.remote` (default `origin`) and read `<owner>/<repo>/brainstorming/<rel with .md -> .yaml>` from the fetched ref, using the last fetched ref on fetch failure. Degrade to the local-only check when no fetched ref is available, including jj-only workspaces. A valued `shipped_at:` or `abandoned_at:` stops: `spec already shipped at <ts> - write a superseding spec`. No record or `in_progress`: continue; let the extension bind on `plan_check` pass.
+3. **Not shipped.** Resolve `piGauntlet.telemetry` from preset and primary project settings; `enabled: false` skips this check. Run `git -C <primary> rev-parse --git-common-dir`; resolve a relative result against `<primary>` and read `<git common dir>/gauntlet/telemetry/<rel with .md -> .yaml>`. When git resolution fails and `jj root` in `<primary>` succeeds, read `<jj root>/.jj/gauntlet/telemetry/<rel with .md -> .yaml>` instead. When the local record is absent, fetch `refs/telemetry/records` from `telemetry.remote` (default `origin`) and read `<owner>/<repo>/brainstorming/<rel with .md -> .yaml>` from the fetched ref, using the last fetched ref on fetch failure. Degrade to the local-only check when no fetched ref is available, including jj-only workspaces. A valued `shipped_at:` or `abandoned_at:` stops: `spec already shipped at <ts> - write a superseding spec`. No record or `in_progress`: continue; let the extension bind on `plan_check` pass.
 4. **Name.** `<name>` = basename of `<rel>` minus `.md`, minus a leading `YYYY-MM-DD-`:
    `2026-09-17-gh-31-gauntlet-resume.md` -> `gh-31-gauntlet-resume`. Same shape as
    brainstorming's Filename Convention slug; wrappers receive it as `<name>`.