pi-gauntlet 5.20.0 → 5.22.0

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

@@ -0,0 +1,91 @@
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import { buildCouncil, memberSlugOf, normalizeRaisedBy, parseAudit, parseChairReport, resolveMembers, slug } from "./telemetry-council.ts";
+
+const zero = { blocker: 0, major: 0, minor: 0 };
+test("slug and member filename normalization", () => {
+  assert.equal(slug("p/alpha:xhigh"), "p-alpha-xhigh");
+  assert.equal(memberSlugOf("/tmp/retry/member-2-p-beta-high.md"), "p-beta-high");
+  assert.equal(memberSlugOf("/tmp/member-0-p-alpha"), "p-alpha");
+  assert.equal(memberSlugOf(undefined), undefined);
+  assert.equal(memberSlugOf("chair.md"), undefined);
+  assert.equal(normalizeRaisedBy("member-0-p-alpha"), "p-alpha");
+  assert.equal(normalizeRaisedBy("p-alpha.md"), "p-alpha");
+  assert.equal(normalizeRaisedBy(" p/alpha:xhigh "), "p-alpha-xhigh");
+});
+const chairText = [
+  "consensus: needs-work",
+  "clusters:",
+  "- [blocker] issue — raised-by: [p-alpha] — fix",
+  "- [Major] issue - raised-by: [p-alpha, p-beta-high, p-alpha] - fix",
+  "- [minor] issue -- raised-by: [p-beta-high] -- cut",
+  "resolved:",
+  "- [blocker] ignored — raised-by: [nobody]",
+].join("\n");
+test("chair clusters parse only before resolved and require attributes", () => {
+  assert.deepEqual(parseChairReport(chairText), { clusters: [
+    { severity: "blocker", raisedBy: ["p-alpha"] },
+    { severity: "major", raisedBy: ["p-alpha", "p-beta-high"] },
+    { severity: "minor", raisedBy: ["p-beta-high"] },
+  ] });
+  assert.equal(parseChairReport("clusters:\n"), null);
+  assert.equal(parseChairReport("consensus: x\n"), null);
+  assert.deepEqual(parseChairReport("consensus: sound\nclusters:\nresolved:\n"), { clusters: [] });
+  assert.equal(parseChairReport("consensus: x\nclusters:\n- [major] no raiser"), null);
+});
+const auditText = [
+  "Applied: [blocker] issue — raised-by: [p-alpha] -> fix",
+  "- Applied: [major] over-spec — raised-by: [p-alpha, p-beta-high] -> cut",
+  "Applied: [minor] issue — raised-by: [p-beta-high] -> open question (missing)",
+  "Deferred: [major] x — raised-by: [p-alpha] -> later",
+  "Rejected: [minor] issue — raised-by: [p-beta-high] -> no",
+].join("\n");
+test("audit reads dispositions, none and cut/open question", () => {
+  assert.deepEqual(parseAudit(auditText), [
+    { disposition: "applied", severity: "blocker", raisedBy: ["p-alpha"] },
+    { disposition: "applied", severity: "major", raisedBy: ["p-alpha", "p-beta-high"] },
+    { disposition: "applied", severity: "minor", raisedBy: ["p-beta-high"] },
+    { disposition: "deferred", severity: "major", raisedBy: ["p-alpha"] },
+    { disposition: "rejected", severity: "minor", raisedBy: ["p-beta-high"] },
+  ]);
+  assert.equal(parseAudit("Applied: [major] x — raised-by: [p-alpha]\nDeferred: none"), null);
+  assert.equal(parseAudit("Applied: x — raised-by: [p-alpha]\nDeferred: none\nRejected: none"), null);
+  assert.equal(parseAudit("Applied: [major] x\nDeferred: none\nRejected: none"), null);
+  assert.deepEqual(parseAudit("Applied: none\nDeferred: none\nRejected: none"), []);
+});
+const results = [
+  { model: "p/alpha:xhigh", exitCode: 0, savedOutputPath: "/tmp/member-0-p-alpha.md" },
+  { model: "p/beta:high", exitCode: 1 },
+  { model: "p/beta:high", exitCode: 0, savedOutputPath: "/tmp/retry/member-1-p-beta-high.md" },
+];
+test("member retry counts dispatches and ambiguous slug fails", () => {
+  const members = resolveMembers(results)!;
+  assert.deepEqual([...members.dispatches], [["p/alpha:xhigh", 1], ["p/beta:high", 2]]);
+  assert.deepEqual([...members.slugToModel], [["p-alpha", "p/alpha:xhigh"], ["p-beta-high", "p/beta:high"]]);
+  assert.equal(resolveMembers([...results, { model: "p/other", exitCode: 0, savedOutputPath: "/tmp/member-3-p-alpha.md" }]), null);
+  assert.deepEqual([...resolveMembers([{ exitCode: 0, savedOutputPath: "/tmp/member-0-x.md" }])!.dispatches], []);
+});
+const clusters = [{ severity: "blocker" as const, raisedBy: ["p-alpha"] }, { severity: "major" as const, raisedBy: ["p-alpha", "p-beta-high"] }, { severity: "minor" as const, raisedBy: ["p-beta-high"] }];
+const audit = [{ disposition: "applied" as const, severity: "blocker" as const, raisedBy: ["p-alpha"] }, { disposition: "deferred" as const, severity: "major" as const, raisedBy: ["p-beta-high", "p-alpha"] }, { disposition: "rejected" as const, severity: "minor" as const, raisedBy: ["p-beta-high"] }];
+const input = () => ({ chair: { model: "p/chair:medium", dispatches: 2, clusters }, members: resolveMembers(results)!, audit });
+test("council joins multiset and counts each severity per member", () => {
+  const block = buildCouncil(input())!;
+  assert.deepEqual(block.chair, { model: "p/chair:medium", dispatches: 2, clusters: 3, members_reported: 2 });
+  assert.deepEqual(block.members["p/alpha:xhigh"], { dispatches: 1, total: { blocker: 1, major: 1, minor: 0 }, unique: { blocker: 1, major: 0, minor: 0 }, applied: { blocker: 1, major: 0, minor: 0 }, unique_applied: { blocker: 1, major: 0, minor: 0 }, deferred: { blocker: 0, major: 1, minor: 0 }, rejected: zero });
+  assert.deepEqual(block.members["p/beta:high"], { dispatches: 2, total: { blocker: 0, major: 1, minor: 1 }, unique: { blocker: 0, major: 0, minor: 1 }, applied: zero, unique_applied: zero, deferred: { blocker: 0, major: 1, minor: 0 }, rejected: { blocker: 0, major: 0, minor: 1 } });
+  for (const member of Object.values(block.members)) for (const severity of ["blocker", "major", "minor"] as const) assert.equal(member.total[severity], member.applied[severity] + member.deferred[severity] + member.rejected[severity]);
+});
+test("zero-member and zero-finding completeness", () => {
+  const members = resolveMembers([...results, { model: "p/gamma:high", exitCode: 0, savedOutputPath: "/tmp/member-2-p-gamma-high.md" }])!;
+  const block = buildCouncil({ ...input(), members })!;
+  assert.deepEqual(block.members["p/gamma:high"], { dispatches: 1, total: zero, unique: zero, applied: zero, unique_applied: zero, deferred: zero, rejected: zero });
+  assert.equal(block.chair.members_reported, 2);
+  assert.deepEqual(buildCouncil({ ...input(), chair: { model: "p/chair:medium", dispatches: 1, clusters: [] }, audit: [] })!.chair, { model: "p/chair:medium", dispatches: 1, clusters: 0, members_reported: 0 });
+});
+test("incomplete batches return null", () => {
+  assert.equal(buildCouncil({ ...input(), audit: [...audit, { disposition: "rejected", severity: "minor", raisedBy: ["p-nobody"] }] }), null);
+  assert.equal(buildCouncil({ ...input(), chair: { ...input().chair, clusters: [...clusters, { severity: "minor", raisedBy: ["p-nobody"] }] } }), null);
+  assert.equal(buildCouncil({ ...input(), audit: [...audit, { disposition: "rejected", severity: "minor", raisedBy: ["p-alpha"] }] }), null);
+  assert.equal(buildCouncil({ ...input(), audit: audit.slice(0, 2) }), null);
+  assert.equal(buildCouncil({ ...input(), audit: [{ ...audit[0], severity: "major" }, audit[1], audit[2]] }), null);
+});

