pi-gauntlet 7.3.0 → 7.3.2

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## v7.3.2 - 2026-10-06
+
+### Changed
+
+- **Telemetry docs and test tightened.** `doc/configuration.md` states that council dispositions are read from any `git ... commit` command's audit lines during brainstorm (not only the heredoc shape), and the non-git telemetry test now uses a multi-line `cat` heredoc so it fails if the `git ... commit` guard is removed.
+
+## v7.3.1 - 2026-10-06
+
+### Changed
+
+- **Spec gate shows council counts, not the audit.** The brainstorming user review gate renders one `Council: <A> applied, <D> deferred, <R> rejected` line (with `; coverage <N> of <M>` on partial coverage) under the briefing and a third menu row, `3 - show council dispositions`, that prints the audit verbatim from the spec commit body and re-presents the gate without approving. The spec commit is made through a quoted heredoc (`git add -- <spec> && git commit -q -F - <<'EOF'`) so the audit lines are in the command; the `telemetry` extension records council dispositions from that command during brainstorm, with assistant text as the fallback. New `eval/spec-gate/` target (five samples, first run recorded) measures the gate render; `scripts/ci.mjs` runs its driver test.
+
 ## v7.3.0 - 2026-10-05
 
 - eval/brainstorming/replay: the live-tool replay harness code and verdict tables are committed; private inputs and transcripts are documented as non-committable.

package/extensions/telemetry.test.ts

@@ -626,6 +626,67 @@
     assert.deepEqual(h.readRecord().derived.council, EXPECTED_COUNCIL);
   });
 
+  const HEREDOC_COMMIT = (body: string) => `git -C /w commit -q -F - -- doc/specs/a.md <<'EOF'\nspec: a\n\n${body}\nEOF`;
+  const ALL_NONE = "Applied: none\nDeferred: none\nRejected: none";
+  const EMPTY_CHAIR = "consensus: sound\nclusters:\nresolved:\n";
+  test("council records the audit from the spec commit heredoc without a chat render", async () => {
+    const h = await boundInBrainstorm();
+    await h.emit("tool_result", memberBatch());
+    await h.emit("tool_result", chairResult());
+    await h.bash("c1", HEREDOC_COMMIT(AUDIT_TEXT));
+    assert.deepEqual(h.readRecord().derived.council, EXPECTED_COUNCIL);
+  });
+  test("council ignores a chat audit after the commit already recorded it", async () => {
+    const h = await boundInBrainstorm();
+    await h.emit("tool_result", memberBatch());
+    await h.emit("tool_result", chairResult());
+    await h.bash("c1", HEREDOC_COMMIT(AUDIT_TEXT));
+    const before = h.readRecord().derived.council;
+    assert.deepEqual(before, EXPECTED_COUNCIL);
+    await h.emit("message_end", assistant(AUDIT_TEXT));
+    assert.deepEqual(h.readRecord().derived.council, before);
+  });
+  test("council ignores a commit outside brainstorm or before a chair result", async () => {
+    const planned = await boundInPlan();
+    await planned.emit("tool_result", memberBatch());
+    await planned.emit("tool_result", chairResult());
+    await planned.bash("c1", HEREDOC_COMMIT(AUDIT_TEXT));
+    assert.equal(planned.readRecord().derived.council, undefined);
+    const early = await boundInBrainstorm();
+    await early.emit("tool_result", memberBatch());
+    await early.bash("c1", HEREDOC_COMMIT(AUDIT_TEXT));
+    assert.equal(early.readRecord().derived.council, undefined);
+  });
+  test("council keeps pending across the grant amend and records a later chat audit", async () => {
+    const h = await boundInBrainstorm();
+    await h.emit("tool_result", memberBatch());
+    await h.emit("tool_result", chairResult());
+    await h.bash("c1", "git -C /w commit --amend --no-edit -q");
+    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 records an all-none audit from the commit against an empty chair", async () => {
+    const h = await boundInBrainstorm();
+    await h.emit("tool_result", memberBatch());
+    await h.emit("tool_result", chairResult(EMPTY_CHAIR));
+    await h.bash("c1", HEREDOC_COMMIT(ALL_NONE));
+    const zeroed = { total: counts(), unique: counts(), applied: counts(), unique_applied: counts(), deferred: counts(), rejected: counts() };
+    assert.deepEqual(h.readRecord().derived.council, {
+      chair: { model: "p/chair:medium", dispatches: 1, clusters: 0, members_reported: 0 },
+      members: { "p/alpha:xhigh": { dispatches: 1, ...zeroed }, "p/beta:high": { dispatches: 2, ...zeroed } },
+    });
+  });
+  test("council ignores a non-git bash command carrying audit text", async () => {
+    const h = await boundInBrainstorm();
+    await h.emit("tool_result", memberBatch());
+    await h.emit("tool_result", chairResult());
+    await h.bash("c1", `cat <<'EOF'\n${AUDIT_TEXT}\nEOF`);
+    assert.equal(h.readRecord().derived.council, undefined);
+    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

@@ -656,11 +656,11 @@
       }
     };
 
