pi-gauntlet 5.3.7 → 5.4.0

package/CHANGELOG.md

@@ -1,5 +1,9 @@
 # Changelog
 
+## v5.4.0 - 2026-09-10
+
+- `subagent-driven-development`: a stalled review fix loop runs one escalated fix round (`implementer`, `context: fresh`, model from new `piGauntlet.escalationLoop.implModel`, default main-loop model + thinking) before stopping; the stop is a one-screen problem note (`stop-note.md`) with concrete fix options, replacing the trajectory-log escalation report. `gauntlet_setting` gains the `escalationLoop` key. (#29)
+
 ## v5.3.7 - 2026-09-10
 
 - `brainstorming`: the standalone "does this replace a prior spec" question is gone - the gather scout names candidate predecessor specs and round 1 states them; the design is presented in two rounds (architecture/components/data flow, then errors/testing/docs) with one approval each. (#27)

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

@@ -4,6 +4,8 @@ import {
   mergeGauntlet,
   resolveSpecCouncil,
   resolveClosureReview,
+  resolveEscalationLoop,
+  mainLoopModel,
   resolveFlowGuards,
   resolveVerifyBeforeShip,
   settingsErrorWarning,
@@ -24,6 +26,41 @@ test("mergeGauntlet: undefined layers -> {}", () => {
   assert.deepEqual(mergeGauntlet(undefined, undefined), {});
 });
 
+test("mergeGauntlet: repo escalationLoop replaces preset whole-object", () => {
+  const preset = { escalationLoop: { implModel: "p/preset:high" }, closureReview: { model: "m" } };
+  const repo = { escalationLoop: {} };
+  const merged = mergeGauntlet(preset, repo);
+  assert.deepEqual(merged.escalationLoop, {});
+  assert.deepEqual(merged.closureReview, { model: "m" });
+});
+
+test("escalationLoop: absent/empty/null/non-string -> mainLoop", () => {
+  const main = "p/main:medium";
+  assert.equal(resolveEscalationLoop({}, main).implModel, main);
+  assert.equal(resolveEscalationLoop({ escalationLoop: {} }, main).implModel, main);
+  assert.equal(resolveEscalationLoop({ escalationLoop: { implModel: "" } }, main).implModel, main);
+  assert.equal(resolveEscalationLoop({ escalationLoop: { implModel: null } }, main).implModel, main);
+  assert.equal(resolveEscalationLoop({ escalationLoop: { implModel: 42 } }, main).implModel, main);
+});
+
+test("escalationLoop: non-empty string wins, trimmed; undefined mainLoop passes through", () => {
+  assert.equal(
+    resolveEscalationLoop({ escalationLoop: { implModel: " p/x:high " } }, "p/main:medium").implModel,
+    "p/x:high",
+  );
+  assert.equal(resolveEscalationLoop({}, undefined).implModel, undefined);
+});
+
+test("mainLoopModel: always suffixed; unset -> off, max -> xhigh, recognised pass through", () => {
+  const m = { provider: "p", id: "id" };
+  assert.equal(mainLoopModel(m, undefined), "p/id:off");
+  assert.equal(mainLoopModel(m, "off"), "p/id:off");
+  assert.equal(mainLoopModel(m, "medium"), "p/id:medium");
+  assert.equal(mainLoopModel(m, "xhigh"), "p/id:xhigh");
+  assert.equal(mainLoopModel(m, "max"), "p/id:xhigh");
+  assert.equal(mainLoopModel(undefined, "medium"), undefined);
+});
+
 test("specCouncil: non-empty string array -> council", () => {
   const r = resolveSpecCouncil({ specCouncil: { members: ["p/m1", " p/m2 "], chair: "p/c" } });
   assert.equal(r.verdict, "council");

package/extensions/lib/gauntlet-settings.ts

@@ -8,6 +8,7 @@ export interface PiGauntlet {
   closureReview?: { enforce?: unknown; model?: unknown; maxFixRounds?: unknown };
   flowGuards?: { enforce?: unknown; specDirs?: unknown };
   verifyBeforeShip?: { testCommands?: unknown; warningReference?: unknown };
+  escalationLoop?: { implModel?: unknown };
 }
 
 // Whole-object second-level merge: each piGauntlet key present in the repo layer
@@ -87,6 +88,29 @@ export function resolveClosureReview(g: PiGauntlet): ClosureReviewResolved {
   return { model, enforce, maxFixRounds };
 }
 
+export interface EscalationLoopResolved {
+  implModel: string | undefined;
+}
+
+export function resolveEscalationLoop(g: PiGauntlet, mainLoop: string | undefined): EscalationLoopResolved {
+  const raw = g.escalationLoop?.implModel;
+  return { implModel: nonEmptyString(raw) ? raw.trim() : mainLoop };
+}
+
+const THINKING_SUFFIXES = new Set(["off", "minimal", "low", "medium", "high", "xhigh"]);
+
+// Always emit a suffix so pi-cohort's applyThinkingSuffix never falls back to the
+// implementer's configured thinking; pi's "max" has no pi-cohort equivalent -> xhigh.
+export function mainLoopModel(
+  model: { provider: string; id: string } | undefined,
+  thinkingLevel: string | undefined,
+): string | undefined {
+  if (!model) return undefined;
+  const level =
+    thinkingLevel === "max" ? "xhigh" : THINKING_SUFFIXES.has(thinkingLevel ?? "") ? thinkingLevel : "off";
+  return `${model.provider}/${model.id}:${level}`;
+}
+
 export interface FlowGuardsResolved {
   enforce: boolean;
   specDirs: string[];

package/extensions/phase-tracker.test.ts

@@ -51,7 +51,7 @@ const resumedBranch = (rest: Partial<Record<Phase, Status>>) => [
   phaseResult("complete", phases({ brainstorm: "skipped", ...rest })),
 ];
 
-function harness(options: { cwd?: string; branch?: unknown[]; idle?: boolean; beforeSettled?: (setIdle: (idle: boolean) => void) => void; sendThrows?: boolean } = {}) {
+function harness(options: { cwd?: string; branch?: unknown[]; idle?: boolean; beforeSettled?: (setIdle: (idle: boolean) => void) => void; sendThrows?: boolean; model?: { provider: string; id: string }; thinkingLevel?: string } = {}) {
   const handlers = new Map<string, ((event: unknown, ctx: unknown) => unknown)[]>();
   const tools: { name: string; execute: (...args: any[]) => unknown }[] = [];
   const sent: { message: any; options: any }[] = [];
@@ -62,6 +62,8 @@ function harness(options: { cwd?: string; branch?: unknown[]; idle?: boolean; be
     hasUI: false,
     isIdle: () => idle,
     sessionManager: { getBranch: () => branch },
+    model: options.model,
+    thinkingLevel: options.thinkingLevel,
   };
   const pi = {
     on(event: string, handler: (event: unknown, context: unknown) => unknown) {
@@ -1141,3 +1143,14 @@ test("replay via session_switch: pass then fail clears the stamp, rebuilt from r
   };
   assert.match(res.details.error ?? "", /plan_check/);
 });
+
+test("gauntlet_setting escalationLoop: setting absent -> ctx-derived main-loop model; setting wins when set", async () => {
+  const h = harness({ cwd: tempCwd({ piGauntlet: {} }), model: { provider: "p", id: "main" }, thinkingLevel: "medium" });
+  const tool = h.tools.find((t) => t.name === "gauntlet_setting")!;
+  const absent = (await tool.execute("g1", { key: "escalationLoop" }, undefined, undefined, h.ctx)) as { details: { key: string; implModel?: string; errors: string[] } };
+  assert.deepEqual(absent.details, { key: "escalationLoop", implModel: "p/main:medium", errors: [] });
+
+  const set = harness({ cwd: tempCwd({ piGauntlet: { escalationLoop: { implModel: "p/strong:high" } } }), model: { provider: "p", id: "main" }, thinkingLevel: "medium" });
+  const res = (await set.tools.find((t) => t.name === "gauntlet_setting")!.execute("g2", { key: "escalationLoop" }, undefined, undefined, set.ctx)) as { details: { implModel?: string } };
+  assert.equal(res.details.implModel, "p/strong:high");
+});

package/extensions/phase-tracker.ts

@@ -17,7 +17,9 @@ import type { ExtensionAPI, ExtensionContext, Theme } from "@earendil-works/pi-c
 import { Text } from "@earendil-works/pi-tui";
 import { type Static, Type } from "@sinclair/typebox";
 import {
+  mainLoopModel,
   resolveClosureReview,
+  resolveEscalationLoop,
   resolveFlowGuards,
   resolveSpecCouncil,
   settingsErrorWarning,
@@ -666,7 +668,7 @@ export default function (pi: ExtensionAPI) {
   });
 
   const GauntletSettingParams = Type.Object({
-    key: StringEnum(["specCouncil", "closureReview"] as const, {
+    key: StringEnum(["specCouncil", "closureReview", "escalationLoop"] as const, {
       description: "Which gauntlet setting to resolve (merged repo-over-preset).",
     }),
   });
@@ -681,7 +683,13 @@ export default function (pi: ExtensionAPI) {
       const payload =
         params.key === "specCouncil"
           ? { key: "specCouncil" as const, ...resolveSpecCouncil(gauntlet), errors }
-          : { key: "closureReview" as const, ...resolveClosureReview(gauntlet), errors };
+          : params.key === "closureReview"
+            ? { key: "closureReview" as const, ...resolveClosureReview(gauntlet), errors }
+            : {
+                key: "escalationLoop" as const,
+                ...resolveEscalationLoop(gauntlet, mainLoopModel(ctx.model, ctx.thinkingLevel)),
+                errors,
+              };
       return {
         content: [{ type: "text", text: "```json\n" + JSON.stringify(payload, null, 2) + "\n```" }],
         details: payload,

package/package.json

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

package/skills/subagent-driven-development/SKILL.md

@@ -30,7 +30,7 @@ You are the **orchestrator**. You read the plan, dispatch, review the review, de
 **Do not pause to check in with the user between tasks.** The plan is already approved. Pause only when:
 
 - A subagent returns `NEEDS_CONTEXT` or `BLOCKED` (see [Implementer Status](#implementer-status))
-- A fix loop escalates per [Fix-Loop Rounds](#fix-loop-rounds) (stagnation, or budget exhausted without convergence)
+- An escalated round fails (stop note per [Fix-Loop Rounds](#fix-loop-rounds))
 - A ⚠️ workflow warning fires
 
 Reaching the end of the plan is not a pause: continue through verification and invoke `/skill:finishing-a-development-branch` as defined in [After All Tasks](#after-all-tasks-complete).
@@ -88,12 +88,12 @@ Every fix re-dispatch (implementer) and code-review re-review carries the consum
 
 Every dispatched fix is verified by a re-review before escalation or task progression - the loop only ever exits on a clean review or an escalation.
 
-**Escalation report:** report reviews run per loop and the final `TRAJECTORY` verdict - report `TRAJECTORY: MISSING` if the line was absent, or quote the raw line if malformed. If the exception ran, say so explicitly: `fix 3 was the convergence exception (CONVERGING, no Critical)`.
+**Escalate** = one escalated round; stop only on failure. Call `gauntlet_setting({ key: "escalationLoop" })` (unavailable -> stop and report). `implModel` undefined -> stop note. Otherwise re-dispatch that fix - same payload and isolation knobs (`cwd`, `worktree`, `SCOPED_TEST_COMMANDS`, status protocol, prior patch, spec anchors) plus the prior report verbatim - overriding only `model: <implModel>`, `context: "fresh"`, `async: false`; one implementer, no fan-out. Run the normal fix-round review gate (SR then CR on `Behaviour-change: yes`, else the triggering reviewer with the re-review marker). All clean -> proceed; in wave mode the escalated patch supersedes the prior one at integrate. Any review with issues, a non-`DONE` status, or a dispatch error -> stop note per `stop-note.md`; no second dispatch. Once per loop; independent of the convergence exception. No `plan_tracker` write during escalation - the task stays `in_progress` until the human decides.
 
 **Worked examples:**
 
 - Review-2 verdict `TRAJECTORY: STAGNANT (repeat of: unchecked error path in parser)` -> escalate now, before fix 2 - earlier than the ordinary budget.
-- Review-3 verdict `TRAJECTORY: CONVERGING (3 -> 1, max severity Moderate)` -> dispatch fix 3; if review 4 still finds issues, escalate with the exception named in the report.
+- Review-3 verdict `TRAJECTORY: CONVERGING (3 -> 1, max severity Moderate)` -> dispatch fix 3; if review 4 still finds issues, escalate.
 - Review-3 verdict `TRAJECTORY: CONVERGING (3 -> 2, max severity Critical)` or `TRAJECTORY: DIVERGING` or no `TRAJECTORY:` line -> escalate.
 
 ## Implementer Status
@@ -139,6 +139,9 @@ When in doubt, default. Don't downgrade reviewers — false negatives are expens
 // implementer
 subagent({ agent: "implementer", async: false, task: "<task text + context + SCOPED_TEST_COMMANDS + status protocol>" })
 
+// escalated fix round (Fix-Loop Rounds): same fix payload, model from gauntlet_setting({ key: "escalationLoop" }).implModel
+subagent({ agent: "implementer", model: "<implModel>", context: "fresh", async: false, task: "<the just-dispatched fix payload + prior review report verbatim>" })
+
 // spec compliance
 subagent({ agent: "spec-reviewer", async: false, task: "<task text + patch diff + absolute spec path + task's Spec: anchors>" })
 

package/skills/subagent-driven-development/stop-note.md

@@ -0,0 +1,48 @@
+# Stop note (subagent-driven-development companion)
+
+Emitted when no escalation model resolves, the escalated dispatch errors, or its one escalated round fails (see `SKILL.md` "Fix-Loop Rounds"); an unavailable `gauntlet_setting` tool is a configuration error - stop and report, no stop note. Inline in the reply; the turn ends; phase stays `implement`, the task stays `in_progress`; no further tasks start. Wave mode: one note per stalled task, after the current batch returns.
+
+## Template
+
+```
+Stopped on task <n> (<title>)[; escalated round on <implModel> did not resolve it].
+
+Problem: <one sentence: what is wrong and why the fixes could not resolve it>
+  <file:line> - <quoted finding from the final review>
+  <failing test/command + 1-3 line output snippet, when present>
+
+Fix options:
+  a) <concrete change>
+  b) <concrete change - amending spec section X / plan task n is a normal option>
+  c) <optional third>
+
+Pick one, or give another fix.
+```
+
+## Rules
+
+- Bracketed header clause only when an escalated round actually ran; omit it when no model was resolvable or the dispatch errored.
+- Residual issues from the final review report only; quote, do not summarise history.
+- When no escalated round ran, the Problem is the reason: "no escalation model resolvable", or the implementer's non-DONE status text / the dispatch error, quoted; skip the file:line and test lines.
+- Options are actionable edits. Spec/plan amendment is first-class - stalls are usually a slightly contradictory spec, not a capability gap.
+- Never offer "skip the task". If the task is genuinely droppable, say so and name the plan tasks that depend on it.
+- No trajectory verdicts, round history, review counts, or paths to spec/plan/review reports.
+- Plain words, ASCII, no headings. One screen.
+
+## Example
+
+```
+Stopped on task 4 (retry policy for the outbound client); escalated round on <provider>/<model>:high did not resolve it.
+
+Problem: `RetryPolicy.next()` returns 0 ms for the first retry, but the client treats 0 as "no
+retry", so the first failure is never retried.
+  src/net/retry.ts:41 - `return attempt * this.baseMs;`
+  npm test -- retry > "retries once after a transient failure":
+    expected 1 call after failure, got 0
+
+Fix options:
+  a) start the backoff at `baseMs` (`(attempt + 1) * this.baseMs`)
+  b) amend plan task 4 so the client retries on any non-negative delay, and keep the policy as is
+
+Pick one, or give another fix.
+```

package/skills/verification-before-completion/reference/settings-precedence.md

@@ -15,7 +15,7 @@ If the repo file defines a `piGauntlet.<key>` at all, that definition **replaces
 the preset's for that key entirely - the two are never merged leaf-by-leaf. If the
 repo file does not define the key, the preset's value is used unchanged. This is
 exactly pi's own `deepMergeSettings` behaviour: it spreads the second-level keys
-(`specCouncil`, `closureReview`, `flowGuards`, `verifyBeforeShip`) wholesale, and
+(`specCouncil`, `closureReview`, `flowGuards`, `verifyBeforeShip`, `escalationLoop`) wholesale, and
 does not recurse into their leaves.
 
 **Caveat - partial definitions drop siblings.** Because the replace is