package/extensions/lib/telemetry-council.ts

@@ -0,0 +1,121 @@
+export type Severity = "blocker" | "major" | "minor";
+export type Disposition = "applied" | "deferred" | "rejected";
+export type SeverityCounts = Record<Severity, number>;
+export interface Cluster { severity: Severity; raisedBy: string[] }
+export interface AuditItem extends Cluster { disposition: Disposition }
+export interface CouncilMember {
+  dispatches: number; total: SeverityCounts; unique: SeverityCounts; applied: SeverityCounts;
+  unique_applied: SeverityCounts; deferred: SeverityCounts; rejected: SeverityCounts;
+}
+export interface CouncilBlock {
+  chair: { model: string; dispatches: number; clusters: number; members_reported: number };
+  members: Record<string, CouncilMember>;
+}
+export interface MemberResult { model?: string; exitCode?: number; savedOutputPath?: string }
+export interface ResolvedMembers { dispatches: Map<string, number>; slugToModel: Map<string, string> }
+const zero = (): SeverityCounts => ({ blocker: 0, major: 0, minor: 0 });
+export const slug = (model: string): string => model.replace(/[^A-Za-z0-9]/g, "-");
+export function memberSlugOf(path: string | undefined): string | undefined {
+  if (!path) return undefined;
+  return /^member-\d+-(.+?)(\.md)?$/.exec(path.split(/[\\/]/).pop() ?? "")?.[1];
+}
+export const normalizeRaisedBy = (token: string): string => slug(token.trim().replace(/^member-\d+-/, "").replace(/\.md$/, ""));
+const attributes = (line: string): Cluster | undefined => {
+  const severity = /\[(blocker|major|minor)\]/i.exec(line);
+  const raisers = /raised-by:\s*\[([^\]]*)\]/i.exec(line);
+  if (!severity || !raisers) return undefined;
+  const raisedBy = [...new Set(raisers[1].split(",").map(normalizeRaisedBy).filter((x) => x && x !== "-"))];
+  return raisedBy.length ? { severity: severity[1].toLowerCase() as Severity, raisedBy } : undefined;
+};
+export function parseChairReport(text: string): { clusters: Cluster[] } | null {
+  if (!/^consensus:/m.test(text)) return null;
+  const lines = text.split("\n");
+  const start = lines.findIndex((line) => /^clusters:\s*$/.test(line));
+  if (start < 0) return null;
+  const clusters: Cluster[] = [];
+  for (const line of lines.slice(start + 1)) {
+    if (/^resolved:/.test(line)) break;
+    if (!/^\s*[-*]\s+/.test(line)) continue;
+    const item = attributes(line);
+    if (!item) return null;
+    clusters.push(item);
+  }
+  return { clusters };
+}
+export function parseAudit(text: string): AuditItem[] | null {
+  const seen = new Set<string>();
+  const items: AuditItem[] = [];
+  for (const line of text.split("\n")) {
+    const match = /^\s*(?:[-*]\s*)?(Applied|Deferred|Rejected):\s*(.*)$/.exec(line);
+    if (!match) continue;
+    const disposition = match[1].toLowerCase() as Disposition;
+    seen.add(disposition);
+    if (match[2].trim().toLowerCase() === "none") continue;
+    const item = attributes(match[2]);
+    if (!item) return null;
+    items.push({ disposition, ...item });
+  }
+  return seen.size === 3 ? items : null;
+}
+export function resolveMembers(results: MemberResult[]): ResolvedMembers | null {
+  const dispatches = new Map<string, number>();
+  const slugToModel = new Map<string, string>();
+  for (const result of results) {
+    if (typeof result.model !== "string") continue;
+    dispatches.set(result.model, (dispatches.get(result.model) ?? 0) + 1);
+    const memberSlug = result.exitCode === 0 ? memberSlugOf(result.savedOutputPath) : undefined;
+    if (!memberSlug) continue;
+    const previous = slugToModel.get(memberSlug);
+    if (previous !== undefined && previous !== result.model) return null;
+    slugToModel.set(memberSlug, result.model);
+  }
+  return { dispatches, slugToModel };
+}
+export interface CouncilInput {
+  chair: { model: string; dispatches: number; clusters: Cluster[] };
+  members: ResolvedMembers;
+  audit: AuditItem[];
+}
+export function buildCouncil(input: CouncilInput): CouncilBlock | null {
+  const resolve = (slugs: string[]): string[] | undefined => {
+    const models = new Set<string>();
+    for (const memberSlug of slugs) {
+      const model = input.members.slugToModel.get(memberSlug);
+      if (model === undefined) return undefined;
+      models.add(model);
+    }
+    return [...models].sort();
+  };
+  const key = (severity: Severity, models: string[]) => JSON.stringify([severity, models]);
+  const reported = new Set<string>();
+  const clusterKeys: string[] = [];
+  for (const cluster of input.chair.clusters) {
+    const models = resolve(cluster.raisedBy);
+    if (!models) return null;
+    for (const model of models) reported.add(model);
+    clusterKeys.push(key(cluster.severity, models));
+  }
+  const resolvedAudit: { item: AuditItem; models: string[] }[] = [];
+  for (const item of input.audit) {
+    const models = resolve(item.raisedBy);
+    if (!models) return null;
+    resolvedAudit.push({ item, models });
+  }
+  if (JSON.stringify(clusterKeys.sort()) !== JSON.stringify(resolvedAudit.map(({ item, models }) => key(item.severity, models)).sort())) return null;
+  const members: Record<string, CouncilMember> = {};
+  for (const [model, dispatches] of [...input.members.dispatches].sort(([a], [b]) => a.localeCompare(b))) {
+    members[model] = { dispatches, total: zero(), unique: zero(), applied: zero(), unique_applied: zero(), deferred: zero(), rejected: zero() };
+  }
+  for (const { item, models } of resolvedAudit) {
+    for (const model of models) {
+      const member = members[model];
+      member.total[item.severity]++;
+      member[item.disposition][item.severity]++;
+      if (models.length === 1) {
+        member.unique[item.severity]++;
+        if (item.disposition === "applied") member.unique_applied[item.severity]++;
+      }
+    }
+  }
+  return { chair: { model: input.chair.model, dispatches: input.chair.dispatches, clusters: input.chair.clusters.length, members_reported: reported.size }, members };
+}

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

