pi-gauntlet 5.7.0 → 5.8.1

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## v5.8.1 - 2026-09-17
+
+- chase-bug hotfix: the implementer proves its worktree binding first, addresses every mutating git command with `git -C`, runs with a fresh context, and the parent aborts non-destructively on any primary-checkout drift after each implementer return; `ci.mjs` asserts the guard text ([#36](https://github.com/jjuraszek/pi-gauntlet/issues/36))
+- `gauntlet-resume`: same-repository worktrees resume from a pi session launched in the primary checkout; cross-repository targets still stop, and reconstruction addresses the resolved worktree by path.
+
+## v5.8.0 - 2026-09-17
+
+- New extension `telemetry`: records one committed YAML record per gauntlet run at `.pi/gauntlet/telemetry/<spec path>.yaml` (phase timing, model/thinking snapshots, per-persona dispatches and tokens, reviewer findings, gate and fix-round counters, plan totals, last test result, diff buckets and modified files at ship), keyed by spec path and continued across sessions; pathspec-commits the record at checkpoints; reconciles a failed ship command; freezes after squash/PR/discard. During brainstorm a `write` into a spec whose record is shipped is blocked (`edit` passes). Settings `piGauntlet.telemetry.{enabled,dir,buckets}`. (#33)
+- `yaml` is the package's first runtime dependency; CI and local checkouts run `npm install` before the test suite. `verify-before-ship` shares its default test-command list with the resolver module (no behaviour change).
+
 ## v5.7.0 - 2026-09-17
 
 - `gauntlet-resume` (new, human-only, `disable-model-invocation: true`): the sole re-entry point into an interrupted gauntlet flow from a fresh session. Input is a pi-cohort `/handoff` brief (file or pasted; grammar in `skills/gauntlet-resume/reference/brief-contract.md`) or a bare worktree that already holds a spec (`reference/reconstruction.md`). Restores `phase_tracker` / `plan_tracker` state via `start brainstorm` + `skip` with `resume:` reasons, re-runs `plan_check` before implement-or-later, stops a ship-stage brief at verify, never creates a worktree, never infers approval from artifacts. Free-form prompts redirect to `/skill:brainstorming`.

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.
-- **3 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. 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) 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.
 
@@ -120,8 +120,9 @@ For local development against a checkout instead of npm:
 
 ```bash
 git clone git@github.com:jjuraszek/pi-gauntlet.git ~/repos/pi-gauntlet
-cd ~/path/to/your/repo && pi install -l ~/repos/pi-gauntlet
-cd ~/repos/pi-gauntlet && npm run link-agents   # local-path installs skip npm install; run this once
+cd ~/repos/pi-gauntlet && npm install      # installs the yaml dependency and links the agents
+cd ~/path/to/your/repo
+pi install -l ~/repos/pi-gauntlet
 ```
 
 ## Use from Claude Code

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

@@ -8,11 +8,16 @@ import {
   mainLoopModel,
   resolveFlowGuards,
   resolveVerifyBeforeShip,
+  resolveTelemetry,
+  DEFAULT_TELEMETRY_DIR,
+  DEFAULT_TELEMETRY_BUCKETS,
+  DEFAULT_TEST_COMMANDS,
+  buildTestCmdRegex,
   settingsErrorWarning,
   type PiGauntlet,
 } from "./gauntlet-settings.ts";
 
-const DEFAULT_TEST_COMMANDS = ["make ci", "pytest"];
+const CUSTOM_TEST_COMMANDS = ["make ci", "pytest"];
 
 test("mergeGauntlet: repo key replaces preset key whole-object", () => {
   const preset = { specCouncil: { members: ["a"], chair: "c" }, closureReview: { model: "m" } };
@@ -144,13 +149,83 @@ test("settingsErrorWarning: includes prefix and joined errors", () => {
 });
 
 test("verifyBeforeShip: default vs override", () => {
-  const d = resolveVerifyBeforeShip({}, DEFAULT_TEST_COMMANDS);
-  assert.deepEqual(d.testCommands, DEFAULT_TEST_COMMANDS);
+  const d = resolveVerifyBeforeShip({}, CUSTOM_TEST_COMMANDS);
+  assert.deepEqual(d.testCommands, CUSTOM_TEST_COMMANDS);
   assert.equal(d.warningReference, undefined);
   const o = resolveVerifyBeforeShip(
     { verifyBeforeShip: { testCommands: ["x"], warningReference: "doc/t.md" } },
-    DEFAULT_TEST_COMMANDS,
+    CUSTOM_TEST_COMMANDS,
   );
   assert.deepEqual(o.testCommands, ["x"]);
   assert.equal(o.warningReference, "doc/t.md");
 });
+
+test("telemetry: absent block -> enabled, default dir, default buckets, no warning", () => {
+  const r = resolveTelemetry({});
+  assert.equal(r.enabled, true);
+  assert.equal(r.dir, DEFAULT_TELEMETRY_DIR);
+  assert.equal(r.dir, ".pi/gauntlet/telemetry");
+  assert.deepEqual(r.buckets, DEFAULT_TELEMETRY_BUCKETS);
+  assert.equal(r.warning, undefined);
+});
+
+test("telemetry: enabled false is the only way to disable", () => {
+  assert.equal(resolveTelemetry({ telemetry: { enabled: false } }).enabled, false);
+  assert.equal(resolveTelemetry({ telemetry: { enabled: "no" } }).enabled, true);
+  assert.equal(resolveTelemetry({ telemetry: { enabled: 0 } }).enabled, true);
+});
+
+test("telemetry: dir accepts a non-empty relative path, otherwise default + warning", () => {
+  assert.equal(resolveTelemetry({ telemetry: { dir: "telemetry/" } }).dir, "telemetry");
+  assert.equal(resolveTelemetry({ telemetry: { dir: "a/../b" } }).dir, "b");
+  for (const bad of [
+    "",
+    "   ",
+    5,
+    null,
+    ["x"],
+    "/abs/dir",
+    "C:\\outside",
+    "C:/outside",
+    "C:outside",
+    "C:",
+    "\\\\server\\share",
+    "../outside",
+    "a/../../outside",
+    "..",
+  ]) {
+    const r = resolveTelemetry({ telemetry: { dir: bad } });
+    assert.equal(r.dir, DEFAULT_TELEMETRY_DIR);
+    assert.match(r.warning ?? "", /telemetry\.dir/);
+  }
+});
+
+test("telemetry: buckets replaces the default list wholesale, preserving key order", () => {
+  const r = resolveTelemetry({ telemetry: { buckets: { spec: ["doc/specs/**"], test: ["**/*.test.ts"] } } });
+  assert.deepEqual(r.buckets, [
+    ["spec", ["doc/specs/**"]],
+    ["test", ["**/*.test.ts"]],
+  ]);
+  assert.equal(r.warning, undefined);
+});
+
+test("telemetry: malformed buckets -> default + warning", () => {
+  for (const bad of [[], "x", { test: "**/*.ts" }, { test: [""] }, { test: [1] }, {}]) {
+    const r = resolveTelemetry({ telemetry: { buckets: bad } });
+    assert.deepEqual(r.buckets, DEFAULT_TELEMETRY_BUCKETS);
+    assert.match(r.warning ?? "", /telemetry\.buckets/);
+  }
+});
+
+test("telemetry: dir and buckets warnings join with '; '", () => {
+  const r = resolveTelemetry({ telemetry: { dir: 1, buckets: 2 } });
+  assert.match(r.warning ?? "", /telemetry\.dir.*; .*telemetry\.buckets/);
+});
+
+test("DEFAULT_TEST_COMMANDS + buildTestCmdRegex match the documented entrypoints", () => {
+  const re = buildTestCmdRegex(DEFAULT_TEST_COMMANDS);
+  for (const cmd of ["make ci", "make test", "npm test", "npm run test", "pnpm test", "yarn test", "pytest -q", "rspec", "cargo test", "go test ./..."])
+    assert.ok(re.test(cmd), cmd);
+  assert.equal(re.test("make test-smoke"), false);
+  assert.equal(re.test("ls"), false);
+});

package/extensions/lib/gauntlet-settings.ts

@@ -1,3 +1,5 @@
+import path from "node:path";
+
 // Pure gauntlet-settings resolvers. NO pi runtime import: this module is imported
 // by ci.mjs unit tests (node --test) which run outside pi, where
 // @earendil-works/pi-coding-agent is unresolvable. The loader
@@ -9,6 +11,7 @@ export interface PiGauntlet {
   flowGuards?: { enforce?: unknown; specDirs?: unknown };
   verifyBeforeShip?: { testCommands?: unknown; warningReference?: unknown };
   escalationLoop?: { implModel?: unknown };
+  telemetry?: { enabled?: unknown; dir?: unknown; buckets?: unknown };
 }
 
 // Whole-object second-level merge: each piGauntlet key present in the repo layer
@@ -143,6 +146,72 @@ export function resolveVerifyBeforeShip(g: PiGauntlet, defaultTestCommands: stri
   return { testCommands, warningReference };
 }
 
+// Default verification entrypoints shared by verify-before-ship (advisory) and
+// telemetry (derived.tests). Regex fragments; buildTestCmdRegex anchors them with \b.
+export const DEFAULT_TEST_COMMANDS = [
+  "make\\s+(?:ci|test)(?![-\\w])", // rejects make test-smoke and make test-corpus
+  "npm\\s+(?:test|run\\s+test)",
+  "pnpm\\s+test",
+  "yarn\\s+test",
+  "pytest",
+  "rspec",
+  "cargo\\s+test",
+  "go\\s+test",
+];
+
+export const buildTestCmdRegex = (commands: string[]): RegExp => new RegExp(`\\b(${commands.join("|")})\\b`);
+
+export const DEFAULT_TELEMETRY_DIR = ".pi/gauntlet/telemetry";
+
+// Ordered: first matching bucket wins; anything unmatched is "code".
+export const DEFAULT_TELEMETRY_BUCKETS: [string, string[]][] = [
+  ["test", ["**/test/**", "**/tests/**", "**/__tests__/**", "**/*.test.*", "**/*.spec.*", "**/*_test.*"]],
+  ["docs", ["**/*.md"]],
+  ["config", ["**/*.json", "**/*.yaml", "**/*.yml", "**/*.toml", "**/*.lock", "**/*-lock.*"]],
+];
+
+export interface TelemetryResolved {
+  enabled: boolean;
+  dir: string;
+  buckets: [string, string[]][];
+  warning: string | undefined;
+}
+
+export function resolveTelemetry(g: PiGauntlet): TelemetryResolved {
+  const t = g.telemetry;
+  const warnings: string[] = [];
+  const enabled = t?.enabled !== false;
+
+  let dir = DEFAULT_TELEMETRY_DIR;
+  if (t?.dir !== undefined) {
+    const value = nonEmptyString(t.dir) ? t.dir.trim().replace(/\/+$/, "") : "";
+    const canonical = value.replace(/\\/g, "/");
+    const normalized = path.posix.normalize(canonical);
+    if (
+      value &&
+      path.win32.parse(canonical).root === "" &&
+      normalized !== ".." &&
+      !normalized.startsWith("../")
+    ) dir = normalized;
+    else warnings.push("telemetry.dir must be a non-empty path relative to the git toplevel; using the default");
+  }
+
+  let buckets = DEFAULT_TELEMETRY_BUCKETS;
+  if (t?.buckets !== undefined) {
+    const b = t.buckets;
+    const valid =
+      b !== null &&
+      typeof b === "object" &&
+      !Array.isArray(b) &&
+      Object.keys(b).length > 0 &&
+      Object.values(b).every((v) => Array.isArray(v) && v.length > 0 && v.every(nonEmptyString));
+    if (valid) buckets = Object.entries(b as Record<string, string[]>).map(([name, globs]) => [name, [...globs]]);
+    else warnings.push("telemetry.buckets is not an object of non-empty glob arrays; using the defaults");
+  }
+
+  return { enabled, dir, buckets, warning: joinWarn(warnings) };
+}
+
 export function settingsErrorWarning(errors: string[]): string {
   return `\u26a0\ufe0f gauntlet settings load error (using defaults): ${errors.join("; ")}`;
 }

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

@@ -0,0 +1,50 @@
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import { COUNTED_USER_PHASES, REVIEWER_AGENTS, countFindings, countOpenGaps, hasReopen, insertedText, planTotals, textOf, usageToTokens } from "./telemetry-collect.ts";
+
+const usage = (input: number, output = 0, cost = 0) => ({ input, output, cacheRead: 0, cacheWrite: 0, totalTokens: input + output, cost: { input: cost, output: 0, cacheRead: 0, cacheWrite: 0, total: cost } });
+
+test("usageToTokens maps pi Usage to snake_case tokens; all-zero -> undefined", () => {
+  assert.deepEqual(usageToTokens(usage(10, 5, 0.25)), { input: 10, output: 5, cache_read: 0, cache_write: 0, cost: 0.25 });
+  assert.equal(usageToTokens(usage(0)), undefined);
+  assert.equal(usageToTokens(undefined), undefined);
+  assert.deepEqual(usageToTokens({ input: 1, output: 0, cacheRead: 0, cacheWrite: 0, totalTokens: 1, cost: 0.5 }), { input: 1, output: 0, cache_read: 0, cache_write: 0, cost: 0.5 });
+});
+
+test("countFindings tallies [blocker]/[major]/[minor] tags; none -> undefined", () => {
+  assert.deepEqual(countFindings("- [major] x\n- [minor] y\n- [MINOR] z\n[blocker] w"), { blocker: 1, major: 1, minor: 2 });
+  assert.equal(countFindings("all good"), undefined);
+});
+
+test("countOpenGaps returns the latest conformance result's open gap count", () => {
+  assert.equal(countOpenGaps("Conformance verdict: CONFORMS"), 0);
+  assert.equal(countOpenGaps("Conformance verdict: GAPS\nG1:\n  verdict: MISSING\nG2:\n  verdict: PARTIAL\nG1:\n  evidence: repeated"), 2);
+  assert.equal(countOpenGaps("unrelated reviewer text"), undefined);
+});
+
+test("planTotals counts tasks by terminal status", () => {
+  assert.deepEqual(planTotals([{ status: "complete" }, { status: "skipped" }, { status: "failed" }, { status: "complete" }]), { tasks: 4, complete: 2, failed: 1, skipped: 1 });
+});
+
+test("hasReopen detects complete -> in_progress at the same index only", () => {
+  assert.equal(hasReopen([{ status: "complete" }, { status: "pending" }], [{ status: "in_progress" }, { status: "pending" }]), true);
+  assert.equal(hasReopen([{ status: "complete" }], [{ status: "complete" }]), false);
+  assert.equal(hasReopen(undefined, [{ status: "in_progress" }]), false);
+  assert.equal(hasReopen([{ status: "pending" }], [{ status: "in_progress" }]), false);
+});
+
+test("insertedText joins edit newText values or returns write content", () => {
+  assert.equal(insertedText({ path: "x", edits: [{ oldText: "a", newText: "b" }, { oldText: "c", newText: "d" }] }), "b\nd");
+  assert.equal(insertedText({ path: "x", content: "body" }), "body");
+  assert.equal(insertedText({ path: "x" }), "");
+});
+
+test("textOf concatenates text content blocks", () => {
+  assert.equal(textOf([{ type: "text", text: "a" }, { type: "image" }, { type: "text", text: "b" }]), "a\n\nb");
+  assert.equal(textOf("nope"), "");
+});
+
+test("constant sets", () => {
+  assert.deepEqual([...REVIEWER_AGENTS], ["spec-reviewer", "code-reviewer", "conformance-reviewer"]);
+  assert.deepEqual([...COUNTED_USER_PHASES], ["plan", "implement", "verify", "ship"]);
+});

package/extensions/lib/telemetry-collect.ts

@@ -0,0 +1,59 @@
+// Pure reducers the telemetry collector applies to pi tool results (#33).
+import type { PhaseKey, Tokens } from "./telemetry-record.ts";
+
+// pi Usage -> snake_case tokens; cost is usage.cost.total (object) or a bare number.
+export function usageToTokens(u: unknown): Tokens | undefined {
+  const x = u as { input?: unknown; output?: unknown; cacheRead?: unknown; cacheWrite?: unknown; cost?: unknown } | undefined;
+  if (!x || typeof x !== "object") return undefined;
+  const n = (v: unknown): number => (typeof v === "number" && Number.isFinite(v) ? v : 0);
+  const cost = typeof x.cost === "number" ? x.cost : n((x.cost as { total?: unknown } | undefined)?.total);
+  const t: Tokens = { input: n(x.input), output: n(x.output), cache_read: n(x.cacheRead), cache_write: n(x.cacheWrite), cost };
+  return t.input || t.output || t.cache_read || t.cache_write || t.cost ? t : undefined;
+}
+
+const FINDING_TAG_RE = /\[(blocker|major|minor)\]/gi;
+export function countFindings(text: string): { blocker: number; major: number; minor: number } | undefined {
+  const out = { blocker: 0, major: 0, minor: 0 };
+  let any = false;
+  for (const m of text.matchAll(FINDING_TAG_RE)) {
+    out[m[1].toLowerCase() as keyof typeof out] += 1;
+    any = true;
+  }
+  return any ? out : undefined;
+}
+
+export function countOpenGaps(text: string): number | undefined {
+  if (/Conformance verdict:\s*CONFORMS/.test(text)) return 0;
+  const gaps = new Set([...text.matchAll(/^\s*G(\d+):/gm)].map((match) => match[1]));
+  return gaps.size || undefined;
+}
+
+export const REVIEWER_AGENTS = new Set(["spec-reviewer", "code-reviewer", "conformance-reviewer"]);
+export const COUNTED_USER_PHASES = new Set<PhaseKey>(["plan", "implement", "verify", "ship"]);
+
+export const textOf = (content: unknown): string =>
+  Array.isArray(content) ? content.map((c) => (c && typeof c === "object" && (c as { type?: string }).type === "text" ? String((c as { text?: unknown }).text ?? "") : "")).join("\n") : "";
+
+export interface PlanTotals {
+  tasks: number;
+  complete: number;
+  failed: number;
+  skipped: number;
+}
+export const planTotals = (tasks: { status: string }[]): PlanTotals => ({
+  tasks: tasks.length,
+  complete: tasks.filter((t) => t.status === "complete").length,
+  failed: tasks.filter((t) => t.status === "failed").length,
+  skipped: tasks.filter((t) => t.status === "skipped").length,
+});
+
+// A plan_tracker update that moves a task from complete back to in_progress.
+export const hasReopen = (prev: { status: string }[] | undefined, next: { status: string }[]): boolean =>
+  !!prev && next.some((t, i) => prev[i]?.status === "complete" && t.status === "in_progress");
+
+// The text an edit/write call inserts: joined newText values, or the write body.
+export const insertedText = (input: unknown): string => {
+  const i = input as { edits?: { newText?: unknown }[]; content?: unknown };
+  if (Array.isArray(i.edits)) return i.edits.map((e) => String(e?.newText ?? "")).join("\n");
+  return typeof i.content === "string" ? i.content : "";
+};

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

@@ -0,0 +1,98 @@
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import {
+  aggregateNumstat,
+  classifyBucket,
+  isPlanPath,
+  isSpecPath,
+  isSupersededByBanner,
+  matchDiscardStatement,
+  matchShipStatement,
+  matchTestStatement,
+  parseSpecLinks,
+  planSpecHeader,
+  recordPathFor,
+  repoRelativeToolPath,
+  truncateCommand,
+} from "./telemetry-paths.ts";
+import { DEFAULT_TELEMETRY_BUCKETS, DEFAULT_TEST_COMMANDS } from "./gauntlet-settings.ts";
+
+test("recordPathFor maps <dir>/<spec .md -> .yaml> preserving nesting", () => {
+  assert.equal(recordPathFor(".pi/gauntlet/telemetry", "doc/specs/x.md"), ".pi/gauntlet/telemetry/doc/specs/x.yaml");
+  assert.equal(recordPathFor("t", "svc/doc/specs/2026-01-01-a.md"), "t/svc/doc/specs/2026-01-01-a.yaml");
+});
+
+test("repoRelativeToolPath resolves like pi tools: relative to cwd, then repo-relative", () => {
+  assert.equal(repoRelativeToolPath("/repo", "/repo", "doc/specs/a.md"), "doc/specs/a.md");
+  assert.equal(repoRelativeToolPath("/repo", "/repo/svc", "doc/specs/a.md"), "svc/doc/specs/a.md");
+  assert.equal(repoRelativeToolPath("/repo", "/repo/svc", "/repo/doc/specs/a.md"), "doc/specs/a.md");
+  assert.equal(repoRelativeToolPath("/repo", "/repo", "/elsewhere/x.md"), undefined);
+});
+
+test("isSpecPath / isPlanPath match **/doc/specs/*.md and **/doc/plans/*.md only", () => {
+  assert.ok(isSpecPath("doc/specs/a.md"));
+  assert.ok(isSpecPath("svc/doc/specs/a.md"));
+  assert.equal(isSpecPath("doc/specs/sub/a.md"), false);
+  assert.equal(isSpecPath("doc/plans/a.md"), false);
+  assert.ok(isPlanPath("doc/plans/a.md"));
+});
+
+test("planSpecHeader extracts the **Spec:** path", () => {
+  assert.equal(planSpecHeader("# P\n\n**Spec:** `doc/specs/a.md`\n"), "doc/specs/a.md");
+  assert.equal(planSpecHeader("**Spec:** doc/specs/a.md"), "doc/specs/a.md");
+  assert.equal(planSpecHeader("no header"), undefined);
+});
+
+test("matchShipStatement needs a statement start (STMT_START)", () => {
+  assert.deepEqual(matchShipStatement("git merge --squash gh-33 && git commit"), { option: "squash", statement: "git merge --squash gh-33" });
+  assert.deepEqual(matchShipStatement("cd x; git push -u origin HEAD"), { option: "pr", statement: "git push -u origin HEAD" });
+  assert.equal(matchShipStatement('gh pr create --fill')?.option, "pr");
+  assert.equal(matchShipStatement('rg "git push" skills/'), undefined);
+  assert.equal(matchShipStatement("echo git push"), undefined);
+});
+
+test("matchDiscardStatement matches worktree remove and branch -D", () => {
+  assert.equal(matchDiscardStatement("git worktree remove .worktrees/x"), "git worktree remove .worktrees/x");
+  assert.equal(matchDiscardStatement("cd .. && git branch -D gh-33"), "git branch -D gh-33");
+  assert.equal(matchDiscardStatement("git branch -d gh-33"), undefined);
+});
+
+test("matchTestStatement returns the first statement matching a test fragment", () => {
+  assert.equal(matchTestStatement("cd repo && npm test -- --grep x", DEFAULT_TEST_COMMANDS), "npm test -- --grep x");
+  assert.equal(matchTestStatement("make test-smoke", DEFAULT_TEST_COMMANDS), undefined);
+  assert.equal(matchTestStatement("ls", DEFAULT_TEST_COMMANDS), undefined);
+});
+
+test("truncateCommand cuts at 120 chars", () => {
+  assert.equal(truncateCommand("a".repeat(200)).length, 120);
+  assert.equal(truncateCommand("short"), "short");
+});
+
+test("classifyBucket: first match wins, else code", () => {
+  assert.equal(classifyBucket("extensions/lib/telemetry-paths.test.ts", DEFAULT_TELEMETRY_BUCKETS), "test");
+  assert.equal(classifyBucket("doc/configuration.md", DEFAULT_TELEMETRY_BUCKETS), "docs");
+  assert.equal(classifyBucket("package.json", DEFAULT_TELEMETRY_BUCKETS), "config");
+  assert.equal(classifyBucket("extensions/telemetry.ts", DEFAULT_TELEMETRY_BUCKETS), "code");
+  assert.equal(classifyBucket("doc/specs/a.md", [["spec", ["doc/specs/**"]], ["docs", ["**/*.md"]]]), "spec");
+});
+
+test("aggregateNumstat sums per bucket over the given file set; binary rows count 0 lines", () => {
+  const numstat = ["10\t2\textensions/telemetry.ts", "5\t0\textensions/lib/telemetry-paths.test.ts", "-\t-\timg.png", "3\t3\tdoc/specs/a.md", "1\t1\t{old => new}/x.ts"].join("\n");
+  const files = new Set(["extensions/telemetry.ts", "extensions/lib/telemetry-paths.test.ts", "img.png", "new/x.ts"]);
+  assert.deepEqual(aggregateNumstat(numstat, files, DEFAULT_TELEMETRY_BUCKETS), {
+    code: { files: 3, insertions: 11, deletions: 3 },
+    test: { files: 1, insertions: 5, deletions: 0 },
+  });
+});
+
+test("parseSpecLinks reads Supersedes/Fixes banners as paths or markdown links", () => {
+  const body = "# T\n\n> **Supersedes:** [doc/specs/a.md](./a.md), doc/specs/b.md\n> **Fixes:** [doc/specs/c.md](./c.md)\n";
+  assert.deepEqual(parseSpecLinks(body), { supersedes: ["doc/specs/a.md", "doc/specs/b.md"], fixes: ["doc/specs/c.md"] });
+  assert.deepEqual(parseSpecLinks("# T\n"), { supersedes: [], fixes: [] });
+});
+
+test("isSupersededByBanner detects the predecessor banner and its successor label", () => {
+  assert.equal(isSupersededByBanner("> **Superseded by:** [doc/specs/new.md](./new.md) - fully", "doc/specs/new.md"), true);
+  assert.equal(isSupersededByBanner("> **Superseded by:** [doc/specs/other.md](./other.md)", "doc/specs/new.md"), false);
+  assert.equal(isSupersededByBanner("plain text", "doc/specs/new.md"), false);
+});

package/extensions/lib/telemetry-paths.ts

@@ -0,0 +1,145 @@
+// Pure helpers for the telemetry extension (#33): record path mapping, pi-cwd
+// path resolution, ship/discard/test command matchers, diff buckets, spec banners.
+//
+// Ship detection runs on a `bash` `tool_call` while `ship` is in progress and matches
+// the first statement against
+//   STMT_START + (git\s+merge\s+--squash|git\s+push|gh\s+pr\s+create)
+// and discard against
+//   STMT_START + git\s+(worktree\s+remove|branch\s+-D)
+// with STMT_START from phase-tracker-helpers.ts:39.
+// Default bucket globs (DEFAULT_TELEMETRY_BUCKETS): test = **/test/**, **/tests/**,
+// **/__tests__/**, **/*.test.*, **/*.spec.*, **/*_test.*; docs = **/*.md;
+// config = **/*.json, **/*.yaml, **/*.yml, **/*.toml, **/*.lock, **/*-lock.*; else code.
+
+import { isAbsolute, matchesGlob, relative, resolve } from "node:path";
+import { STMT_START } from "./phase-tracker-helpers.ts";
+import { buildTestCmdRegex } from "./gauntlet-settings.ts";
+
+// ---- paths -------------------------------------------------------------------
+
+export const toPosix = (p: string): string => p.split("\\").join("/");
+
+export const isSpecPath = (rel: string): boolean => /(^|\/)doc\/specs\/[^/]+\.md$/.test(rel);
+export const isPlanPath = (rel: string): boolean => /(^|\/)doc\/plans\/[^/]+\.md$/.test(rel);
+
+// <dir>/<spec path with trailing .md replaced by .yaml>, nesting preserved.
+export const recordPathFor = (dir: string, specRel: string): string => `${dir}/${specRel.replace(/\.md$/, ".yaml")}`;
+
+// pi tools resolve a relative path against ctx.cwd; the record key is repo-relative
+// to the owning toplevel so the same spec maps to one record from any cwd.
+// Returns undefined for paths outside the toplevel.
+export function repoRelativeToolPath(toplevel: string, cwd: string, p: string): string | undefined {
+  const abs = isAbsolute(p) ? p : resolve(cwd, p);
+  const rel = toPosix(relative(toplevel, abs));
+  if (rel === "" || rel.startsWith("../") || rel === ".." || isAbsolute(rel)) return undefined;
+  return rel;
+}
+
+const SPEC_HEADER_RE = /^\*\*Spec:\*\*\s*`?([^`\s]+)`?/m;
+export const planSpecHeader = (planBody: string): string | undefined => SPEC_HEADER_RE.exec(planBody)?.[1];
+
+// ---- command matchers ----------------------------------------------------------
+
+const SHIP_RE = new RegExp(STMT_START + "(git\\s+merge\\s+--squash|git\\s+push|gh\\s+pr\\s+create)");
+const DISCARD_RE = new RegExp(STMT_START + "(git\\s+(?:worktree\\s+remove|branch\\s+-D))");
+const STATEMENT_END = /\n|;|&&|\|\||\|/;
+
+export const truncateCommand = (s: string): string => (s.length > 120 ? s.slice(0, 120) : s);
+
+// The statement that begins at the regex's group-1 match, up to the next separator.
+function statementAt(command: string, re: RegExp): string | undefined {
+  const m = re.exec(command);
+  if (!m) return undefined;
+  const start = m.index + m[0].indexOf(m[1]);
+  return command.slice(start).split(STATEMENT_END)[0].trim();
+}
+
+export type ShipOption = "squash" | "pr";
+
+export function matchShipStatement(command: string): { option: ShipOption; statement: string } | undefined {
+  const statement = statementAt(command, SHIP_RE);
+  if (!statement) return undefined;
+  return { option: /^git\s+merge\s+--squash/.test(statement) ? "squash" : "pr", statement };
+}
+
+export const matchDiscardStatement = (command: string): string | undefined => statementAt(command, DISCARD_RE);
+
+// First statement matching one of the resolved verifyBeforeShip.testCommands
+// fragments, using the same \b-anchored construction as verify-before-ship.ts.
+export function matchTestStatement(command: string, testCommands: string[]): string | undefined {
+  const re = buildTestCmdRegex(testCommands);
+  for (const raw of command.split(STATEMENT_END)) {
+    const statement = raw.trim();
+    if (statement && re.test(statement)) return statement;
+  }
+  return undefined;
+}
+
+// ---- diff buckets --------------------------------------------------------------
+
+export function classifyBucket(rel: string, buckets: [string, string[]][]): string {
+  for (const [name, globs] of buckets) if (globs.some((g) => matchesGlob(rel, g))) return name;
+  return "code";
+}
+
+export interface BucketStat {
+  files: number;
+  insertions: number;
+  deletions: number;
+}
+
+// `git diff --numstat` rows: "<ins>\t<del>\t<path>"; binary rows use "-"; renames
+// render as "a => b" or "{a => b}/rest" and count under the new path.
+export function numstatPath(raw: string): string {
+  const braced = raw.replace(/\{([^{}]*) => ([^{}]*)\}/g, (_m, _a, b: string) => b).replace(/\/\//g, "/");
+  const arrow = braced.indexOf(" => ");
+  return arrow >= 0 ? braced.slice(arrow + 4) : braced;
+}
+
+export function aggregateNumstat(numstat: string, files: Set<string>, buckets: [string, string[]][]): Record<string, BucketStat> {
+  const out: Record<string, BucketStat> = {};
+  for (const line of numstat.split("\n")) {
+    if (!line.trim()) continue;
+    const [ins, del, ...rest] = line.split("\t");
+    const path = numstatPath(rest.join("\t"));
+    if (!files.has(path)) continue;
+    const bucket = classifyBucket(path, buckets);
+    const stat = (out[bucket] ??= { files: 0, insertions: 0, deletions: 0 });
+    stat.files += 1;
+    stat.insertions += ins === "-" ? 0 : Number(ins) || 0;
+    stat.deletions += del === "-" ? 0 : Number(del) || 0;
+  }
+  return out;
+}
+
+// ---- spec banners --------------------------------------------------------------
+
+const LINK_BANNER_RE = /^> \*\*(Supersedes|Fixes):\*\*\s*(.+)$/gm;
+const MD_LINK_RE = /\[([^\]]+)\]\([^)]*\)/g;
+
+function bannerTargets(rest: string): string[] {
+  const labels: string[] = [];
+  const remainder = rest.replace(MD_LINK_RE, (_m, label: string) => {
+    labels.push(label.trim());
+    return " ";
+  });
+  for (const tok of remainder.split(/[\s,]+/)) if (tok && tok !== "-") labels.push(tok);
+  return labels;
+}
+
+export function parseSpecLinks(body: string): { supersedes: string[]; fixes: string[] } {
+  const out = { supersedes: [] as string[], fixes: [] as string[] };
+  for (const m of body.matchAll(LINK_BANNER_RE)) {
+    const list = m[1] === "Supersedes" ? out.supersedes : out.fixes;
+    for (const t of bannerTargets(m[2])) if (!list.includes(t)) list.push(t);
+  }
+  return out;
+}
+
+export const SUPERSEDED_BY_RE = /^> \*\*Superseded by:\*\*/m;
+
+// True when the inserted text is a predecessor banner naming `successor` as its label.
+export function isSupersededByBanner(inserted: string, successor: string): boolean {
+  const m = /^> \*\*Superseded by:\*\*\s*\[([^\]]+)\]/m.exec(inserted);
+  return m?.[1]?.trim() === successor;
+}