-    const onCouncilAudit = (content: unknown) => {
+    const onCouncilAudit = (text: string) => {
       const pending = councilPending;
       const clusters = pending?.chair?.clusters;
       if (!record || !pending?.chair || !clusters) return;
-      const audit = parseAudit(textOf(content));
+      const audit = parseAudit(text);
       if (!audit) return;
       const members = resolveMembers(pending.memberResults);
       const block = members && buildCouncil({ chair: { ...pending.chair, clusters }, members, audit });
@@ -758,6 +758,7 @@
       }
       if (event.toolName === "bash") {
         const command = String((event.input as { command?: unknown }).command ?? "");
+        if (phaseNow() === "brainstorm" && /\bgit\b[^\n]*\bcommit\b/.test(command)) onCouncilAudit(command);
         if (record && (phases.verify.status === "in_progress" || phases.ship.status === "in_progress")) {
           const statement = matchTestStatement(command, snap.testCommands ?? DEFAULT_TEST_COMMANDS);
           if (statement) pendingTest.set(event.toolCallId, statement);
@@ -771,7 +772,7 @@
       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);
+      if (phaseNow() === "brainstorm") onCouncilAudit(textOf(msg.content));
     });
 
     pi.on("turn_end", async (_event, ctx) => {

package/package.json

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

package/skills/brainstorming/reference/spec-finalization.md

@@ -88,7 +88,19 @@ subagent({ agent: "spec-summarizer", context: "fresh", async: false, cwd: "<abs
 
 `<SUMMARY_PATH>` above is a placeholder in the dispatch object; it means substitute the value of the shell variable `$SUMMARY_PATH` set above. The steps below use `$SUMMARY_PATH` (the shell form) once the value is in hand.
 
-Then commit the spec - staging any predecessor spec edited per [Marking superseded specs](superseding.md) alongside it; a change request at the gate that renames, materially revises, or drops the spec also reconciles the predecessor's banner before recommitting. This commit is **unconditional**: the summary is only a gate aid, so a degraded or missing summary never blocks it. If the council path ran, include its audit (`Coverage:` when present, then `Applied:` / `Deferred:` / `Rejected:`, verbatim from `/skill:roasting-the-spec`'s return) in the **commit message body** - this is the durable, non-contractual record a finish-time revert reads back; the audit is never a committed spec section. Evaluate the summary in two stages (the **Degrade path** referenced in each is defined just below):
+Then commit the spec - staging any predecessor spec edited per [Marking superseded specs](superseding.md) alongside it; a change request at the gate that renames, materially revises, or drops the spec also reconciles the predecessor's banner before recommitting. This commit is **unconditional**: the summary is only a gate aid, so a degraded or missing summary never blocks it. Commit with the message on stdin through a quoted heredoc - the only permitted form, so audit lines carrying backticks or `$` land unchanged and each starts a line (telemetry reads them from this command):
+
+```bash
+git -C <abs worktree path> add -- <spec path> [<predecessor path>] && git -C <abs worktree path> commit -q -F - -- <spec path> [<predecessor path>] <<'EOF'
+<subject>
+
+<audit lines, verbatim>
+EOF
+```
+
+If the council path ran, the body is its audit (`Coverage:` when present, then `Applied:` / `Deferred:` / `Rejected:`, verbatim from `/skill:roasting-the-spec`'s return) - the durable, non-contractual record a finish-time revert and row 3 below read back; the audit is never a committed spec section. On the worker path the body is empty. `-m`, `-F <file>`, `printf | ... -F -`, and `$'...'` strings are not used for this commit. The `add` on the same line is required because the spec is untracked at its first commit and `commit -- <path>` rejects an untracked path.
+
+Evaluate the summary in two stages (the **Degrade path** referenced in each is defined just below):
 
 1. **From the dispatch tool result, before the `Read`.** If the result is **not** an `"Output saved to: <path> (<N> KB, <M> lines)"` reference (e.g. an exit-0 save error returns the full inline output plus an "Output file error" line - the prunable shape, no file to read), or the reference reports under ~500 bytes, or over ~45 KB (the `Read` truncates at 50KB / 2000 lines, so a larger file cannot render whole) - skip the `Read` and take the degrade path. Use the reference's reported figures; do not re-derive them.
 2. **The `Read` itself, as the last content-producing tool call before composing the gate.** `Read` `$SUMMARY_PATH` and paste its contents verbatim at the top of the gate. If the `Read` fails, returns 0 bytes, or reports truncation - take the degrade path. The `Read` must be last: pi-condense does not protect a `/tmp` read, so any turn boundary between the `Read` and the render lets the read result be pruned, reproducing the bug.
@@ -97,24 +109,22 @@ Then commit the spec - staging any predecessor spec edited per [Marking supersed
 
 Either way - summary rendered or degraded - then `rm "$SUMMARY_PATH"` (unconditional cleanup; harmless if the file was never created, since it lives outside the worktree under the OS temp dir).
 
-Paste the summary verbatim, unedited in the template below; use adjacent lines for the audit, unresolved ambiguities, and every `Missing from the spec` entry:
+Paste the summary verbatim, unedited in the template below; use adjacent lines for the `Council:` counts, unresolved ambiguities, and every `Missing from the spec` entry; the audit itself is shown only on row 3:
 
 ```
 <spec-only summary read back from the temp file - pasted verbatim, unedited>
 
 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: [<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)
+Council: <A> applied, <D> deferred, <R> rejected
+(council path only: A, D, R count the non-`none` lines under each label of the returned audit; append `; coverage <N> of <M>` only when the return carried a `Coverage:` line, e.g. `Council: 11 applied, 0 deferred, 0 rejected; coverage 2 of 3`; omit the whole line and row 3 on the worker path or when the council aborted before an audit existed)
 
 <unresolved ambiguities; every `Missing from the spec` 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.
 
 1 - approve: proceed to planning under the existing amendment review; a fresh reviewer applies evidence-backed factual corrections on its own, and every other spec amendment (scope, acceptance-criteria, or contract edits, and redraws) stops for your review.
 2 - approve, auto-apply amends: every later spec amendment in this flow (corrected facts, paths, verification lines, and scope, acceptance-criteria, or public-contract edits alike) applies without asking; only a redraw (changed problem statement, component added, removed, or re-bounded) still stops for you, and the grant never stands in for a spec approval.
+3 - show council dispositions: prints the council audit verbatim, then re-presents this gate. Not an approval.
 
 Or tell me what to change in the spec, or say "revert applied council edit <X>" to undo a specific applied edit.
 ```
@@ -123,7 +133,7 @@ If you believe the summary needs correcting, do **not** silently rewrite it - re
 
 **Revert valve.** "Revert applied council edit X" is a normal change request: revise the spec to undo edit X, re-dispatch the summarizer with a **fresh** temp path (per the re-dispatch rule below), and re-present the gate. This is cheap here - the spec is not yet plan- or code-bearing.
 
-Wait for the user. On a change request (including a revert), revise the spec and re-present - mint a **fresh** temp path for the re-dispatched summarizer (never reuse a prior round's path, so stale content can never be mistaken for the new summary). On approval - `1`, `approve`, or equivalent prose approves without a grant; `2`, `approve, auto-apply amends`, or equivalent prose approves and grants - proceed immediately to `/skill:writing-plans` with no further prompt; first read [Standing grants](amendment-surface.md#standing-grants) (stop if unreadable). On a grant (`2`, `approve, auto-apply amends`, or equivalent prose), `edit` the spec's `**Amend-grant:**` value to the granting sentence (the digit `2` becomes the grant description after `2 - approve, auto-apply amends:` above), then `git -C <abs worktree path> add -- <spec path>` and `git -C <abs worktree path> commit --amend --no-edit -q`, so the spec commit carries the line and keeps its council-audit body; then confirm `git -C <abs worktree path> show HEAD:<spec path>` reads "grant active" through the predicate. On a plain approval (`1`, `approve`) the value stays `none` and the commit is untouched. A reply that mixes approval with a change request ("2 but rename the section") is a change request: revise, re-present, and read the grant only from the reply to the re-presented gate. If the amend or the HEAD check fails, stop and report; never proceed as granted. The plan and execution mode are mechanical derivatives, so the only human gate here is spec approval itself. Don't land the spec on `main`; it stays in the worktree and ships in the same squash commit as the implementation.
+Wait for the user. On a change request (including a revert), revise the spec and re-present - mint a **fresh** temp path for the re-dispatched summarizer (never reuse a prior round's path, so stale content can never be mistaken for the new summary). On `3` or its label alone: print the audit verbatim from `git -C <abs worktree path> show -s --format=%b HEAD` (never from a held tool result; the body survives the grant's `--amend --no-edit`), then re-present the same gate - the briefing text of the gate message just rendered, reused verbatim (no summarizer re-dispatch, no read of the removed `$SUMMARY_PATH`; if that text is no longer in context, the one-line degrade note takes its place), the `Council:` line, the adjacent lines, the three rows; nothing in the spec or the commit changes. `3` plus a change request is a change request. `3` plus `1`/`2` prints and re-presents, and the approval is read only from a clean `1`/`2` on the re-presented gate - a reply carrying `3` never grants. A gate-round recommit (change request or revert) re-runs the same heredoc commit with the audit as its body, so HEAD always carries it; on a revert of edit X, move X's `Applied:` line to `Rejected:` with `-> reverted at gate` and recompute the `Council:` counts from the revised audit. On approval - `1`, `approve`, or equivalent prose approves without a grant; `2`, `approve, auto-apply amends`, or equivalent prose approves and grants - proceed immediately to `/skill:writing-plans` with no further prompt; first read [Standing grants](amendment-surface.md#standing-grants) (stop if unreadable). On a grant (`2`, `approve, auto-apply amends`, or equivalent prose), `edit` the spec's `**Amend-grant:**` value to the granting sentence (the digit `2` becomes the grant description after `2 - approve, auto-apply amends:` above), then `git -C <abs worktree path> add -- <spec path>` and `git -C <abs worktree path> commit --amend --no-edit -q`, so the spec commit carries the line and keeps its council-audit body; then confirm `git -C <abs worktree path> show HEAD:<spec path>` reads "grant active" through the predicate. On a plain approval (`1`, `approve`) the value stays `none` and the commit is untouched. A reply that mixes approval with a change request ("2 but rename the section") is a change request: revise, re-present, and read the grant only from the reply to the re-presented gate. If the amend or the HEAD check fails, stop and report; never proceed as granted. The plan and execution mode are mechanical derivatives, so the only human gate here is spec approval itself. Don't land the spec on `main`; it stays in the worktree and ships in the same squash commit as the implementation.
 
 Post-approval changes follow [Amending an approved spec](../SKILL.md#amending-an-approved-spec).
 

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

@@ -1,6 +1,6 @@
 ---
 name: roasting-the-spec
-description: Use after writing a spec, when a spec council is configured (the resolved piGauntlet.specCouncil council, via the gauntlet_setting tool, repo settings over the preset). Auto-dispatched by /skill:brainstorming as the critique pass when members is non-empty (no longer offered). N members on different models critique in parallel, a neutral chair consolidates and adjudicates, the parent applies its own dispositions and returns an audit for the user to ratify at brainstorming's gate.
+description: Use after writing a spec, when a spec council is configured (the resolved piGauntlet.specCouncil council, via the gauntlet_setting tool, repo settings over the preset). Auto-dispatched by /skill:brainstorming as the critique pass when members is non-empty (no longer offered). N members on different models critique in parallel, a neutral chair consolidates and adjudicates, the parent applies its own dispositions and returns an audit that brainstorming commits with the spec, counts at its gate, and prints on request.
 ---
 
 # Roasting the Spec (Spec Council)
@@ -126,20 +126,20 @@ 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: [<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.
+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 row 3 at brainstorming's 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.
 
 ### 4 — Emit the audit
 
-Return a structured audit, gate-only (not a committed spec section) — a coverage line plus three labelled lists:
+Return a structured audit, for the commit body and row 3 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 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.
+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, shows a `Council:` counts line at its one review gate, and prints the audit verbatim when the user picks row 3. The user can revert any applied edit there - that gate, not this skill, is where ratification happens.
 
 ### 5 — Clean up
 
@@ -152,7 +152,7 @@ Single pass — no automatic re-roast loop. The user can invoke this skill again
 - Running the council when `piGauntlet.specCouncil.members` is absent or empty (brainstorming owns the gate and should have used the worker fallback).
 - Reading member critique files' findings content yourself instead of routing them through the chair (the mechanical structural probe - existence plus header regex - is the named exception).
 - Writing member files to a relative path (they land in the worktree).
-- Applying edits without surfacing the audit at brainstorming's gate — apply-before-the-gate is correct; apply-without-the-gate is not.
+- Applying edits without the `Council:` counts and the row-3 audit at brainstorming's gate - apply-before-the-gate is correct; apply-without-the-gate is not.
 - Suppressing a finding instead of routing it to applied, deferred, or rejected in the audit.
 - Surfacing member-vs-member disagreements to the user instead of letting the chair adjudicate.
 - Editing anything other than the spec under `doc/specs/`.