@@ -4,6 +4,7 @@ import {
   capEvents, derive, diffPhases, emptyAccumulators, emptyPhases, foldAccumulators, implementAutoCompletes,
   newRecord, parseRecord, serializeRecord, type Accumulators, type TelemetryEvent,
 } from "./telemetry-record.ts";
+import type { CouncilBlock } from "./telemetry-council.ts";
 
 const ev = (over: Partial<TelemetryEvent> & { kind: string }): TelemetryEvent =>
   ({ ts: "2026-09-17T10:00:00Z", session: "s1", phase: "unphased", ...over }) as TelemetryEvent;
@@ -165,3 +166,28 @@ test("parseRecord drops malformed accumulator blocks and fills missing fields",
   assert.equal(derive(parsed, "2026-09-17T10:01:00Z").amendments, 2);
 });
 
+const COUNCIL: CouncilBlock = {
+  chair: { model: "p/chair:medium", dispatches: 1, clusters: 2, members_reported: 2 },
+  members: {
+    "p/alpha:xhigh": { dispatches: 1, total: { blocker: 0, major: 1, minor: 1 }, unique: { blocker: 0, major: 1, minor: 0 }, applied: { blocker: 0, major: 1, minor: 0 }, unique_applied: { blocker: 0, major: 1, minor: 0 }, deferred: { blocker: 0, major: 0, minor: 0 }, rejected: { blocker: 0, major: 0, minor: 1 } },
+    "p/beta:high": { dispatches: 2, total: { blocker: 0, major: 0, minor: 1 }, unique: { blocker: 0, major: 0, minor: 0 }, applied: { blocker: 0, major: 0, minor: 0 }, unique_applied: { blocker: 0, major: 0, minor: 0 }, deferred: { blocker: 0, major: 0, minor: 0 }, rejected: { blocker: 0, major: 0, minor: 1 } },
+  },
+};
+
+test("derive carries derived.council through like tests/diff; absent stays absent", () => {
+  const rec = newRecord({ spec: "doc/specs/a.md", session: "s1", now: "2026-09-17T10:00:00Z", runId: "r1" });
+  assert.equal(derive(rec, "2026-09-17T10:01:00Z").council, undefined);
+  rec.derived.council = COUNCIL;
+  assert.deepEqual(derive(rec, "2026-09-17T10:01:00Z").council, COUNCIL);
+});
+
+test("serializeRecord writes council.chair and each member as flow maps under block keys; parseRecord round-trips", () => {
+  const rec = newRecord({ spec: "doc/specs/a.md", session: "s1", now: "2026-09-17T10:00:00Z", runId: "r1" });
+  rec.derived.council = COUNCIL;
+  const text = serializeRecord(rec);
+  assert.match(text, /^  council:\n    chair: \{ model: p\/chair:medium, dispatches: 1, clusters: 2, members_reported: 2 \}\n    members:\n      p\/alpha:xhigh: \{ dispatches: 1, total: \{ blocker: 0, major: 1, minor: 1 \}/m);
+  assert.match(text, /^      p\/beta:high: \{ dispatches: 2, /m);
+  assert.deepEqual(parseRecord(text)!.derived.council, COUNCIL);
+  const plain = newRecord({ spec: "doc/specs/a.md", session: "s1", now: "2026-09-17T10:00:00Z", runId: "r2" });
+  assert.equal(parseRecord(serializeRecord(plain))!.derived.council, undefined);
+});

package/extensions/lib/telemetry-record.ts

@@ -1,6 +1,7 @@
 // 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";
+import type { CouncilBlock } from "./telemetry-council.ts";
 
 export const PHASES = ["brainstorm", "plan", "implement", "verify", "ship"] as const;
 export type Phase = (typeof PHASES)[number];
@@ -91,7 +92,7 @@ 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;
+  spec_edits_after_ship: number; diff?: DiffSummary; modified_files?: string[]; council?: CouncilBlock; spec_writes: Accumulators["spec_writes"]; events_dropped: number;
 }
 export type RecordStatus = "in_progress" | "shipped" | "abandoned";
 export interface TelemetryRecord {
@@ -121,7 +122,7 @@ export function derive(rec: TelemetryRecord, now: string): Derived {
   }
   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;
+  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, council: rec.derived.council, spec_writes: acc.spec_writes, events_dropped: acc.events_dropped }) as Derived;
 }
 
 const stripUndefined = (v: unknown): unknown => {
@@ -156,7 +157,11 @@ export function serializeRecord(rec: TelemetryRecord): string {
   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"]));
+  if (isMap(derivedNode)) {
+    flowLeafChildren(derivedNode, new Set(["modified_files", "council"]));
+    const council = derivedNode.get("council", true);
+    if (isMap(council)) flowLeafChildren(council);
+  }
   const accumulatorNode = doc.get("accumulators", true);
   if (isMap(accumulatorNode)) {
     for (const session of accumulatorNode.items) if (isMap(session.value)) flowLeafChildren(session.value);

package/extensions/telemetry.test.ts

@@ -511,6 +511,96 @@
 
   const subagentResult = (results: unknown[], content = "") => ({ toolName: "subagent", toolCallId: "sa", input: {}, content: [{ type: "text", text: content }], isError: false, details: { results } });
 
+  async function boundInBrainstorm() {
+    const h = harness();
+    await h.phaseResult("start", P({ brainstorm: "in_progress" }));
+    await h.writeSpec("doc/specs/a.md");
+    return h;
+  }
+  const memberBatch = (isError = false) => ({ ...subagentResult([
+    { agent: "spec-council-member", exitCode: 0, model: "p/alpha:xhigh", savedOutputPath: "/tmp/c/member-0-p-alpha.md", usage: usage(1) },
+    { agent: "spec-council-member", exitCode: 1, model: "p/beta:high", usage: usage(1) },
+    { agent: "spec-council-member", exitCode: 0, model: "p/beta:high", savedOutputPath: "/tmp/c/retry/member-1-p-beta-high.md", usage: usage(1) },
+  ]), isError });
+  const CHAIR_TEXT = "consensus: needs-work\nclusters:\n- [major] a - raised-by: [p-alpha] - x\n- [minor] b - raised-by: [p-alpha, p-beta-high] - x\nresolved:\n";
+  const chairResult = (text = CHAIR_TEXT, exitCode = 0) => ({ ...subagentResult([{ agent: "spec-council-synthesizer", exitCode, model: "p/chair:medium", usage: usage(1) }], text), isError: exitCode !== 0 });
+  const AUDIT_TEXT = "Applied: [major] a - raised-by: [p-alpha] -> edit\nDeferred: none\nRejected: [minor] b - raised-by: [p-alpha, p-beta-high] -> reason";
+  const assistant = (text: string) => ({ type: "message_end", message: { role: "assistant", usage: usage(1), content: [{ type: "text", text }] } });
+  const counts = (major = 0, minor = 0) => ({ blocker: 0, major, minor });
+  const EXPECTED_COUNCIL = {
+    chair: { model: "p/chair:medium", dispatches: 1, clusters: 2, members_reported: 2 },
+    members: {
+      "p/alpha:xhigh": { dispatches: 1, total: counts(1, 1), unique: counts(1), applied: counts(1), unique_applied: counts(1), deferred: counts(), rejected: counts(0, 1) },
+      "p/beta:high": { dispatches: 2, total: counts(0, 1), unique: counts(), applied: counts(), unique_applied: counts(), deferred: counts(), rejected: counts(0, 1) },
+    },
+  };
+
+  test("council captures failed member batch, chair, audit and persists on later flush", async () => {
+    const h = await boundInBrainstorm();
+    await h.emit("tool_result", memberBatch(true));
+    await h.emit("tool_result", chairResult());
+    assert.equal(h.readRecord().derived.council, undefined);
+    await h.emit("message_end", assistant(AUDIT_TEXT));
+    assert.deepEqual(h.readRecord().derived.council, EXPECTED_COUNCIL);
+    await h.phaseResult("complete", P({ brainstorm: "complete" }));
+    assert.deepEqual(h.readRecord().derived.council, EXPECTED_COUNCIL);
+    assert.equal(h.readRecord().derived.personas["spec-council-member"], undefined);
+  });
+  test("council defaults missing chair model and survives unrelated result before audit", async () => {
+    const h = await boundInBrainstorm();
+    await h.emit("tool_result", memberBatch());
+    await h.emit("tool_result", subagentResult([{ agent: "spec-council-synthesizer", exitCode: 0, usage: usage(1) }], CHAIR_TEXT));
+    await h.emit("tool_result", subagentResult([{ agent: "spec-summarizer", exitCode: 0, model: "p/s", usage: usage(1) }]));
+    await h.emit("message_end", assistant(AUDIT_TEXT));
+    assert.deepEqual(h.readRecord().derived.council, { ...EXPECTED_COUNCIL, chair: { ...EXPECTED_COUNCIL.chair, model: "unknown" } });
+  });
+  test("council ignores plan phase", async () => {
+    const h = await boundInPlan();
+    await h.emit("tool_result", memberBatch());
+    await h.emit("tool_result", chairResult());
+    await h.emit("message_end", assistant(AUDIT_TEXT));
+    assert.equal(h.readRecord().derived.council, undefined);
+  });
+  test("council counts failed chair retries and retains last usable clusters", async () => {
+    const h = await boundInBrainstorm();
+    await h.emit("tool_result", memberBatch());
+    await h.emit("tool_result", chairResult("Failed", 1));
+    await h.emit("tool_result", chairResult());
+    await h.emit("tool_result", chairResult("no consensus here", 1));
+    await h.emit("message_end", assistant(AUDIT_TEXT));
+    assert.deepEqual(h.readRecord().derived.council!.chair, { ...EXPECTED_COUNCIL.chair, dispatches: 3 });
+  });
+  test("council retains pending on incomplete audit and ignores audit before chair", async () => {
+    const h = await boundInBrainstorm();
+    await h.emit("message_end", assistant(AUDIT_TEXT));
+    await h.emit("tool_result", memberBatch());
+    await h.emit("tool_result", chairResult());
+    await h.emit("message_end", assistant("Applied: [major] a - raised-by: [p-alpha] -> edit\nDeferred: none\nRejected: none"));
+    assert.equal(h.readRecord().derived.council, undefined);
+    await h.emit("message_end", assistant("Applied: a -> edit\nDeferred: none\nRejected: none"));
+    assert.equal(h.readRecord().derived.council, undefined);
+    await h.emit("message_end", assistant(AUDIT_TEXT));
+    assert.deepEqual(h.readRecord().derived.council, EXPECTED_COUNCIL);
+  });
+  test("council reset clears pending and new member batch supersedes held chair", async () => {
+    const h = await boundInBrainstorm();
+    await h.emit("tool_result", memberBatch());
+    await h.emit("tool_result", chairResult());
+    await h.phaseResult("reset", P());
+    await h.phaseResult("start", P({ brainstorm: "in_progress" }));
+    await h.writeSpec("doc/specs/a.md");
+    await h.emit("message_end", assistant(AUDIT_TEXT));
+    assert.equal(h.readRecord().derived.council, undefined);
+    await h.emit("tool_result", memberBatch());
+    await h.emit("tool_result", chairResult());
+    await h.emit("tool_result", memberBatch());
+    await h.emit("message_end", assistant(AUDIT_TEXT));
+    assert.equal(h.readRecord().derived.council, undefined);
+    await h.emit("tool_result", chairResult());
+    await h.emit("message_end", assistant(AUDIT_TEXT));
+    assert.deepEqual(h.readRecord().derived.council, EXPECTED_COUNCIL);
+  });
+
   test("subagent results: dispatch events, persona tokens, spec_rounds, reviews, conformance_loops; async results: [] contribute nothing", async () => {
     const h = await boundInPlan();
     await h.emit("tool_result", subagentResult([

package/extensions/telemetry.ts

@@ -24,6 +24,7 @@
   import { COUNTED_USER_PHASES, REVIEWER_AGENTS, countFindings, countOpenGaps, hasReopen, insertedText, planTotals, textOf, usageToTokens } from "./lib/telemetry-collect.ts";
   import { addTokens, capEvents, compact, currentPhase, derive, diffPhases, emptyAccumulators, emptyPhases, foldAccumulators, implementAutoCompletes, liveShipEvent, newRecord, parseRecord, serializeRecord, type Accumulators, type BaseEvent, type PhaseAcc, type PhaseKey, type PhaseMap, type TelemetryEvent, type TelemetryRecord, type Tokens } from "./lib/telemetry-record.ts";
   import { guardReason } from "./lib/telemetry-ship.ts";
+  import { buildCouncil, parseAudit, parseChairReport, resolveMembers, type Cluster, type MemberResult } from "./lib/telemetry-council.ts";
 
   // ---- deps seam -------------------------------------------------------------------
 
@@ -204,6 +205,7 @@
     let settingsWarned = false;
     let sessionId = "";
     let currentDir = "";
+    let councilPending: { memberResults: MemberResult[]; chair?: { model: string; dispatches: number; clusters?: Cluster[] } } | undefined;
 
     // Per-event settings read; undefined => this event is a no-op.
     const enabledSettings = (ctx: ExtensionContext): SettingsSnapshot | undefined => {
@@ -364,6 +366,7 @@
       record = undefined;
       recordRel = undefined;
       frozen = false;
+      councilPending = undefined;
     };
 
     const isSafeSpecLink = (link: string): boolean => {
@@ -432,6 +435,7 @@
               ? { kind: "phase", action: "reset" }
               : { kind: "phase", action: t.action, name: t.name },
         );
+        if (t.action === "start" && t.name === "brainstorm") councilPending = undefined;
         phases = details.phases;
         if (record && t.name === "brainstorm" && (t.action === "complete" || t.action === "skip")) record.approved_at ??= e.ts;
         if (record && t.name === "ship" && t.action === "complete" && checkoutVia === "jj") await onShipKeep(snap);
@@ -538,8 +542,9 @@
         }
         return onSpecInteraction(event.toolName, loc, event, snap);
       }
-      if (event.toolName === "subagent" && !event.isError) {
-        await onSubagentResult(event.details, event.content);
+      if (event.toolName === "subagent") {
+        if (phaseNow() === "brainstorm") onCouncilResults(event.details, event.content);
+        if (!event.isError) await onSubagentResult(event.details, event.content);
         return undefined;
       }
       if (event.toolName === "plan_tracker" && !event.isError) {
@@ -625,6 +630,42 @@
       acc.tokens = addTokens(acc.tokens, t);
     };
 
+    const onCouncilResults = (details: unknown, content: unknown) => {
+      const results = (details as { results?: unknown[] } | undefined)?.results;
+      if (!Array.isArray(results) || !results.length) return;
+      const typed = results.map((raw) => raw as { agent?: unknown; exitCode?: unknown; model?: unknown; savedOutputPath?: unknown });
+      if (councilPending?.chair && typed.some((r) => r.agent === "spec-council-member")) councilPending = undefined;
+      for (const r of typed) {
+        if (r.agent === "spec-council-member") {
+          (councilPending ??= { memberResults: [] }).memberResults.push({
+            model: typeof r.model === "string" ? r.model : undefined,
+            exitCode: typeof r.exitCode === "number" ? r.exitCode : undefined,
+            savedOutputPath: typeof r.savedOutputPath === "string" ? r.savedOutputPath : undefined,
+          });
+        } else if (r.agent === "spec-council-synthesizer") {
+          const chair = ((councilPending ??= { memberResults: [] }).chair ??= { model: "unknown", dispatches: 0 });
+          if (typeof r.model === "string") chair.model = r.model;
+          chair.dispatches += 1;
+          const parsed = parseChairReport(textOf(content));
+          if (parsed) chair.clusters = parsed.clusters;
+        }
+      }
+    };
+
+    const onCouncilAudit = (content: unknown) => {
+      const pending = councilPending;
+      const clusters = pending?.chair?.clusters;
+      if (!record || !pending?.chair || !clusters) return;
+      const audit = parseAudit(textOf(content));
+      if (!audit) return;
+      const members = resolveMembers(pending.memberResults);
+      const block = members && buildCouncil({ chair: { ...pending.chair, clusters }, members, audit });
+      if (!block) return;
+      record.derived.council = block;
+      councilPending = undefined;
+      flush();
+    };
+
     const onSubagentResult = async (details: unknown, content: unknown) => {
       const results = (details as { results?: unknown[] } | undefined)?.results;
       if (!Array.isArray(results) || results.length === 0) return;
@@ -723,9 +764,10 @@
     pi.on("message_end", async (event, ctx) => {
       lastCtx = ctx;
       if (!enabledSettings(ctx)) return;
-      const msg = event.message as { role?: string; usage?: unknown };
+      const msg = event.message as { role?: string; usage?: unknown; content?: unknown };
       if (msg.role !== "assistant") return;
       addPhaseTokens(usageToTokens(msg.usage));
+      if (phaseNow() === "brainstorm") onCouncilAudit(msg.content);
     });
 
     pi.on("turn_end", async (_event, ctx) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-gauntlet",
-  "version": "5.20.0",
+  "version": "5.22.0",
   "description": "Opinionated, gated workflow skills, subagent personas, and runtime extensions for the pi coding agent.",
   "author": "Jacek Juraszek",
   "type": "module",

package/skills/brainstorming/SKILL.md

@@ -44,7 +44,7 @@ Work through the items below **in order**. This is your own checklist to follow,
 4. **Understand the idea against the draft** - see [Understand the idea](#3-understand-the-idea).
 5. **Propose 2-3 approaches** - see [Explore approaches](#4-explore-approaches).
 6. **Present the design** - see [Present the design in two rounds](#6-present-the-design-in-two-rounds).
-7. **Write the spec** - follow [Spec Self-Review](#spec-self-review-before-user-review-gate) steps 1-4.
+7. **Write the spec** - follow [Spec Self-Review](#spec-self-review-before-user-review-gate) steps 1-5.
 8. **Spec self-review (lint)** - run the inline checks in [Spec Self-Review](#spec-self-review-before-user-review-gate).
 9. **Critique pass (auto-dispatched)** - use [Spec Council](#spec-council-optional).
 10. **Re-run placeholder scan** - follow [Spec Self-Review](#spec-self-review-before-user-review-gate).
@@ -163,7 +163,21 @@ Spec-writing replaces the context draft, in this exact order:
    `# CONTEXT DRAFT - NOT A SPEC - fully replaced at spec-writing` — before
    dispatching lint, critique, council, or summarizer. The phase-tracker commit
    guard is a backstop, not the primary check.
-4. **After the line-1 check and before the inline lint**, `edit` any known
+4. **After the line-1 check**, run the second predecessor pass. Compose a query from
+   the spec's H1 terms, then the terms of every H2 that is not a template heading
+   (Problem, Acceptance criteria, Design, Errors and edge cases, Tests, Documentation
+   impact, Out of scope, Open questions), then the `**Goal:**` line's terms - same
+   token rules as the scout, deduplicated, cut at 15. Run
+   `(cd <abs worktree path> && node <SPEC_INDEX> --query '<terms>' --limit 5 --exclude <spec path relative to the worktree>)`
+   with `<SPEC_INDEX>` resolved as in `gatherer.md`. Take the `live` rows and drop every
+   path the draft's `Predecessor:` line(s) named (retained from the step-1 read). Carry
+   the remainder to the gate as one adjacent line:
+   `New predecessor candidates at spec-writing: <path> (<title>), ... - index rows are a hint; code is the source and an absent row proves nothing.`
+   or `New predecessor candidates at spec-writing: none.` A non-zero exit degrades to
+   `Second predecessor pass unavailable: <first stderr line>`; it never blocks the gate
+   or the commit. "yes, <path> is a predecessor" at the gate is a change request that
+   adds the `supersedes <path>, <scope>` clause and the banner, then re-presents the gate.
+5. **After the second predecessor pass and before the inline lint**, `edit` any known
    predecessor spec to insert its supersession banner (see
    [Marking superseded specs](reference/superseding.md)). This position is fixed:
    the banner is written after any slug rename, so it always cites the final path.
@@ -238,12 +252,13 @@ Paste the summary verbatim, unedited in the template below; use adjacent lines f
 Spec written and committed to <project>/doc/specs/<filename>.md (worktree: <path>).
 
 Coverage: <N> of <M> members reported; <slug>: <reason> (line present only when coverage was partial)
-Applied: <cluster -> edit>, ...
-Deferred: <cluster -> where it belongs>, ...
-Rejected: <cluster -> one-line reason>, ...
-(omit the audit lines above when the worker path ran, not the council)
+Applied: [<severity>] <cluster> — raised-by: [<slugs>] -> <edit>
+Deferred: [<severity>] <cluster> — raised-by: [<slugs>] -> <where it belongs>
+Rejected: [<severity>] <cluster> — raised-by: [<slugs>] -> <one-line reason>
+(one line per item, exactly as returned by roasting-the-spec - `Applied: none` / `Deferred: none` / `Rejected: none` when a list is empty; omit the audit lines when the worker path ran, not the council)
 
 <unresolved ambiguities; every gap-footer entry from the summary>
+New predecessor candidates at spec-writing: <path> (<title>), ... - index rows are a hint; code is the source and an absent row proves nothing.
 
 Please review. Approve to proceed, tell me what to change in the spec, or say "revert applied council edit <X>" to undo a specific applied edit. Reply "auto-apply amends" - every later amend-class change in this flow then applies without review, scope changes included; redraws and the spec gate still stop. "approve, auto-apply amends" does both.
 ```
@@ -288,6 +303,7 @@ One question at a time, YAGNI, 2-3 approaches, two design rounds, clarify freely
 - Proposed-change execution before approval ([owner](#hard-constraint)).
 - Plan before approval; brainstorming invocation for an amend ([owner](#user-review-gate)).
 - Missing predecessor banner; invalid multi-spec split ([owner](#spec-self-review-before-user-review-gate); [owner](#2-scope-check)).
+- Gate reached without the second predecessor pass ([owner](#spec-self-review-before-user-review-gate)).
 - Approaches while a contradicted premise remains unresolved ([owner](#3-understand-the-idea)).
 - Amend without `reference/amendment-surface.md`; waiting after an amend grant; auto-applying a redraw ([owner](#amending-an-approved-spec)).
 

package/skills/brainstorming/gatherer.md

@@ -53,11 +53,13 @@ Scout (always dispatched):
 > instead; cite the old spec only for its unsuperseded sections (banner contract:
 > `reference/superseding.md`). Predecessor check: compose a 5-15 term keyword query
 > from the request (topic nouns, component names, file names - not stop words; if
-> the request is only a ticket reference, take the terms from the ticket title via
+> the request is only a ticket reference, take the terms from the ticket title and body via
 > the tracker CLI when one is available, otherwise use the fallback below). Run
 > `node <SPEC_INDEX> --query '<keywords>' --limit 10` from the worktree root,
 > keeping the keywords inside single quotes, and treat its rows as the candidate
-> list. If the command fails, fall back to listing the project's spec directory
+> list; zero rows means the index found no evidence, not that no predecessor exists -
+> judge `Predecessor: none` from the code recon. If the command fails, fall back to
+> listing the project's spec directory
 > and reading titles and `**Goal:**` lines, and write
 > `Spec index unavailable - predecessor check used directory listing.` in your
 > handoff. Either way open at
@@ -67,7 +69,8 @@ Scout (always dispatched):
 > Judge by topic; shared file paths never decide.
 > The `files` column of each candidate row is the `;`-separated list of repo-relative
 > paths that predecessor's ship modified and that still exist, or the literal `missing`,
-> or blank; do not recompute it from git or telemetry. After the `Predecessor:` line(s),
+> or blank; do not recompute it from git or telemetry. The `state` column is `live` or
+> `superseded`; cite a `superseded` row only through its successor. After the `Predecessor:` line(s),
 > and only when at least one predecessor is named, render a `Predecessor anchors`
 > section: list every attributed path exactly once, attributed to the first named
 > predecessor in index output order whose cell lists it, with no per-path commentary

package/skills/gauntlet-performance/SKILL.md

@@ -18,13 +18,14 @@ The CLI parses and aggregates; you reason. Never open a telemetry YAML record yo
 
 ## Read the digest
 
-`runs` has one row per record; `shipped*` marks a truncated run (no ship phase recorded - an older salvage stamped it at landing; its `wall` is `-` and it feeds no aggregate). `by version` groups by pi-gauntlet version: `n` counts every row, `shipped` counts the rows behind the p50/max columns. `grants` is `fix_round_grants` - the fix-round proxy (human-granted extra review rounds); schema 1 has no code-review round count.
+`runs` has one row per record; `shipped*` marks a truncated run (no ship phase recorded - an older salvage stamped it at landing; its `wall` is `-` and it feeds no aggregate). `by version` groups by pi-gauntlet version: `n` counts every row, `shipped` counts the rows behind the p50/max columns. `grants` is `fix_round_grants` - the fix-round proxy (human-granted extra review rounds); schema 1 has no code-review round count. Read `council` by roster: counts are blocker/major/minor, `uniq_appl_nonminor/run` counts unique-and-applied blocker/major findings per run, and `chair:` summarizes synthesis and retries. Read severity as the chair's consolidated severity (the highest any co-raiser assigned), not the member's own. A roster with fewer than five runs is not assessed, and older records can have no council data.
 
 ## Reply - exactly this, in this order
 
 1. **Recommendation** (2-4 sentences). One claim, led by the run that exemplifies it: quote its `spec` slug, `run_id`, and the 1-3 numbers that carry the claim. When `grants` is the evidence, call it the fix-round proxy. If no version group has `shipped >= 2`, the recommendation is "sample too small" with the `n`/`shipped` counts per version.
 2. **Cornerstones**: 3-5 bullets of aggregate facts from `by version` - corpus size, truncated count, the p50s and model tallies that moved between versions.
-3. **Menu**, numbered, at most 3 items, rendered exactly as:
+3. **Council assessment**: Render this block independently of the version sample gate, even when item 1 says "sample too small". If the digest prints `no council data in selected records`, render only `council: no data`. If the most recent roster has fewer than 5 runs, render only `council: <roster> - not enough runs to assess (N of 5)`. Otherwise render one line per `flag:` of the most recent roster as the roster-change recommendations; when an older roster exists, add one line comparing the two rosters' `uniq_appl_nonminor/run` and rejected share as groups. Compare rosters as groups, never a member across rosters.
+4. **Menu**, numbered, at most 3 items, rendered exactly as:
    - `1. render report` - ask for a target path; write markdown there: the digest verbatim, then the recommendation and cornerstones above. If the file exists, ask before overwriting. Write nothing unless this item is chosen.
    - `2. open recommendation as ticket` - hand the claim and its numbers to `/skill:shape-ticket`; never create a ticket directly.
    - `3. drill into <slug>` - re-run the CLI with `--json` and show that run's fields.

package/skills/roasting-the-spec/SKILL.md

@@ -126,7 +126,7 @@ For each cluster in the chair's report, decide one of:
 
 Also inline any `external-ref:` cluster you have context for (e.g. a ticket fetched during brainstorming) as part of the apply-set — this is your call, same as any other cluster.
 
-An `over-spec:` cluster decided **apply** is executed as deletion or shrink of the quoted clause **and** any acceptance-criteria or testing-approach line that exists only for it. Its audit line reads `Applied: over-spec: <clause> -> cut (was adds: M files / N tests / K ACs)` or `Applied: over-spec: <clause> -> shrunk to <replacement> (was adds: ...)`, so the gate shows what was removed. `defer`/`reject` are unchanged.
+An `over-spec:` cluster decided **apply** is executed as deletion or shrink of the quoted clause **and** any acceptance-criteria or testing-approach line that exists only for it. Its audit line reads `Applied: [<severity>] over-spec: <clause> — raised-by: [<slugs>] -> cut (was adds: M files / N tests / K ACs)` or `Applied: [<severity>] over-spec: <clause> — raised-by: [<slugs>] -> shrunk to <replacement> (was adds: ...)`, so the gate shows what was removed. `defer`/`reject` are unchanged.
 
 You are the advocate — decide on scope grounds — and, unlike a dispatched subagent, also the executor: you hold `edit`/`write` tools directly, so apply the edit yourself instead of proposing it for someone else to make. Do this **before** returning to brainstorming.
 
@@ -135,9 +135,9 @@ You are the advocate — decide on scope grounds — and, unlike a dispatched su
 Return a structured audit, gate-only (not a committed spec section) — a coverage line plus three labelled lists:
 
 - `Coverage:` — `N of M members reported; <slug>: <reason>` — present only when member coverage was partial; omitted at full coverage.
-- `Applied:` — one of `Applied: <cluster> -> <edit> (grounded: <member probe>)`, `Applied: <cluster> -> <edit> (probed: <check> - <result>)` for a confirmed hypothesis, `Applied: <cluster> -> open question (<not found | inconclusive: <check> | contradicted: <result>>)`. The probe rides on the audit line because member files are removed in section 5.
-- `Deferred:` — cluster -> where it belongs.
-- `Rejected:` — cluster -> one-line reason.
+- `Applied:` — one line per applied cluster: `Applied: [<severity>] <cluster> — raised-by: [<slugs>] -> <edit> (grounded: <member probe>)`, `... -> <edit> (probed: <check> - <result>)` for a confirmed hypothesis, or `... -> open question (<not found | inconclusive: <check> | contradicted: <result>>)`. Copy `[<severity>]` and `raised-by: [...]` verbatim from the cluster line - telemetry joins on them. No applied cluster -> the single line `Applied: none`. The probe rides on the audit line because member files are removed in section 5.
+- `Deferred:` — one line per deferred cluster, same `[<severity>] <cluster> — raised-by: [<slugs>]` prefix, then `-> <where it belongs>`. None -> `Deferred: none`.
+- `Rejected:` — one line per rejected cluster, same prefix, then `-> <one-line reason>`. None -> `Rejected: none`.
 
 Hand this audit to brainstorming along with the now-final spec. brainstorming writes it into the **spec commit message body** (git-native, readable pre-squash) so it survives for finish-time revert visibility, then shows it to the user alongside the final spec at its one review gate. The user can revert any applied edit there — that gate, not this skill, is where ratification happens.