pi-gauntlet 7.17.1 → 7.18.1

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## v7.18.1 - 2026-10-19
+
+### Removed
+
+- **`start implement` no longer warns about a missing `promptCache` lifetime.** The warning fired on every non-Anthropic model (pi's catalog declares `promptCache` only for direct `anthropic` Claude entries) and read as an instruction to edit `models.json`, which stalled auto-chaining into implement until the user typed "continue"; the per-call cache telemetry from #67 stays and is the real signal for cache hits.
+
+## v7.18.0 - 2026-10-19
+
+### Changed
+
+- **Brainstorming questions list one option per line.** Each `A)`/`B)` option and the `Recommendation:` line sit on their own physical line instead of one paragraph; wording and the framing rules are unchanged. (#70)
+
+### Fixed
+
+- **Telemetry counts the agents of a failed dispatch.** A `subagent` call that ended in error (a failed chain step, a sibling that exited non-zero) still records its retained per-persona results; spec-round and conformance bookkeeping stay on the success path. `package.json` now declares pi-cohort >= 7.3.1 as a peer dependency, matching the README requirement. (#70)
+
 ## v7.17.1 - 2026-10-18
 
 ### Fixed

package/extensions/phase-tracker.test.ts

@@ -69,7 +69,7 @@ const resumedBranch = (rest: Partial<Record<Phase, Status>>) => [
   phaseResult("complete", phases({ brainstorm: "skipped", ...rest })),
 ];
 
-type TestModel = { provider: string; id: string; promptCache?: { short?: number; long?: number } };
+type TestModel = { provider: string; id: string };
 
 function harness(options: { cwd?: string; branch?: unknown[]; idle?: boolean; beforeSettled?: (setIdle: (idle: boolean) => void) => void; sendThrows?: boolean; model?: TestModel; thinkingLevel?: string; registry?: Record<string, TestModel>; setModelResult?: boolean | Error } = {}) {
   const handlers = new Map<string, ((event: unknown, ctx: unknown) => unknown)[]>();
@@ -136,7 +136,7 @@ const startPhase = async (h: ReturnType<typeof harness>, phase: string) => {
   return { text: r.content.map((c) => c.text).join("\n"), status: r.details.phases[phase].status };
 };
 
-const M = (id: string, promptCache?: { short?: number; long?: number }) => ({ provider: "p", id, promptCache });
+const M = (id: string) => ({ provider: "p", id });
 
 const preparePhase = async (h: ReturnType<typeof harness>, phase = "plan") => {
   await settle(h);
@@ -223,46 +223,6 @@ test("phaseModels: resolver warnings appear only for their phase", async () => {
   assert.deepEqual(h.pi.thinkingCalls, []);
 });
 
-for (const row of [
-  { name: "missing short", phase: "implement", cache: undefined, retention: undefined, tier: "short" },
-  { name: "declared short", phase: "implement", cache: { short: 300 }, retention: undefined, tier: undefined },
-  { name: "missing long", phase: "implement", cache: { short: 300 }, retention: "long", tier: "long" },
-  { name: "plan ignores cache", phase: "plan", cache: undefined, retention: undefined, tier: undefined },
-]) {
-  test(`phaseModels: cache warning ${row.name}`, async () => {
-    const retention = process.env.PI_CACHE_RETENTION;
-    if (row.retention === undefined) delete process.env.PI_CACHE_RETENTION;
-    else process.env.PI_CACHE_RETENTION = row.retention;
-    try {
-      const h = harness({ cwd: tempCwd({ piGauntlet: { flowGuards: { enforce: false } } }), model: M("m", row.cache) });
-      await preparePhase(h, row.phase);
-      const r = await startPhase(h, row.phase);
-      if (row.tier) {
-        assert.ok(r.text.includes(`p/m declares no promptCache.${row.tier} lifetime, so pi's cache warmer skips it`));
-        assert.ok(r.text.includes("providers.p.modelOverrides.m.promptCache"));
-        assert.ok(r.text.includes("providers.p.models[].promptCache"));
-      } else assert.doesNotMatch(r.text, /cache warmer/);
-      assert.deepEqual(h.pi.setModelCalls, []);
-      assert.deepEqual(h.pi.thinkingCalls, []);
-      assert.equal(r.status, "in_progress");
-    } finally {
-      if (retention === undefined) delete process.env.PI_CACHE_RETENTION;
-      else process.env.PI_CACHE_RETENTION = retention;
-    }
-  });
-}
-
-test("phaseModels: cache warning checks the switched model", async () => {
-  const h = harness({ cwd: tempCwd({ piGauntlet: { flowGuards: { enforce: false }, phaseModels: { implement: "p/warm" } } }), model: M("old"), registry: { "p/warm": M("warm", { short: 300, long: 3600 }) } });
-  await preparePhase(h, "implement");
-  const r = await startPhase(h, "implement");
-  assert.equal(h.pi.setModelCalls.length, 1);
-  assert.deepEqual(h.pi.thinkingCalls, []);
-  assert.equal(h.ctx.model?.id, "warm");
-  assert.doesNotMatch(r.text, /cache warmer/);
-  assert.equal(r.status, "in_progress");
-});
-
 test("agent_settled nudges each exact edge with persisted details", async () => {
   for (const [state, edge, skill] of [
     [phases({ brainstorm: "complete", plan: "complete" }), "plan-implement", "/skill:subagent-driven-development"],

package/extensions/phase-tracker.ts

@@ -1031,17 +1031,6 @@ export default function (pi: ExtensionAPI) {
             for (const w of resolved.warning?.split("; ") ?? []) if (w.includes(`phaseModels.${phase} `)) startLines.push(`\u26a0\ufe0f ${w}`);
             const target = resolved.phaseModels[phase];
             if (target) startLines.push(...(await applyPhaseModel(pi, ctx, phase, target)));
-            if (phase === "implement") {
-              const tier = process.env.PI_CACHE_RETENTION === "long" ? "long" : "short";
-              const m = ctx.model;
-              if (m && m.promptCache?.[tier] === undefined) {
-                startLines.push(
-                  `\u26a0\ufe0f ${m.provider}/${m.id} declares no promptCache.${tier} lifetime, so pi's cache warmer skips it. ` +
-                    `Declare it in <agent-dir>/models.json (default ~/.pi/agent): providers.${m.provider}.modelOverrides.${m.id}.promptCache for a built-in model, ` +
-                    `or providers.${m.provider}.models[].promptCache for a custom one; the lifetime is required by the warmer but not sufficient - see doc/configuration.md#phase-models.`,
-                );
-              }
-            }
           }
           phases = { ...phases, [params.phase]: transitionPhaseState("in_progress") as PhaseState };
           // A rewind must not inherit the prior verify's conformance latch.

package/extensions/telemetry.test.ts

@@ -588,7 +588,7 @@
     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);
+    assert.deepEqual(h.readRecord().derived.personas["spec-council-member"], { dispatches: 3, models: ["p/alpha:xhigh", "p/beta:high"], tokens: { input: 3, output: 0, cache_read: 0, cache_write: 0, cost: 0 } });
   });
   test("council defaults missing chair model and survives unrelated result before audit", async () => {
     const h = await boundInBrainstorm();
@@ -727,6 +727,66 @@
     assert.deepEqual(rec.derived.phases.plan?.tokens, { input: 152, output: 15, cache_read: 0, cache_write: 0, cost: 1.5 });
   });
 
+  for (const [name, agents] of [
+    ["chain", ["implementer", "spec-reviewer", "spec-reviewer"]],
+    ["plain tasks", ["implementer", "implementer"]],
+    ["empty results", []],
+    ["missing results", undefined],
+  ] as const) {
+    test(`failed subagent ${name}: count terminal retained results once, not progress`, async () => {
+      const h = harness();
+      await h.phaseResult("start", P({ brainstorm: "in_progress" }));
+      await h.writeSpec("doc/specs/a.md");
+      await h.phaseResult("start", P({ brainstorm: "complete", plan: "complete", implement: "in_progress" }));
+      await h.emit("tool_result", { toolName: "plan_tracker", toolCallId: "pt", input: {}, content: [], isError: false, details: { action: "init", tasks: [{ name: "repair", status: "in_progress" }] } });
+      const before = h.readRecord();
+      const results = agents?.map((agent, i) => ({ agent, exitCode: i === agents.length - 1 ? 1 : 0, model: `p/m${i}`, usage: usage(10, 2, 0.5) }));
+      const terminal = { ...subagentResult(results ?? []), isError: true, details: results === undefined ? {} : { results } };
+      for (const partial of [results?.slice(0, 1), results]) {
+        await h.emit("tool_execution_update", { type: "tool_execution_update", toolName: "subagent", toolCallId: "sa", args: {}, partialResult: { content: [], details: { results: partial ?? [] } } });
+      }
+      assert.deepEqual(h.readRecord(), before);
+      await h.emit("tool_result", terminal);
+      const rec = h.readRecord();
+      const dispatches = rec.events.filter((e) => e.kind === "dispatch");
+      assert.equal(dispatches.length, agents?.length ?? 0);
+      assert.deepEqual(dispatches.map((e) => ({ agent: e.agent, model: e.model, exit: e.exit, phase: e.phase })), results?.map((r) => ({ agent: r.agent, model: r.model, exit: r.exitCode || undefined, phase: "implement" })) ?? []);
+      for (const agent of new Set(agents)) {
+        const retained = results!.filter((r) => r.agent === agent);
+        assert.deepEqual(rec.derived.personas[agent], { dispatches: retained.length, models: retained.map((r) => r.model), tokens: { input: 10 * retained.length, output: 2 * retained.length, cache_read: 0, cache_write: 0, cost: 0.5 * retained.length } });
+      }
+      if (name === "chain") assert.deepEqual(rec.derived.reviews?.["spec-reviewer"], { dispatches: 2, nonzero_exit: 1 });
+      if (results?.length) assert.deepEqual(rec.derived.phases.implement?.tokens, { input: 10 * results.length, output: 2 * results.length, cache_read: 0, cache_write: 0, cost: 0.5 * results.length });
+      else assert.deepEqual(rec, before);
+      assert.deepEqual(rec.events.filter((e) => e.kind === "phase" || e.kind === "gate"), before.events.filter((e) => e.kind === "phase" || e.kind === "gate"));
+      assert.deepEqual(rec.derived.plan, before.derived.plan);
+      assert.deepEqual(rec.derived.gates, before.derived.gates);
+    });
+  }
+
+  test("failed spec and conformance dispatches count usage and failures without advancing successful gates", async () => {
+    const h = await boundInPlan();
+    await h.phaseResult("start", P({ brainstorm: "complete", plan: "complete", implement: "complete", verify: "in_progress" }));
+    const results = ["spec-summarizer", "conformance-reviewer"].map((agent) => ({ agent, exitCode: 1, model: "p/r", usage: usage(3) }));
+    const before = h.readRecord();
+    await h.emit("tool_result", { ...subagentResult(results, "Conformance verdict: GAPS\nG1:\n  verdict: MISSING"), isError: true });
+    let rec = h.readRecord();
+    assert.deepEqual(rec.events.filter((e) => e.kind === "dispatch").map((e) => ({ agent: e.agent, exit: e.exit, phase: e.phase })), results.map((r) => ({ agent: r.agent, exit: 1, phase: "verify" })));
+    for (const { agent } of results) assert.deepEqual(rec.derived.personas[agent], { dispatches: 1, models: ["p/r"], tokens: { input: 3, output: 0, cache_read: 0, cache_write: 0, cost: 0 } });
+    assert.equal(rec.derived.gates.spec_rounds, before.derived.gates.spec_rounds);
+    assert.equal(rec.derived.conformance_loops, before.derived.conformance_loops);
+    assert.equal(rec.derived.conformance_open_gaps, before.derived.conformance_open_gaps);
+    assert.deepEqual(rec.derived.reviews?.["conformance-reviewer"], { dispatches: 1, nonzero_exit: 1 });
+    assert.deepEqual(rec.derived.phases.verify?.tokens, { input: 6, output: 0, cache_read: 0, cache_write: 0, cost: 0 });
+    assert.deepEqual(rec.events.filter((e) => e.kind === "phase" || e.kind === "gate"), before.events.filter((e) => e.kind === "phase" || e.kind === "gate"));
+    await h.emit("tool_result", subagentResult(results.map((r) => ({ ...r, exitCode: 0 })), "Conformance verdict: GAPS\nG1:\n  verdict: MISSING"));
+    rec = h.readRecord();
+    assert.equal(rec.derived.gates.spec_rounds, before.derived.gates.spec_rounds + 1);
+    assert.equal(rec.derived.conformance_loops, 1);
+    assert.equal(rec.derived.conformance_open_gaps, 1);
+    assert.deepEqual(rec.derived.reviews?.["conformance-reviewer"], { dispatches: 2, nonzero_exit: 1 });
+  });
+
   test("conformance-reviewer during verify counts loops and retains the latest open gap count", async () => {
     const h = await boundInPlan();
     await h.phaseResult("complete", P({ brainstorm: "complete", plan: "complete" }));

package/extensions/telemetry.ts

@@ -548,7 +548,7 @@
       }
       if (event.toolName === "subagent") {
         if (phaseNow() === "brainstorm") onCouncilResults(event.details, event.content);
-        if (!event.isError) await onSubagentResult(event.details, event.content);
+        await onSubagentResult(event.details, event.content, event.isError);
         return undefined;
       }
       if (event.toolName === "plan_tracker" && !event.isError) {
@@ -670,7 +670,7 @@
       flush();
     };
 
-    const onSubagentResult = async (details: unknown, content: unknown) => {
+    const onSubagentResult = async (details: unknown, content: unknown, isError: boolean) => {
       const results = (details as { results?: unknown[] } | undefined)?.results;
       if (!Array.isArray(results) || results.length === 0) return;
       const acc = live();
@@ -687,7 +687,7 @@
         persona.dispatches += 1;
         if (model && !persona.models.includes(model)) persona.models.push(model);
         if (tokens) persona.tokens = addTokens(persona.tokens, tokens);
-        if (agent === "spec-summarizer") acc.gates.spec_rounds += 1;
+        if (!isError && agent === "spec-summarizer") acc.gates.spec_rounds += 1;
         if (REVIEWER_AGENTS.has(agent)) {
           const review = (acc.reviews[agent] ??= { dispatches: 0, nonzero_exit: 0 });
           review.dispatches += 1;
@@ -699,7 +699,7 @@
             review.findings.major += findings.major;
             review.findings.minor += findings.minor;
           }
-          if (agent === "conformance-reviewer") {
+          if (!isError && agent === "conformance-reviewer") {
             if (phases.verify.status === "in_progress") acc.conformance_loops += 1;
             const openGaps = countOpenGaps(text);
             if (openGaps !== undefined) acc.conformance_open_gaps = openGaps;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-gauntlet",
-  "version": "7.17.1",
+  "version": "7.18.1",
   "description": "Opinionated, gated workflow skills, subagent personas, and runtime extensions for the pi coding agent.",
   "author": "Jacek Juraszek",
   "type": "module",
@@ -61,6 +61,9 @@
     "build:bins": "node scripts/build-bins.mjs",
     "test": "node scripts/ci.mjs"
   },
+  "peerDependencies": {
+    "pi-cohort": ">=7.3.1"
+  },
   "dependencies": {
     "yaml": "^2.9.0"
   },

package/skills/brainstorming/SKILL.md

@@ -91,23 +91,46 @@ Clarify freely.
 
 `Read` the gathered draft unconditionally before question one. Treat it as a helper, not a fence: verify load-bearing claims from primary code, and confirm whether the codebase or ecosystem already solves the problem.
 
-Ask one question per message, about purpose, constraints, success, and affected actors. Every questionary question offers 2-4 labeled options (`A)`, `B)`, ...), each a different outcome, and ends `Recommendation: <letter> - <why>`; when more outcomes are plausible, the last option is `other - name it` or the question splits in two. This format overrides chat-style rules in `AGENTS.md` (one paragraph, no Options/Recommendation layout). A decision that would be a yes/no or "may I" question is not asked: make it, state it as an assumption in the message that carries the next question or the premise note, and record it in the draft. Before asking, check code, docs, and tracker: look up current-state facts (dispatch a subagent when costly); adopt a ticket-recorded decision and cite the ticket, asking it only when a cited code or API contradiction, or conflicting recorded outcomes, prevents adopting it. Other approvals retain their wording.
+Ask one question per message, about purpose, constraints, success, and affected actors. Offer 2-4 labeled options (`A)`, `B)`, ...) for every questionary question, each a different outcome. Put the lead-in before the first option, each labeled option on its own physical line, and `Recommendation: <letter> - <why>` on its own final line; when more outcomes are plausible, the last option is `other - name it` or the question splits in two. Use this one-option-per-line layout even when chat-style rules in `AGENTS.md` require one paragraph or no Options/Recommendation layout. A decision that would be a yes/no or "may I" question is not asked: make it, state it as an assumption in the message that carries the next question or the premise note, and record it in the draft. Before asking, check code, docs, and tracker: look up current-state facts (dispatch a subagent when costly); adopt a ticket-recorded decision and cite the ticket, asking it only when a cited code or API contradiction, or conflicting recorded outcomes, prevents adopting it. Other approvals retain their wording.
 
 Bad: `May I treat those two acceptance criteria as location-only deviations? Recommendation: yes`
-Good: `The two ACs name a path that moved; the spec keeps them in-scope with the new path as a Design clause. Which surface owns the refresh? A) the extension B) a new bin C) the existing skill step. Recommendation: A - the extension already holds the poll loop, so no new entrypoint.`
+Good:
+```text
+The two ACs name a path that moved; the spec keeps them in-scope with the new path as a Design clause. Which surface owns the refresh?
+A) the extension
+B) a new bin
+C) the existing skill step.
+Recommendation: A - the extension already holds the poll loop, so no new entrypoint.
+```
 
 Append only citable findings - schemas, hard constraints, contradictions, and scope-changing answers - to `## Appended during questionary` using `edit`.
 
 Before approaches, state in chat the supported, disproved, corrected, and unverified premises with sources and attempted lookups, in full sentences - no status-keyword lists, no template; if the design depends on no claims, one sentence says so. An unverified claim is not a stop: put it in Open Questions or a stated assumption. If a load-bearing claim is contradicted, the premise note is your next message - even as question one - and states the corrected fact with its source; the design continues on it and the user overrides in reply. Record the corrected fact, and any override, in the draft for `## Problem` or the relevant design decision.
 
-Before question one, verify the draft's `Framing:` line against primary code and add your own recon. This check adds to the premise verification above and never replaces it: trace every consumer, caller, and data path the ask's constraints name before writing the holds-statement or the question, and name those traces in the holds-statement, not only the files read. A framing concern exists when you can state a cited case that the ask is misdiagnosed, wrong-sized, already solved, a band-aid where the root cause is reachable, or cuts across a sound pattern - including a repo convention that is itself the debt - and can name the alternative it implies; an objection without an alternative is a lead to investigate, not a concern. With a concern, question one is the framing question in the questionary format: `A) as framed`, `B) pivot: <named alternative> - <cited reason>`, `C) smaller or none: <what ships, or what happens if nothing ships>`, `Recommendation: <letter> - <why>`; for a band-aid concern, B carries the root-cause alternative. Without a concern, open the first message with one sentence naming what was checked - `The framing holds: checked <x>, <y>` - and continue to the first ordinary question; a scout objection that yielded no alternative is named among the things checked.
+Before question one, verify the draft's `Framing:` line against primary code and add your own recon. This check adds to the premise verification above and never replaces it: trace every consumer, caller, and data path the ask's constraints name before writing the holds-statement or the question, and name those traces in the holds-statement, not only the files read. A framing concern exists when you can state a cited case that the ask is misdiagnosed, wrong-sized, already solved, a band-aid where the root cause is reachable, or cuts across a sound pattern - including a repo convention that is itself the debt - and can name the alternative it implies; an objection without an alternative is a lead to investigate, not a concern. With a concern, question one is the framing question in the questionary format:
+
+```text
+A) as framed
+B) pivot: <named alternative> - <cited reason>
+C) smaller or none: <what ships, or what happens if nothing ships>
+Recommendation: <letter> - <why>
+```
+
+For a band-aid concern, put the root-cause alternative in B. Without a concern, open the first message with one sentence naming what was checked - `The framing holds: checked <x>, <y>` - and continue to the first ordinary question; a scout objection that yielded no alternative is named among the things checked.
 
 After any premise correction in the same message, ask the framing question or give the holds-statement. Ask the framing question at most once per brainstorm, including after pushback; the user's reply is final, and later doubts on the same point go to Open Questions or a `Pattern:` line. Recommend; never pivot without the reply. A ticket-recorded decision on the exact point follows the ticket rule above; an adopted decision records `Framing: kept (ticket <id>)`. A pivot never rewrites AC rows: rows it no longer satisfies take `deviates:` dispositions, and a pivot that changes the topic re-mints the slug.
 
 Record the outcome in the draft under `## Appended during questionary` as `Framing: kept` or `Framing: pivoted to <x> - <why>`; spec-writing carries that line into `## Problem`. On redraw entry (checklist step 4) the count restarts: run this evaluation once against the new draft. On redraw the draft is the approved spec: its `## Problem` `Framing:` line is context, not scout evidence, and the new outcome is recorded directly in `## Problem`. When the scout failed there is no `Framing:` line; the holds-statement or the question still comes from your own recon.
 
 Bad: `The ask adds another settings path - should we? Recommendation: no`
-Good: `The ask adds a second settings path beside the resolver that already owns every setting (settings/resolver.ts:11). A) as framed B) pivot: a key under the existing resolver - one read path, no new boundary C) smaller or none: document the default and ship no setting. Recommendation: B - the owning schema already exists.`
+Good:
+```text
+The ask adds a second settings path beside the resolver that already owns every setting (settings/resolver.ts:11).
+A) as framed
+B) pivot: a key under the existing resolver - one read path, no new boundary
+C) smaller or none: document the default and ship no setting.
+Recommendation: B - the owning schema already exists.
+```
 
 ### 4. Explore approaches