pi-gauntlet 5.7.0 → 5.8.0

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

@@ -0,0 +1,173 @@
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import { STMT_START } from "./phase-tracker-helpers.ts";
+import {
+  capEvents, derive, diffPhases, emptyAccumulators, emptyPhases, foldAccumulators, implementAutoCompletes,
+  newRecord, parseRecord, serializeRecord, type Accumulators, type TelemetryEvent,
+} from "./telemetry-record.ts";
+import { matchShipStatement } from "./telemetry-paths.ts";
+
+const ev = (over: Partial<TelemetryEvent> & { kind: string }): TelemetryEvent =>
+  ({ ts: "2026-09-17T10:00:00Z", session: "s1", phase: "unphased", ...over }) as TelemetryEvent;
+
+test("diffPhases: start/complete/skip emit one transition per changed phase; status/substep/grant emit none; reset emits reset", () => {
+  const a = emptyPhases();
+  const b = { ...a, brainstorm: { status: "in_progress" as const } };
+  assert.deepEqual(diffPhases(a, b, "start"), [{ action: "start", name: "brainstorm" }]);
+  const c = { ...b, brainstorm: { status: "complete" as const } };
+  assert.deepEqual(diffPhases(b, c, "complete"), [{ action: "complete", name: "brainstorm" }]);
+  assert.deepEqual(diffPhases(b, { ...b, brainstorm: { status: "in_progress", substep: "gather" } }, "substep"), []);
+  assert.deepEqual(diffPhases(b, b, "status"), []);
+  assert.deepEqual(diffPhases(b, b, "grant_fix_rounds"), []);
+  assert.deepEqual(diffPhases(c, a, "reset"), [{ action: "reset" }]);
+});
+
+test("implementAutoCompletes only when implement is in progress and every task is complete|skipped", () => {
+  const p = { ...emptyPhases(), implement: { status: "in_progress" as const } };
+  assert.equal(implementAutoCompletes(p, [{ status: "complete" }, { status: "skipped" }]), true);
+  assert.equal(implementAutoCompletes(p, [{ status: "complete" }, { status: "failed" }]), false);
+  assert.equal(implementAutoCompletes(p, []), false);
+  assert.equal(implementAutoCompletes(emptyPhases(), [{ status: "complete" }]), false);
+});
+
+test("foldAccumulators sums counts/tokens, maxes peak_context, takes last_sha256 from the later block, and is associative", () => {
+  const a: Accumulators = { ...emptyAccumulators(), amendments: 1, phases: { plan: { tokens: { input: 10, output: 1, cache_read: 0, cache_write: 0, cost: 0.5 }, peak_context: 100, user_messages: 2 } }, spec_writes: { brainstorm: { count: 2, last_sha256: "aa" } }, personas: { implementer: { dispatches: 1, models: ["m1"] } } };
+  const b: Accumulators = { ...emptyAccumulators(), amendments: 2, phases: { plan: { tokens: { input: 5, output: 1, cache_read: 2, cache_write: 0, cost: 0.25 }, peak_context: 50, compactions: 1 } }, spec_writes: { brainstorm: { count: 1, last_sha256: "bb" } }, personas: { implementer: { dispatches: 2, models: ["m1", "m2"] } } };
+  const c: Accumulators = { ...emptyAccumulators(), gates: { spec_rounds: 1, plan_rounds: 0, fix_round_grants: 0, task_reopens: 0 } };
+  const ab = foldAccumulators(a, b);
+  assert.equal(ab.amendments, 3);
+  assert.deepEqual(ab.phases.plan, { tokens: { input: 15, output: 2, cache_read: 2, cache_write: 0, cost: 0.75 }, peak_context: 100, user_messages: 2, compactions: 1 });
+  assert.deepEqual(ab.spec_writes.brainstorm, { count: 3, last_sha256: "bb" });
+  assert.deepEqual(ab.personas.implementer, { dispatches: 3, models: ["m1", "m2"] });
+  assert.deepEqual(foldAccumulators(ab, c), foldAccumulators(a, foldAccumulators(b, c)));
+});
+
+test("capEvents drops oldest non-lifecycle events first and reports the drop count", () => {
+  const events: TelemetryEvent[] = [ev({ kind: "phase", action: "start", name: "brainstorm" } as any)];
+  for (let i = 0; i < 305; i++) events.push(ev({ kind: "dispatch", agent: `a${i}` } as any));
+  events.push(ev({ kind: "ship", option: "squash" } as any));
+  const { events: kept, dropped } = capEvents(events, 300);
+  assert.equal(kept.length, 300);
+  assert.equal(dropped, 7);
+  assert.equal(kept[0].kind, "phase");
+  assert.equal((kept[1] as any).agent, "a7");
+  assert.equal(kept.at(-1)!.kind, "ship");
+});
+
+test("capEvents never drops lifecycle events and leaves derive unchanged when lifecycle events exceed the cap", () => {
+  const rec = newRecord({ spec: "doc/specs/a.md", session: "s1", now: "2026-09-17T10:00:00Z", runId: "r1" });
+  rec.events = [
+    ...Array.from({ length: 305 }, (_, i) => ev({
+      kind: "phase",
+      action: i % 2 === 0 ? "start" : "complete",
+      name: "brainstorm",
+      ts: new Date(Date.parse("2026-09-17T10:00:00Z") + i * 1000).toISOString(),
+    } as any)),
+    ...Array.from({ length: 10 }, (_, i) => ev({ kind: "dispatch", agent: `a${i}` } as any)),
+  ];
+  const before = JSON.stringify(derive(rec, "2026-09-17T12:00:00Z"));
+  const capped = capEvents(rec.events, 300);
+  rec.events = capped.events;
+  assert.equal(capped.events.length, 305);
+  assert.ok(capped.events.every((event) => event.kind === "phase"));
+  assert.equal(capped.dropped, 10);
+  assert.equal(JSON.stringify(derive(rec, "2026-09-17T12:00:00Z")), before);
+});
+
+test("derive: phase timing from events, counts from accumulators, ship_option from the live ship event; unchanged by the cap", () => {
+  const rec = newRecord({ spec: "doc/specs/a.md", session: "s1", now: "2026-09-17T10:00:00Z", runId: "r1" });
+  rec.events.push(
+    ev({ kind: "phase", action: "start", name: "brainstorm", model: "p/m", thinking: "high", ts: "2026-09-17T10:00:00Z" } as any),
+    ev({ kind: "phase", action: "complete", name: "brainstorm", phase: "brainstorm", ts: "2026-09-17T10:10:00Z" } as any),
+    ev({ kind: "phase", action: "start", name: "ship", ts: "2026-09-17T11:00:00Z" } as any),
+    ev({ kind: "ship", option: "pr", phase: "ship", ts: "2026-09-17T11:05:00Z" } as any),
+    ev({ kind: "ship_failed", phase: "ship", ts: "2026-09-17T11:06:00Z" } as any),
+    ev({ kind: "ship", option: "squash", phase: "ship", ts: "2026-09-17T11:07:00Z" } as any),
+  );
+  rec.accumulators.s1 = { ...emptyAccumulators(), amendments: 1, events_dropped: 3, phases: { brainstorm: { tokens: { input: 1, output: 2, cache_read: 0, cache_write: 0, cost: 0.1 }, compactions: 1 }, unphased: { tokens: { input: 9, output: 0, cache_read: 0, cache_write: 0, cost: 0 } } }, gates: { spec_rounds: 2, plan_rounds: 1, fix_round_grants: 0, task_reopens: 0 } };
+  rec.approved_at = "2026-09-17T10:10:00Z";
+  rec.shipped_at = "2026-09-17T11:07:00Z";
+  const d = derive(rec, "2026-09-17T12:00:00Z");
+  assert.equal(d.duration_s, 67 * 60);
+  assert.deepEqual(d.phases.brainstorm, { started_at: "2026-09-17T10:00:00Z", completed_at: "2026-09-17T10:10:00Z", duration_s: 600, model: "p/m", thinking: "high", tokens: { input: 1, output: 2, cache_read: 0, cache_write: 0, cost: 0.1 }, compactions: 1 });
+  assert.deepEqual(d.phases.unphased, { tokens: { input: 9, output: 0, cache_read: 0, cache_write: 0, cost: 0 } });
+  assert.equal(d.phases.ship?.started_at, "2026-09-17T11:00:00Z");
+  assert.equal(d.phases.ship?.completed_at, undefined);
+  assert.deepEqual(d.gates, { spec_rounds: 2, plan_rounds: 1, fix_round_grants: 0, task_reopens: 0, ship_option: "squash" });
+  assert.equal(d.amendments, 1);
+  assert.equal(d.spec_edits_after_ship, 0);
+  assert.equal(d.events_dropped, 3);
+  assert.equal("plan" in d, false);
+  assert.equal("tests" in d, false);
+  const before = JSON.stringify(d);
+  rec.events = capEvents([...rec.events, ...Array.from({ length: 400 }, (_, i) => ev({ kind: "dispatch", agent: `x${i}`, phase: "plan" } as any))], 300).events;
+  assert.equal(JSON.stringify(derive(rec, "2026-09-17T12:00:00Z")).replace(/"personas":\{[^}]*\}/, ""), before.replace(/"personas":\{[^}]*\}/, ""));
+});
+
+test("serializeRecord -> parseRecord round-trips run_id, events, accumulators, and writes derived before accumulators/events", () => {
+  const rec = newRecord({ spec: "doc/specs/a.md", session: "s1", now: "2026-09-17T10:00:00Z", runId: "r1" });
+  rec.events.push(ev({ kind: "phase", action: "start", name: "brainstorm" } as any));
+  rec.accumulators.s1 = { ...emptyAccumulators(), conformance_open_gaps: 2, amendments: 2 };
+  rec.derived = derive(rec, "2026-09-17T10:01:00Z");
+  const text = serializeRecord(rec);
+  assert.ok(text.startsWith("schema: 1\nspec: doc/specs/a.md\nrun_id: r1\n"), text.slice(0, 80));
+  assert.ok(text.indexOf("derived:") < text.indexOf("accumulators:") && text.indexOf("accumulators:") < text.indexOf("events:"));
+  assert.match(text, /^  - \{ ts: .*kind: phase.*\}$/m);
+  assert.doesNotMatch(text, /null/);
+  const back = parseRecord(text)!;
+  assert.equal(back.run_id, "r1");
+  assert.deepEqual(back.events, rec.events);
+  assert.deepEqual(back.accumulators, rec.accumulators);
+  assert.equal(back.derived.conformance_open_gaps, 2);
+  assert.ok(text.indexOf("conformance_loops:") < text.indexOf("conformance_open_gaps:"));
+  assert.equal(parseRecord("not: [valid"), undefined);
+  assert.equal(parseRecord("schema: 2\nspec: x"), undefined);
+});
+
+test("serializeRecord keeps a populated 300-event record under 450 lines with leaf objects in flow style", () => {
+  const tokens = { input: 100, output: 20, cache_read: 30, cache_write: 4, cost: 0.5 };
+  const phases = Object.fromEntries(["brainstorm", "plan", "implement", "verify", "ship"].map((phase) =>
+    [phase, { tokens, peak_context: 20_000, user_messages: 3 }]
+  ));
+  const personas = Object.fromEntries(["brainstormer", "spec_reviewer", "planner", "plan_reviewer", "implementer", "reviewer", "verifier"].map((persona) =>
+    [persona, { dispatches: 2, models: ["provider/model-a", "provider/model-b"], tokens }]
+  ));
+  const reviews = Object.fromEntries(["spec", "plan", "code"].map((review) =>
+    [review, { dispatches: 2, nonzero_exit: 1, findings: { blocker: 0, major: 1, minor: 2 } }]
+  ));
+  const populated = (): Accumulators => ({
+    ...emptyAccumulators(), phases, personas, reviews,
+    gates: { spec_rounds: 2, plan_rounds: 2, fix_round_grants: 1, task_reopens: 1 },
+  } as Accumulators);
+  const rec = newRecord({ spec: "doc/specs/populated.md", session: "s1", now: "2026-09-17T10:00:00Z", runId: "populated", branch: "main" });
+  rec.accumulators = { s1: populated(), s2: populated() };
+  rec.derived = {
+    ...rec.derived, phases, personas, reviews,
+    gates: { spec_rounds: 4, plan_rounds: 4, fix_round_grants: 2, task_reopens: 2 },
+    plan: { tasks: 10, complete: 8, failed: 1, skipped: 1 }, tests: { command: "node --test", result: "pass" },
+    diff: { base: "main", commits: 3, buckets: { source: { files: 10, insertions: 100, deletions: 20 }, tests: { files: 5, insertions: 50, deletions: 5 }, docs: { files: 5, insertions: 25, deletions: 2 } } },
+    modified_files: Array.from({ length: 20 }, (_, i) => `extensions/file-${i}.ts`),
+  };
+  rec.events = Array.from({ length: 300 }, (_, i) => ev({ kind: "dispatch", agent: `agent-${i}`, phase: "implement" } as any));
+
+  const text = serializeRecord(rec);
+  assert.ok(text.split("\n").length < 450, `serialized record has ${text.split("\n").length} lines`);
+  assert.match(text, /^    implementer: \{ dispatches: /m);
+  assert.deepEqual(parseRecord(text), rec);
+});
+
+test("parseRecord drops malformed accumulator blocks and fills missing fields", () => {
+  const rec = newRecord({ spec: "doc/specs/a.md", session: "s1", now: "2026-09-17T10:00:00Z", runId: "r1" });
+  const text = serializeRecord(rec).replace("accumulators: {}", "accumulators: { s1: null, s2: 5, s3: { amendments: 2 } }");
+  const parsed = parseRecord(text)!;
+  assert.deepEqual(Object.keys(parsed.accumulators), ["s3"]);
+  assert.equal(parsed.accumulators.s3.amendments, 2);
+  assert.deepEqual(parsed.accumulators.s3.phases, {});
+  assert.doesNotThrow(() => derive(parsed, "2026-09-17T10:01:00Z"));
+  assert.equal(derive(parsed, "2026-09-17T10:01:00Z").amendments, 2);
+});
+
+test("STMT_START-anchored matcher is the one used for ship detection", () => {
+  assert.ok(new RegExp(STMT_START + "git\\s+push").test("cd x && git push"));
+  assert.equal(matchShipStatement('rg "git push"'), undefined);
+});

package/extensions/lib/telemetry-record.ts

@@ -0,0 +1,181 @@
+// Telemetry record model (#33): phases, events, accumulators, derive, YAML.
+import { Document, isCollection, isMap, isSeq, parse as parseYaml, stringify as stringifyYaml, type YAMLMap } from "yaml";
+import type { BucketStat, ShipOption } from "./telemetry-paths.ts";
+
+export const PHASES = ["brainstorm", "plan", "implement", "verify", "ship"] as const;
+export type Phase = (typeof PHASES)[number];
+export type PhaseKey = Phase | "unphased";
+export type PhaseStatus = "pending" | "in_progress" | "complete" | "skipped";
+export type PhaseMap = Record<Phase, { status: PhaseStatus; substep?: string; reason?: string }>;
+export const emptyPhases = (): PhaseMap => Object.fromEntries(PHASES.map((p) => [p, { status: "pending" }])) as PhaseMap;
+export const currentPhase = (phases: PhaseMap): PhaseKey => PHASES.find((p) => phases[p].status === "in_progress") ?? "unphased";
+export type PhaseAction = "start" | "complete" | "skip" | "reset";
+export interface PhaseTransition { action: PhaseAction; name?: Phase }
+export function diffPhases(prev: PhaseMap, next: PhaseMap, action: string): PhaseTransition[] {
+  if (action === "reset") return [{ action: "reset" }];
+  if (action !== "start" && action !== "complete" && action !== "skip") return [];
+  return PHASES.filter((p) => prev[p].status !== next[p].status).map((name) => ({ action, name }));
+}
+export const implementAutoCompletes = (phases: PhaseMap, tasks: { status: string }[] | undefined): boolean =>
+  phases.implement.status === "in_progress" && Array.isArray(tasks) && tasks.length > 0 && tasks.every((t) => t.status === "complete" || t.status === "skipped");
+
+export interface BaseEvent { ts: string; session: string; phase: PhaseKey }
+export type TelemetryEvent = BaseEvent & (
+  | { kind: "phase"; action: PhaseAction; name?: Phase; model?: string; thinking?: string }
+  | { kind: "plan_check"; pass: boolean; spec?: string; plan?: string }
+  | { kind: "dispatch"; agent: string; model?: string; exit?: number }
+  | { kind: "gate"; gate: "fix_round_grant" | "task_reopen"; rounds?: number }
+  | { kind: "config_change"; model?: string; thinking?: string }
+  | { kind: "ship"; option: ShipOption | "keep" | "discard"; command?: string }
+  | { kind: "ship_failed" }
+  | { kind: "spec_renamed"; from: string; to: string }
+  | { kind: "warning"; message: string }
+);
+// Lifecycle events are never dropped because derive depends on their complete history.
+const LIFECYCLE_KINDS = new Set(["phase", "ship", "ship_failed", "spec_renamed"]);
+export const EVENT_CAP = 300;
+export function capEvents(events: TelemetryEvent[], cap = EVENT_CAP): { events: TelemetryEvent[]; dropped: number } {
+  let kept = events, dropped = 0;
+  if (kept.length > cap) {
+    let excess = kept.length - cap;
+    kept = kept.filter((e) => {
+      if (excess > 0 && !LIFECYCLE_KINDS.has(e.kind)) { excess--; dropped++; return false; }
+      return true;
+    });
+  }
+  return { events: kept, dropped };
+}
+
+export interface Tokens { input: number; output: number; cache_read: number; cache_write: number; cost: number }
+export interface PhaseAcc { tokens?: Tokens; compactions?: number; user_messages?: number; peak_context?: number }
+export interface PersonaAcc { dispatches: number; models: string[]; tokens?: Tokens }
+export interface ReviewAcc { dispatches: number; nonzero_exit: number; findings?: { blocker: number; major: number; minor: number } }
+export interface Gates { spec_rounds: number; plan_rounds: number; fix_round_grants: number; task_reopens: number }
+export interface Accumulators {
+  phases: Partial<Record<PhaseKey, PhaseAcc>>; personas: Record<string, PersonaAcc>; reviews: Record<string, ReviewAcc>;
+  spec_writes: Partial<Record<PhaseKey, { count: number; last_sha256: string }>>; gates: Gates;
+  conformance_loops: number; conformance_open_gaps?: number; amendments: number; spec_edits_after_ship: number; events_dropped: number;
+}
+export const emptyAccumulators = (): Accumulators => ({ phases: {}, personas: {}, reviews: {}, spec_writes: {}, gates: { spec_rounds: 0, plan_rounds: 0, fix_round_grants: 0, task_reopens: 0 }, conformance_loops: 0, amendments: 0, spec_edits_after_ship: 0, events_dropped: 0 });
+export const zeroTokens = (): Tokens => ({ input: 0, output: 0, cache_read: 0, cache_write: 0, cost: 0 });
+export const addTokens = (a: Tokens | undefined, b: Tokens): Tokens => ({ input: (a?.input ?? 0) + b.input, output: (a?.output ?? 0) + b.output, cache_read: (a?.cache_read ?? 0) + b.cache_read, cache_write: (a?.cache_write ?? 0) + b.cache_write, cost: (a?.cost ?? 0) + b.cost });
+const optSum = (a?: number, b?: number): number | undefined => a === undefined && b === undefined ? undefined : (a ?? 0) + (b ?? 0);
+const optMax = (a?: number, b?: number): number | undefined => a === undefined ? b : b === undefined ? a : Math.max(a, b);
+export const compact = <T extends object>(o: T): T => Object.fromEntries(Object.entries(o).filter(([, v]) => v !== undefined)) as T;
+export function foldAccumulators(a: Accumulators, b: Accumulators): Accumulators {
+  const out = emptyAccumulators();
+  for (const k of new Set([...Object.keys(a.phases), ...Object.keys(b.phases)]) as Set<PhaseKey>) {
+    const x = a.phases[k] ?? {}, y = b.phases[k] ?? {};
+    out.phases[k] = compact({ tokens: x.tokens && y.tokens ? addTokens(x.tokens, y.tokens) : x.tokens ?? y.tokens, compactions: optSum(x.compactions, y.compactions), user_messages: optSum(x.user_messages, y.user_messages), peak_context: optMax(x.peak_context, y.peak_context) });
+  }
+  for (const k of new Set([...Object.keys(a.personas), ...Object.keys(b.personas)])) {
+    const x = a.personas[k], y = b.personas[k];
+    out.personas[k] = compact({ dispatches: (x?.dispatches ?? 0) + (y?.dispatches ?? 0), models: [...new Set([...(x?.models ?? []), ...(y?.models ?? [])])], tokens: x?.tokens && y?.tokens ? addTokens(x.tokens, y.tokens) : x?.tokens ?? y?.tokens });
+  }
+  for (const k of new Set([...Object.keys(a.reviews), ...Object.keys(b.reviews)])) {
+    const x = a.reviews[k], y = b.reviews[k];
+    const findings = x?.findings || y?.findings ? { blocker: (x?.findings?.blocker ?? 0) + (y?.findings?.blocker ?? 0), major: (x?.findings?.major ?? 0) + (y?.findings?.major ?? 0), minor: (x?.findings?.minor ?? 0) + (y?.findings?.minor ?? 0) } : undefined;
+    out.reviews[k] = compact({ dispatches: (x?.dispatches ?? 0) + (y?.dispatches ?? 0), nonzero_exit: (x?.nonzero_exit ?? 0) + (y?.nonzero_exit ?? 0), findings });
+  }
+  for (const k of new Set([...Object.keys(a.spec_writes), ...Object.keys(b.spec_writes)]) as Set<PhaseKey>) {
+    const x = a.spec_writes[k], y = b.spec_writes[k]; out.spec_writes[k] = { count: (x?.count ?? 0) + (y?.count ?? 0), last_sha256: y?.last_sha256 ?? x?.last_sha256 ?? "" };
+  }
+  for (const g of Object.keys(out.gates) as (keyof Gates)[]) out.gates[g] = a.gates[g] + b.gates[g];
+  out.conformance_loops = a.conformance_loops + b.conformance_loops; out.conformance_open_gaps = b.conformance_open_gaps ?? a.conformance_open_gaps; out.amendments = a.amendments + b.amendments;
+  out.spec_edits_after_ship = a.spec_edits_after_ship + b.spec_edits_after_ship; out.events_dropped = a.events_dropped + b.events_dropped;
+  return out;
+}
+
+export interface DiffSummary { base: string; commits: number; buckets: Record<string, BucketStat> }
+export interface Derived {
+  duration_s: number; phases: Partial<Record<PhaseKey, PhaseAcc & { started_at?: string; completed_at?: string; duration_s?: number; model?: string; thinking?: string }>>;
+  personas: Record<string, PersonaAcc>; reviews?: Record<string, ReviewAcc>; conformance_loops: number; conformance_open_gaps?: number; gates: Gates & { ship_option?: string };
+  plan?: { tasks: number; complete: number; failed: number; skipped: number }; tests?: { command: string; result: "pass" | "fail" }; amendments: number;
+  spec_edits_after_ship: number; diff?: DiffSummary; modified_files?: string[]; spec_writes: Accumulators["spec_writes"]; events_dropped: number;
+}
+export type RecordStatus = "in_progress" | "shipped" | "abandoned";
+export interface TelemetryRecord {
+  schema: 1; spec: string; run_id: string; branch?: string; status: RecordStatus; created_at: string; approved_at?: string; shipped_at?: string; abandoned_at?: string;
+  supersedes?: string[]; fixes?: string[]; versions?: Record<string, string>; author?: { name?: string; email?: string }; agent_overrides?: Record<string, unknown>;
+  sessions: string[]; derived: Derived; accumulators: Record<string, Accumulators>; events: TelemetryEvent[];
+}
+export function newRecord(o: { spec: string; session: string; now: string; runId: string; branch?: string }): TelemetryRecord {
+  return { schema: 1, spec: o.spec, run_id: o.runId, branch: o.branch, status: "in_progress", created_at: o.now, sessions: [o.session], derived: { duration_s: 0, phases: {}, personas: {}, conformance_loops: 0, gates: { spec_rounds: 0, plan_rounds: 0, fix_round_grants: 0, task_reopens: 0 }, amendments: 0, spec_edits_after_ship: 0, spec_writes: {}, events_dropped: 0 }, accumulators: {}, events: [] };
+}
+export const totalAccumulators = (rec: TelemetryRecord): Accumulators => Object.values(rec.accumulators).reduce<Accumulators>((acc, block) => foldAccumulators(acc, block), emptyAccumulators());
+const seconds = (a: string, b: string): number => Math.max(0, Math.round((Date.parse(b) - Date.parse(a)) / 1000));
+export function liveShipEvent(events: TelemetryEvent[]): (TelemetryEvent & { kind: "ship" }) | undefined {
+  let live: (TelemetryEvent & { kind: "ship" }) | undefined;
+  for (const e of events) { if (e.kind === "ship") live = e; else if (e.kind === "ship_failed") live = undefined; }
+  return live;
+}
+export function derive(rec: TelemetryRecord, now: string): Derived {
+  const acc = totalAccumulators(rec), phases: Derived["phases"] = {};
+  for (const e of rec.events) {
+    if (e.kind !== "phase") continue;
+    if (e.action === "reset") { for (const p of PHASES) if (phases[p]) phases[p] = compact({ ...phases[p], started_at: undefined, completed_at: undefined, duration_s: undefined, model: undefined, thinking: undefined }); continue; }
+    if (!e.name) continue;
+    const cur = phases[e.name] ?? {};
+    if (e.action === "start") phases[e.name] = compact({ ...cur, started_at: e.ts, completed_at: undefined, duration_s: undefined, model: e.model, thinking: e.thinking });
+    else if (cur.started_at) phases[e.name] = { ...cur, completed_at: e.ts, duration_s: seconds(cur.started_at, e.ts) };
+  }
+  for (const k of Object.keys(acc.phases) as PhaseKey[]) phases[k] = compact({ ...(phases[k] ?? {}), ...acc.phases[k] });
+  const live = liveShipEvent(rec.events);
+  return compact({ duration_s: seconds(rec.created_at, rec.shipped_at ?? rec.abandoned_at ?? now), phases, personas: acc.personas, reviews: Object.keys(acc.reviews).length ? acc.reviews : undefined, conformance_loops: acc.conformance_loops, conformance_open_gaps: acc.conformance_open_gaps, gates: compact({ ...acc.gates, ship_option: live?.option }), plan: rec.derived.plan, tests: rec.derived.tests, amendments: acc.amendments, spec_edits_after_ship: acc.spec_edits_after_ship, diff: rec.derived.diff, modified_files: rec.derived.modified_files, spec_writes: acc.spec_writes, events_dropped: acc.events_dropped }) as Derived;
+}
+
+const stripUndefined = (v: unknown): unknown => {
+  if (Array.isArray(v)) return v.map(stripUndefined);
+  if (v && typeof v === "object") return Object.fromEntries(Object.entries(v as object).filter(([, x]) => x !== undefined).map(([k, x]) => [k, stripUndefined(x)]));
+  return v;
+};
+const flowLeafChildren = (map: YAMLMap, blockLists: Set<string> = new Set()): void => {
+  for (const pair of map.items) {
+    const key = String(pair.key);
+    const child = pair.value;
+    if (!isCollection(child) || blockLists.has(key)) continue;
+    if (isMap(child) && child.items.length > 0 && child.items.every((item) => isMap(item.value))) {
+      for (const item of child.items) if (isCollection(item.value)) item.value.flow = true;
+    } else {
+      child.flow = true;
+    }
+  }
+};
+const flowModelLists = (node: unknown): void => {
+  if (isMap(node)) {
+    for (const pair of node.items) {
+      if (String(pair.key) === "models" && isSeq(pair.value)) pair.value.flow = true;
+      flowModelLists(pair.value);
+    }
+  } else if (isSeq(node)) {
+    for (const item of node.items) flowModelLists(item);
+  }
+};
+export function serializeRecord(rec: TelemetryRecord): string {
+  const { derived, accumulators, events, ...head } = rec;
+  const body = stripUndefined({ ...head, derived, accumulators }) as Record<string, unknown>;
+  const doc = new Document(body);
+  const derivedNode = doc.get("derived", true);
+  if (isMap(derivedNode)) flowLeafChildren(derivedNode, new Set(["modified_files"]));
+  const accumulatorNode = doc.get("accumulators", true);
+  if (isMap(accumulatorNode)) {
+    for (const session of accumulatorNode.items) if (isMap(session.value)) flowLeafChildren(session.value);
+  }
+  flowModelLists(doc.contents);
+  const bodyText = doc.toString({ lineWidth: 0 });
+  const eventLines = (events as unknown as Record<string, unknown>[]).map((e) => "  - " + stringifyYaml(stripUndefined(e), { collectionStyle: "flow", lineWidth: 0 }).trim());
+  return bodyText + "events:\n" + (eventLines.length ? eventLines.join("\n") + "\n" : "");
+}
+export function parseRecord(text: string): TelemetryRecord | undefined {
+  let doc: unknown;
+  try { doc = parseYaml(text); } catch { return undefined; }
+  if (!doc || typeof doc !== "object") return undefined;
+  const d = doc as Partial<TelemetryRecord>;
+  if (d.schema !== 1 || typeof d.spec !== "string" || typeof d.run_id !== "string") return undefined;
+  const accumulators = Object.fromEntries(Object.entries(d.accumulators ?? {}).flatMap(([session, block]) =>
+    block && typeof block === "object" && !Array.isArray(block)
+      ? [[session, { ...emptyAccumulators(), ...block }]]
+      : []
+  )) as Record<string, Accumulators>;
+  return { ...(d as TelemetryRecord), sessions: Array.isArray(d.sessions) ? d.sessions : [], derived: d.derived ?? newRecord({ spec: d.spec, session: "", now: d.created_at ?? "", runId: d.run_id }).derived, accumulators, events: Array.isArray(d.events) ? d.events : [] };
+}

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

@@ -0,0 +1,23 @@
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import { BASE_REFS, guardReason, modifiedFilesFrom } from "./telemetry-ship.ts";
+
+test("guardReason names spec, timestamp and record path", () => {
+  assert.equal(
+    guardReason("doc/specs/a.md", "2026-09-17T12:00:00Z", ".pi/gauntlet/telemetry/doc/specs/a.yaml"),
+    "spec doc/specs/a.md shipped at 2026-09-17T12:00:00Z (record .pi/gauntlet/telemetry/doc/specs/a.yaml). Write a new date-slugged spec that supersedes it instead of reusing this file.",
+  );
+});
+
+test("modifiedFilesFrom drops the spec, doc/plans/**, and the telemetry dir; sorts", () => {
+  const names = "extensions/telemetry.ts\nextensions/telemetry.test.ts\ndoc/specs/a.md\ndoc/plans/a.md\nsvc/doc/plans/b.md\n.pi/gauntlet/telemetry/doc/specs/a.yaml\nREADME.md\n\n";
+  assert.deepEqual(modifiedFilesFrom(names, "doc/specs/a.md", ".pi/gauntlet/telemetry"), ["README.md", "extensions/telemetry.test.ts", "extensions/telemetry.ts"]);
+  assert.deepEqual(modifiedFilesFrom("", "doc/specs/a.md", "t/"), []);
+  // Filenames with leading or trailing whitespace must be kept verbatim
+  const namesWithWhitespace = " lead.ts\ntrail.ts \nREADME.md\n";
+  assert.deepEqual(modifiedFilesFrom(namesWithWhitespace, "doc/specs/a.md", "t/"), [" lead.ts", "README.md", "trail.ts "]);
+});
+
+test("BASE_REFS order is origin/HEAD, main, master", () => {
+  assert.deepEqual(BASE_REFS, ["origin/HEAD", "main", "master"]);
+});

package/extensions/lib/telemetry-ship.ts

@@ -0,0 +1,17 @@
+// Pure ship-time helpers for the telemetry extension (#33): diff file filter,
+// base-ref candidates, guard block reason.
+
+export const BASE_REFS = ["origin/HEAD", "main", "master"] as const;
+
+export const guardReason = (spec: string, shippedAt: string, recordRel: string): string =>
+  `spec ${spec} shipped at ${shippedAt} (record ${recordRel}). Write a new date-slugged spec that supersedes it instead of reusing this file.`;
+
+// derived.modified_files: `git diff --name-only <base>...HEAD` output minus the bound
+// spec, doc/plans/**, and <dir>/**; sorted repo-relative paths (renames -> new path).
+export function modifiedFilesFrom(nameOnly: string, spec: string, dir: string): string[] {
+  const dirPrefix = dir.replace(/\/+$/, "") + "/";
+  return nameOnly
+    .split("\n")
+    .filter((f) => f && f !== spec && !/(^|\/)doc\/plans\//.test(f) && !f.startsWith(dirPrefix))
+    .sort();
+}