pi-gauntlet 5.5.3 → 5.5.4

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## v5.5.4 - 2026-09-14
+
+- `phase-tracker`: new `phase_tracker` action `grant_fix_rounds` records an explicit human approval of N more conformance fix rounds (reason quotes the human), accepted only while the cap block is live; each qualifying implementer wave spends one granted round, credits replay with the session and reset with the audit latch. The cap-block message now leads with that action and names the exact `.pi/settings.json` for the `enforce: false` last resort (applies without restart, whole-block precedence).
+- `gauntlet_setting` is registered with sequential execution, so a settings write and a verifying read batched in one message run in order.
+- `conformance-check.md`: an explicit human approval re-enters the fix loop via `grant_fix_rounds`; without it escalation stays terminal.
+
 ## v5.5.3 - 2026-09-13
 
 - `code-reviewer`: verdict is a stated function of severity - a Critical or Moderate finding means `FIX_FIRST`, Minor-only and clean reports mean `SHIP`, matching the orchestrating skills. (#30)

package/extensions/phase-tracker.test.ts

@@ -58,7 +58,7 @@ const resumedBranch = (rest: Partial<Record<Phase, Status>>) => [
 
 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 tools: { name: string; executionMode?: string; parameters?: any; execute: (...args: any[]) => unknown }[] = [];
   const sent: { message: any; options: any }[] = [];
   let idle = options.idle ?? true;
   let branch = options.branch ?? [];
@@ -76,7 +76,7 @@ function harness(options: { cwd?: string; branch?: unknown[]; idle?: boolean; be
       registered.push(handler);
       handlers.set(event, registered);
     },
-    registerTool(tool: { name: string; executionMode?: string; execute: (...args: any[]) => unknown }) {
+    registerTool(tool: { name: string; executionMode?: string; parameters?: any; execute: (...args: any[]) => unknown }) {
       tools.push(tool);
     },
     sendMessage(message: unknown, sendOptions: unknown) {
@@ -1275,7 +1275,7 @@ test("cap guard: default 3 waves pass, the fourth is blocked with the escalation
   }
   const blocked = await firstCallResult(h, "c4", implementerWave(1));
   assert.equal(blocked?.block, true);
-  assert.match(blocked?.reason ?? "", /fix round 3 of 3 already used; escalate to the human/);
+  assert.match(blocked?.reason ?? "", /3 fix round\(s\) used against a cap of 3 \(granted rounds included\); escalate to the human/);
 });
 
 test("cap guard: maxFixRounds 0 blocks the first wave; 1 blocks the second; a chain implementer is cap-checked and counted", async () => {
@@ -1422,3 +1422,298 @@ test("replay: two implementer waves after the audit in verify restore fixRounds
   await inShip.emit("session_start");
   assert.equal(await firstCallResult(inShip, "c1", implementerWave(1)), undefined);
 });
+
+// --- Human overrule of the fix-round cap (spec 2026-09-14-fix-round-human-overrule) ---
+
+const grantResult = (rounds: number, reason = "human approved") => ({
+  type: "message",
+  message: { role: "toolResult", toolName: "phase_tracker", details: {
+    action: "grant_fix_rounds", rounds, reason,
+    phases: phases({ brainstorm: "complete", plan: "complete", implement: "complete", verify: "in_progress" }),
+  } },
+});
+
+const grant = async (h: ReturnType<typeof harness>, id: string, input: Record<string, unknown>) =>
+  (await h.tools.find((t) => t.name === "phase_tracker")!.execute(id, { action: "grant_fix_rounds", ...input }, undefined, undefined, h.ctx)) as {
+    content: { type: string; text: string }[];
+    details: { action: string; rounds?: number; reason?: string; error?: string };
+  };
+
+const exhaust = async (h: ReturnType<typeof harness>, rounds: number, prefix = "x") => {
+  for (let i = 1; i <= rounds; i++) {
+    assert.equal(await firstCallResult(h, `${prefix}${i}`, implementerWave(1)), undefined);
+    await h.emitEvent("tool_result", okWave(`${prefix}${i}`));
+  }
+};
+
+test("grant: funds extra waves and rejects another grant while credits remain", async () => {
+  const h = guardedHarness({ piGauntlet: { closureReview: { enforce: true } } });
+  await h.emit("session_start");
+  await exhaust(h, 3);
+  const res = await grant(h, "g1", { rounds: 2, reason: "I'm approving 2 more rounds" });
+  assert.equal(res.details.error, undefined);
+  assert.deepEqual([res.details.rounds, res.details.reason], [2, "I'm approving 2 more rounds"]);
+  assert.equal((await grant(h, "g2", { rounds: 1, reason: "more" })).details.error, "grant_fix_rounds: 2 granted round(s) still unused; spend them before granting more");
+  await exhaust(h, 2, "c");
+  const blocked = await firstCallResult(h, "c3", implementerWave(1));
+  assert.equal(blocked?.block, true);
+  assert.match(blocked?.reason ?? "", /5 fix round\(s\) used against a cap of 3 \(granted rounds included\)/);
+});
+
+test("grant: schema declares rounds as integer 1..MAX_SAFE_INTEGER; missing rounds or empty reason error without state change", async () => {
+  const h = guardedHarness({ piGauntlet: { closureReview: { maxFixRounds: 0 } } });
+  await h.emit("session_start");
+  const params = h.tools.find((t) => t.name === "phase_tracker")!.parameters;
+  const roundOptions = params.args[0].rounds.args[0].args[0];
+  assert.equal(params.args[0].rounds.args[0].kind, "Integer");
+  assert.deepEqual([roundOptions.minimum, roundOptions.maximum], [1, Number.MAX_SAFE_INTEGER]);
+  assert.ok(params.args[0].action.values.includes("grant_fix_rounds"));
+
+  const noRounds = await grant(h, "g1", { reason: "ok" });
+  assert.equal(noRounds.details.error, "grant_fix_rounds requires rounds: a positive integer");
+  assert.equal(noRounds.details.rounds, undefined);
+  const noReason = await grant(h, "g2", { rounds: 1, reason: "   " });
+  assert.equal(noReason.details.error, "grant_fix_rounds requires reason: the human's approval, quoted");
+  assert.equal(noReason.details.rounds, undefined);
+  assert.equal((await firstCallResult(h, "c1", implementerWave(1)))?.block, true, "no credit was granted");
+});
+
+test("grant: rejected when no cap block is live - before the audit, in implement, below the cap, enforce off, and in a child", async () => {
+  const expectNotLive = async (h: ReturnType<typeof harness>, used: number, cap: number) => {
+    const res = await grant(h, "g", { rounds: 1, reason: "ok" });
+    assert.equal(res.details.error, `grant_fix_rounds: no fix-round cap block is active (${used} used, cap ${cap}); nothing to overrule`);
+  };
+
+  const preAudit = harness({ cwd: tempCwd({ piGauntlet: { closureReview: { maxFixRounds: 0 } } }), branch: verifyBranch() });
+  await preAudit.emit("session_start");
+  await expectNotLive(preAudit, 0, 0);
+
+  const implement = harness({ cwd: tempCwd({ piGauntlet: { closureReview: { maxFixRounds: 0 } } }), branch: implementBranch([subagentResult(["conformance-reviewer"])]) });
+  await implement.emit("session_start");
+  await expectNotLive(implement, 0, 0);
+
+  const below = guardedHarness({ piGauntlet: { closureReview: { maxFixRounds: 3 } } });
+  await below.emit("session_start");
+  await exhaust(below, 2);
+  await expectNotLive(below, 2, 3);
+
+  const off = guardedHarness({ piGauntlet: { closureReview: { enforce: false, maxFixRounds: 0 } } });
+  await off.emit("session_start");
+  await expectNotLive(off, 0, 0);
+
+  const priorDepth = process.env.PI_SUBAGENT_DEPTH;
+  process.env.PI_SUBAGENT_DEPTH = "1";
+  let child: ReturnType<typeof harness>;
+  try {
+    child = guardedHarness({ piGauntlet: { closureReview: { maxFixRounds: 0 } } });
+  } finally {
+    if (priorDepth === undefined) delete process.env.PI_SUBAGENT_DEPTH;
+    else process.env.PI_SUBAGENT_DEPTH = priorDepth;
+  }
+  await child.emit("session_start");
+  await expectNotLive(child, 0, 0);
+});
+
+test("grant: only qualifying synchronous parent task waves spend credits", async () => {
+  const h = guardedHarness({ piGauntlet: { closureReview: { maxFixRounds: 0 } } });
+  await h.emit("session_start");
+  await grant(h, "g", { rounds: 1, reason: "ok" });
+  await h.emitEvent("tool_result", waveResult("e1", [{ agent: "code-reviewer", exitCode: 0 }]));
+  await h.emitEvent("tool_result", waveResult("e2", [{ agent: "implementer", exitCode: 0 }], true));
+  await h.emitEvent("tool_result", waveResult("e3", []));
+  assert.equal((await firstCallResult(h, "a", { ...implementerWave(1), async: true }))?.block, true);
+  assert.equal((await firstCallResult(h, "l", loneImplementer()))?.block, true);
+  assert.equal(await firstCallResult(h, "c", implementerWave(1)), undefined);
+  await h.emitEvent("tool_result", okWave("c"));
+  assert.equal((await firstCallResult(h, "d", implementerWave(1)))?.block, true);
+
+  // In a child (PI_SUBAGENT_DEPTH >= 1, fixed at registration) both the cap gate and observeFixWave
+  // are dormant, so credit consumption has no public effect; the observable contract is dormancy.
+  const priorDepth = process.env.PI_SUBAGENT_DEPTH;
+  process.env.PI_SUBAGENT_DEPTH = "1";
+  let child: ReturnType<typeof harness>;
+  try {
+    child = guardedHarness({ piGauntlet: { closureReview: { maxFixRounds: 0 } } }, [grantResult(1), subagentResult(["implementer"])]);
+  } finally {
+    if (priorDepth === undefined) delete process.env.PI_SUBAGENT_DEPTH;
+    else process.env.PI_SUBAGENT_DEPTH = priorDepth;
+  }
+  await child.emit("session_start");
+  assert.equal(await firstCallResult(child, "child-wave", implementerWave(1)), undefined, "child session: cap gate and observer are dormant, so the replayed grant and implementer result have no observable effect");
+});
+
+test("grant replay restores and spends the recorded pool independent of current cap; rejected grants restore no credit", async () => {
+  const trail = [subagentResult(["implementer"]), subagentResult(["implementer"]), subagentResult(["implementer"]), grantResult(2), subagentResult(["implementer"])];
+  const h = guardedHarness({ piGauntlet: { closureReview: { maxFixRounds: 3 } } }, trail);
+  await h.emit("session_start");
+  assert.equal(
+    (await grant(h, "g", { rounds: 1, reason: "more" })).details.error,
+    "grant_fix_rounds: 1 granted round(s) still unused; spend them before granting more",
+  );
+  assert.equal(await firstCallResult(h, "c", implementerWave(1)), undefined);
+  await h.emitEvent("tool_result", okWave("c"));
+  const blocked = await firstCallResult(h, "d", implementerWave(1));
+  assert.equal(blocked?.block, true);
+  assert.match(blocked?.reason ?? "", /5 fix round\(s\) used against a cap of 3 \(granted rounds included\)/);
+
+  // Same trail at cap 5: replay yields fixRounds = 4 (cap not live yet); lowering the live cap
+  // exposes the one replayed credit, then wave 5 passes on the counter and wave 6 blocks.
+  const capChanged = guardedHarness({ piGauntlet: { closureReview: { maxFixRounds: 5 } } }, trail);
+  await capChanged.emit("session_start");
+  assert.equal(
+    (await grant(capChanged, "g", { rounds: 1, reason: "more" })).details.error,
+    "grant_fix_rounds: no fix-round cap block is active (4 used, cap 5); nothing to overrule",
+    "replayed fixRounds = 4 regardless of cap on disk",
+  );
+  // Lower the cap on disk without spending a wave: the block goes live at 4 >= 3 and the grant
+  // probe now reads the replayed pool - exactly one credit, independent of the cap at replay time.
+  writeFileSync(join(capChanged.ctx.cwd, ".pi", "settings.json"), JSON.stringify({ piGauntlet: { closureReview: { maxFixRounds: 3 } } }));
+  assert.equal(
+    (await grant(capChanged, "g2", { rounds: 1, reason: "more" })).details.error,
+    "grant_fix_rounds: 1 granted round(s) still unused; spend them before granting more",
+    "same credits regardless of cap on disk",
+  );
+  writeFileSync(join(capChanged.ctx.cwd, ".pi", "settings.json"), JSON.stringify({ piGauntlet: { closureReview: { maxFixRounds: 5 } } }));
+  assert.equal(await firstCallResult(capChanged, "c", implementerWave(1)), undefined);
+  await capChanged.emitEvent("tool_result", okWave("c"));
+  const blockedAt5 = await firstCallResult(capChanged, "d", implementerWave(1));
+  assert.equal(blockedAt5?.block, true);
+  assert.match(blockedAt5?.reason ?? "", /5 fix round\(s\) used against a cap of 5 \(granted rounds included\)/);
+
+  const rejected = guardedHarness({ piGauntlet: { closureReview: { maxFixRounds: 0 } } }, [{
+    type: "message",
+    message: {
+      role: "toolResult",
+      toolName: "phase_tracker",
+      details: { action: "grant_fix_rounds", error: "grant_fix_rounds requires rounds: a positive integer", phases: phases({ verify: "in_progress" }) },
+    },
+  }]);
+  await rejected.emit("session_start");
+  assert.equal((await firstCallResult(rejected, "c1", implementerWave(1)))?.block, true, "no credits from a rejected grant");
+});
+
+test("grant reset: start implement and reset zero credits (live and replay); start verify --force keeps them", async () => {
+  const settings = { piGauntlet: { closureReview: { maxFixRounds: 0 }, flowGuards: { enforce: false } } };
+
+  const force = guardedHarness(settings, [grantResult(1)]);
+  await force.emit("session_start");
+  await force.tools.find((t) => t.name === "phase_tracker")!.execute("p", { action: "start", phase: "verify", force: true }, undefined, undefined, force.ctx);
+  assert.equal(await firstCallResult(force, "c", implementerWave(1)), undefined);
+
+  const liveImpl = guardedHarness(settings);
+  await liveImpl.emit("session_start");
+  await grant(liveImpl, "g", { rounds: 1, reason: "ok" });
+  const tool = liveImpl.tools.find((t) => t.name === "phase_tracker")!;
+  for (const [id, input] of [
+    ["p1", { action: "skip", phase: "verify", reason: "amendment" }],
+    ["p2", { action: "start", phase: "implement", force: true }],
+    ["p3", { action: "complete", phase: "implement" }],
+    ["p4", { action: "start", phase: "verify", force: true }],
+  ] as const) {
+    assert.equal(((await tool.execute(id, input, undefined, undefined, liveImpl.ctx)) as { details: { error?: string } }).details.error, undefined);
+  }
+  await liveImpl.emitEvent("tool_result", waveResult("audit", [{ agent: "conformance-reviewer", exitCode: 0 }]));
+  assert.equal((await firstCallResult(liveImpl, "c1", implementerWave(1)))?.block, true, "credits zeroed by start implement (cap 0 blocks)");
+
+  const reset = guardedHarness(settings);
+  await reset.emit("session_start");
+  await grant(reset, "g", { rounds: 1, reason: "ok" });
+  const resetTool = reset.tools.find((t) => t.name === "phase_tracker")!;
+  await resetTool.execute("p", { action: "reset" }, undefined, undefined, reset.ctx);
+  assert.match((await grant(reset, "g2", { rounds: 1, reason: "ok" })).details.error ?? "", /no fix-round cap block is active/);
+  for (const [id, input] of [
+    ["p1", { action: "start", phase: "brainstorm" }],
+    ["p2", { action: "complete", phase: "brainstorm" }],
+    ["p3", { action: "start", phase: "plan" }],
+    ["p4", { action: "complete", phase: "plan" }],
+    ["p5", { action: "start", phase: "implement" }],
+    ["p6", { action: "complete", phase: "implement" }],
+    ["p7", { action: "start", phase: "verify" }],
+  ] as const) {
+    assert.equal(((await resetTool.execute(id, input, undefined, undefined, reset.ctx)) as { details: { error?: string } }).details.error, undefined);
+  }
+  await reset.emitEvent("tool_result", waveResult("audit", [{ agent: "conformance-reviewer", exitCode: 0 }]));
+  assert.equal((await firstCallResult(reset, "c1", implementerWave(1)))?.block, true, "credits zeroed by reset (cap 0 blocks)");
+
+  const replayImpl = harness({
+    cwd: tempCwd(settings),
+    branch: verifyBranch([
+      subagentResult(["conformance-reviewer"]),
+      grantResult(1),
+      phaseResult("skip", phases({ brainstorm: "complete", plan: "complete", implement: "complete", verify: "skipped" })),
+      phaseResult("start", phases({ brainstorm: "complete", plan: "complete", implement: "in_progress", verify: "skipped" })),
+      phaseResult("complete", phases({ brainstorm: "complete", plan: "complete", implement: "complete", verify: "skipped" })),
+      phaseResult("start", phases({ brainstorm: "complete", plan: "complete", implement: "complete", verify: "in_progress" })),
+      subagentResult(["conformance-reviewer"]),
+    ]),
+  });
+  await replayImpl.emit("session_start");
+  assert.equal((await firstCallResult(replayImpl, "c1", implementerWave(1)))?.block, true, "replayed start implement zeroed credits");
+
+  const replayReset = harness({
+    cwd: tempCwd(settings),
+    branch: verifyBranch([
+      subagentResult(["conformance-reviewer"]),
+      grantResult(1),
+      phaseResult("reset", phases({})),
+      phaseResult("start", phases({ brainstorm: "in_progress" })),
+      phaseResult("complete", phases({ brainstorm: "complete" })),
+      phaseResult("start", phases({ brainstorm: "complete", plan: "in_progress" })),
+      phaseResult("complete", phases({ brainstorm: "complete", plan: "complete" })),
+      phaseResult("start", phases({ brainstorm: "complete", plan: "complete", implement: "in_progress" })),
+      phaseResult("complete", phases({ brainstorm: "complete", plan: "complete", implement: "complete" })),
+      phaseResult("start", phases({ brainstorm: "complete", plan: "complete", implement: "complete", verify: "in_progress" })),
+      subagentResult(["conformance-reviewer"]),
+    ]),
+  });
+  await replayReset.emit("session_start");
+  assert.equal((await firstCallResult(replayReset, "c1", implementerWave(1)))?.block, true, "replayed reset zeroed credits");
+});
+
+test("grant: block reason gives action, settings path, and live-read guidance", async () => {
+  const h = guardedHarness({ piGauntlet: { closureReview: { maxFixRounds: 0 } } });
+  await h.emit("session_start");
+  const reason = (await firstCallResult(h, "c", implementerWave(1)))?.reason ?? "";
+  assert.match(reason, /phase_tracker\(\{ action: "grant_fix_rounds"/);
+  assert.ok(reason.includes(join(h.ctx.cwd, ".pi", "settings.json")));
+  assert.match(reason, /no restart.*restate model and maxFixRounds/s);
+});
+
+test("gauntlet_setting registration requests sequential execution", () => {
+  assert.equal(harness().tools.find((t) => t.name === "gauntlet_setting")!.executionMode, "sequential");
+});
+
+test("grant renderResult shows count and reason", async () => {
+  const h = guardedHarness({ piGauntlet: { closureReview: { maxFixRounds: 0 } } });
+  await h.emit("session_start");
+  const res = await grant(h, "g", { rounds: 2, reason: "go on" });
+  const tool = h.tools.find((t) => t.name === "phase_tracker")! as any;
+  const rendered = tool.renderResult(res, {}, { fg: (_c: string, s: string) => s, bold: (s: string) => s });
+  assert.match(JSON.stringify(rendered), /2.*go on/);
+});
+
+test("grant: child sessions cannot overrule even a zero cap", async () => {
+  const priorDepth = process.env.PI_SUBAGENT_DEPTH;
+  process.env.PI_SUBAGENT_DEPTH = "1";
+  let child: ReturnType<typeof harness>;
+  try {
+    child = guardedHarness({ piGauntlet: { closureReview: { maxFixRounds: 0 } } });
+  } finally {
+    if (priorDepth === undefined) delete process.env.PI_SUBAGENT_DEPTH;
+    else process.env.PI_SUBAGENT_DEPTH = priorDepth;
+  }
+  await child.emit("session_start");
+  assert.match((await grant(child, "g", { rounds: 1, reason: "ok" })).details.error ?? "", /no fix-round cap block is active/);
+});
+
+test("grant: accepts MAX_SAFE_INTEGER and current on-disk cap controls whether the block is live", async () => {
+  const h = guardedHarness({ piGauntlet: { closureReview: { maxFixRounds: 0 } } });
+  await h.emit("session_start");
+  const result = await grant(h, "g", { rounds: Number.MAX_SAFE_INTEGER, reason: "approved" });
+  assert.equal(result.details.rounds, Number.MAX_SAFE_INTEGER);
+
+  const changed = guardedHarness({ piGauntlet: { closureReview: { maxFixRounds: 0 } } });
+  await changed.emit("session_start");
+  writeFileSync(join(changed.ctx.cwd, ".pi", "settings.json"), JSON.stringify({ piGauntlet: { closureReview: { maxFixRounds: 1 } } }));
+  assert.match((await grant(changed, "g", { rounds: 1, reason: "ok" })).details.error ?? "", /0 used, cap 1/);
+});

package/extensions/phase-tracker.ts

@@ -56,9 +56,11 @@ interface PhaseState {
 type PhaseMap = Record<Phase, PhaseState>;
 
 interface PhaseTrackerDetails {
-  action: "start" | "complete" | "skip" | "status" | "reset" | "substep";
+  action: "start" | "complete" | "skip" | "status" | "reset" | "substep" | "grant_fix_rounds";
   phases: PhaseMap;
   error?: string;
+  rounds?: number;
+  reason?: string;
 }
 
 interface PlanCheckStamp {
@@ -206,10 +208,14 @@ const loneImplementerBlockReason =
   "a lone agent call runs unisolated and produces no worktree diff. " +
   "To disable this gate, set piGauntlet.closureReview.enforce: false.";
 
-const fixRoundCapBlockReason = (used: number, cap: number): string =>
-  `Conformance fix loop: fix round ${used} of ${cap} already used; escalate to the human ` +
-  "with the verdict trail instead of re-looping. " +
-  "To disable this gate, set piGauntlet.closureReview.enforce: false.";
+const fixRoundCapBlockReason = (used: number, cap: number, settingsPath: string): string =>
+  `Conformance fix loop: ${used} fix round(s) used against a cap of ${cap} (granted rounds included); ` +
+  "escalate to the human with the verdict trail instead of re-looping.\n" +
+  "If the human explicitly approves more rounds, record it and retry as a tasks wave: " +
+  'phase_tracker({ action: "grant_fix_rounds", rounds: <N>, reason: "<their words>" }).\n' +
+  `Last resort: set piGauntlet.closureReview.enforce: false in ${settingsPath} (disables all closure guards; ` +
+  "applies on the next tool call, no restart - a gauntlet_setting read in the same message sees the write; " +
+  "a repo closureReview block replaces the preset's whole block, so restate model and maxFixRounds alongside).";
 
 const closureModelBlockReason = (model: string, missing: number, total: number): string =>
   `Blocked: ${missing} of ${total} conformance-reviewer ${total === 1 ? "dispatch" : "entries"} ` +
@@ -255,7 +261,7 @@ const pathInSpecDirs = (rawPath: string, specDirs: string[]): boolean => {
 };
 
 const PhaseTrackerParams = Type.Object({
-  action: StringEnum(["start", "complete", "skip", "status", "reset", "substep"] as const, {
+  action: StringEnum(["start", "complete", "skip", "status", "reset", "substep", "grant_fix_rounds"] as const, {
     description: "Action to perform",
   }),
   phase: Type.Optional(
@@ -265,7 +271,14 @@ const PhaseTrackerParams = Type.Object({
   ),
   reason: Type.Optional(
     Type.String({
-      description: "Reason for skipping (required for skip action)",
+      description: "Reason (required for skip and grant_fix_rounds; for grant, the human's approval quoted)",
+    }),
+  ),
+  rounds: Type.Optional(
+    Type.Integer({
+      minimum: 1,
+      maximum: Number.MAX_SAFE_INTEGER,
+      description: "Extra fix rounds the human explicitly approved (grant_fix_rounds only)",
     }),
   ),
   force: Type.Optional(
@@ -328,6 +341,7 @@ export default function (pi: ExtensionAPI) {
   let phases: PhaseMap = emptyPhases();
   let conformanceDispatched = false;
   let fixRounds = 0;
+  let fixRoundCredits = 0;
   let gauntletEntered = false;
   // Shared by replay and the live tool_result hook so a resumed session enforces
   // the same budget. Evaluated BEFORE the same result may set the latch, so the
@@ -341,6 +355,7 @@ export default function (pi: ExtensionAPI) {
       isImplementerWave(details, isError) &&
       resolveClosureReview(loadGauntletSettings(ctx.cwd).gauntlet).enforce
     ) {
+      if (fixRoundCredits > 0) fixRoundCredits -= 1;
       fixRounds += 1;
     }
   };
@@ -420,6 +435,7 @@ export default function (pi: ExtensionAPI) {
     phases = emptyPhases();
     conformanceDispatched = false;
     fixRounds = 0;
+    fixRoundCredits = 0;
     gauntletEntered = false;
     planCheckStamp = undefined;
     attemptedRecoveryEdges.clear();
@@ -444,14 +460,17 @@ export default function (pi: ExtensionAPI) {
         const details = msg.details as PhaseTrackerDetails | undefined;
         if (details && !details.error) {
           phases = details.phases;
+          if (details.action === "grant_fix_rounds" && typeof details.rounds === "number") fixRoundCredits = details.rounds;
           gauntletEntered = nextGauntletEntered(gauntletEntered, details.action, details.phases.brainstorm.status);
           if (details.action === "start" && details.phases.implement.status === "in_progress") {
             conformanceDispatched = false;
             fixRounds = 0;
+            fixRoundCredits = 0;
           }
           if (details.action === "reset") {
             conformanceDispatched = false;
             fixRounds = 0;
+            fixRoundCredits = 0;
             planCheckStamp = undefined;
           }
         }
@@ -544,7 +563,12 @@ export default function (pi: ExtensionAPI) {
       }
       if (fixLoopWindow && collectAgents(event.input, "implementer").length > 0) {
         const cap = resolveClosureReview(g()).maxFixRounds;
-        if (fixRounds >= cap) return { block: true, reason: fixRoundCapBlockReason(fixRounds, cap) };
+        if (fixRounds >= cap) {
+          const funded = fixRoundCredits > 0 && (event.input as { async?: unknown })?.async !== true;
+          if (!funded) {
+            return { block: true, reason: fixRoundCapBlockReason(fixRounds, cap, join(ctx.cwd, ".pi", "settings.json")) };
+          }
+        }
       }
       const model = closureReviewModel();
       if (model && !hasAction) {
@@ -730,6 +754,7 @@ export default function (pi: ExtensionAPI) {
     label: "Gauntlet Setting",
     description: "Resolve merged piGauntlet.* settings (repo over preset); for skill use only.",
     parameters: GauntletSettingParams,
+    executionMode: "sequential",
     async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
       const { gauntlet, errors } = loadGauntletSettings(ctx.cwd);
       const payload =
@@ -914,6 +939,7 @@ export default function (pi: ExtensionAPI) {
           if (params.phase === "implement") {
             conformanceDispatched = false;
             fixRounds = 0;
+            fixRoundCredits = 0;
           }
           gauntletEntered = nextGauntletEntered(gauntletEntered, "start", phases.brainstorm.status);
           firedGuards.clear();
@@ -1080,6 +1106,7 @@ export default function (pi: ExtensionAPI) {
           ) as PhaseMap;
           conformanceDispatched = false;
           fixRounds = 0;
+          fixRoundCredits = 0;
           gauntletEntered = nextGauntletEntered(gauntletEntered, "reset", phases.brainstorm.status);
           firedGuards.clear();
           updateWidget(ctx);
@@ -1089,6 +1116,39 @@ export default function (pi: ExtensionAPI) {
           };
         }
 
+        case "grant_fix_rounds": {
+          const reject = (error: string) => ({
+            content: [{ type: "text" as const, text: `Error: ${error}` }],
+            details: { action: "grant_fix_rounds", phases: { ...phases }, error } as PhaseTrackerDetails,
+          });
+          if (params.rounds === undefined) return reject("grant_fix_rounds requires rounds: a positive integer");
+          const reason = params.reason?.trim() ?? "";
+          if (reason.length === 0) return reject("grant_fix_rounds requires reason: the human's approval, quoted");
+          const closure = resolveClosureReview(loadGauntletSettings(ctx.cwd).gauntlet);
+          const capLive =
+            !isSubagentChild &&
+            gauntletEntered &&
+            phases.verify.status === "in_progress" &&
+            conformanceDispatched &&
+            closure.enforce &&
+            fixRounds >= closure.maxFixRounds;
+          if (!capLive) {
+            return reject(
+              `grant_fix_rounds: no fix-round cap block is active (${fixRounds} used, cap ${closure.maxFixRounds}); nothing to overrule`,
+            );
+          }
+          if (fixRoundCredits > 0) {
+            return reject(`grant_fix_rounds: ${fixRoundCredits} granted round(s) still unused; spend them before granting more`);
+          }
+          fixRoundCredits = params.rounds;
+          return {
+            content: [
+              { type: "text", text: `Granted ${params.rounds} extra fix round(s) - reason: "${reason}"\n${formatStatus(phases)}` },
+            ],
+            details: { action: "grant_fix_rounds", rounds: params.rounds, reason, phases: { ...phases } } as PhaseTrackerDetails,
+          };
+        }
+
         default:
           return {
             content: [{ type: "text", text: `Unknown action: ${params.action}` }],
@@ -1160,6 +1220,14 @@ export default function (pi: ExtensionAPI) {
         }
         case "reset":
           return new Text(theme.fg("success", "✓ ") + theme.fg("muted", "Phase tracker reset"), 0, 0);
+        case "grant_fix_rounds":
+          return new Text(
+            theme.fg("success", "+ ") +
+              theme.fg("muted", `${details.rounds} extra fix round(s) granted`) +
+              theme.fg("dim", ` (${details.reason})`),
+            0,
+            0,
+          );
         default:
           return new Text(theme.fg("dim", "Done"), 0, 0);
       }

package/extensions/test-support/pi-stubs.mjs

@@ -22,16 +22,16 @@ const sources = {
     }
   `,
   "@sinclair/typebox": `
-    const schema = (...args) => ({ args });
+    const schema = (kind) => (...args) => ({ kind, args });
     export const Type = {
-      Object: schema,
-      Optional: schema,
-      String: schema,
-      Boolean: schema,
-      Union: schema,
-      Null: schema,
-      Array: schema,
-      Integer: schema,
+      Object: schema("Object"),
+      Optional: schema("Optional"),
+      String: schema("String"),
+      Boolean: schema("Boolean"),
+      Union: schema("Union"),
+      Null: schema("Null"),
+      Array: schema("Array"),
+      Integer: schema("Integer"),
     };
   `,
 };

package/package.json

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

package/skills/verification-before-completion/reference/conformance-check.md

@@ -126,8 +126,10 @@ partition from an earlier round.
 
 Mirrors `subagent-driven-development` Parallel-Wave Mode and reuses its
 `plan_tracker` progress surface. Runs entirely inside the gate — it invokes
-**no** `phase_tracker` calls (`phase_tracker({ phase: "implement" })` errors
-while verify is `in_progress`) and does **not** enter SDD's phase machinery.
+**no** phase-transition `phase_tracker` calls (`start`/`complete`/`skip`/`reset`
+- `phase_tracker({ phase: "implement" })` errors while verify is `in_progress`;
+the only `phase_tracker` call inside the loop is the human-approval
+`grant_fix_rounds` in step 6) and does **not** enter SDD's phase machinery.
 Only the fan-out/integrate/review shape and `plan_tracker` are reused. Every execution dispatch is foreground with top-level `async: false`, including retries and prose-described dispatches; an unexpected async handle is a configuration failure: stop and report, never poll or relaunch. `forceTopLevelAsync` is incompatible; see [pi-cohort dispatch configuration](https://github.com/jjuraszek/pi-cohort/blob/main/doc/configuration.md).
 
 **Precondition — worktree required.** The loop needs a worktree HEAD to branch
@@ -178,8 +180,11 @@ Per round:
    default `3`, floors negatives at `0`, coerces non-integers to `3`) reached
    with an open `fix` gap or repair item → **escalate to the human** with the per-gap
    round-by-round verdict trail. Escalation is the sole non-completing
-   terminal state — no silent re-loop, no auto-ship. Inside a
-   brainstorming-entered flow the phase tracker enforces both rules at
+   terminal state — no silent re-loop, no auto-ship. If the human explicitly
+   approves N more rounds, record `phase_tracker({ action: "grant_fix_rounds",
+   rounds: N, reason: "<their words>" })` and re-enter step 2; without that
+   approval, escalation stays terminal. Inside a brainstorming-entered flow
+   the phase tracker enforces both rules at
    tool-call time: a lone `agent: "implementer"` dispatch is blocked, and the
    wave after the cap is blocked (`closureReview.enforce: false` disables).
 
@@ -187,7 +192,7 @@ Per round:
 
 a. Run the full plan-header `Verification` set once (ad-hoc: the project's canonical test command). After R0 `CONFORMS` with no round run, the pre-R0 full run counts.
 b. Dispatch `code-reviewer` directly (foreground, `async: false`, `SCOPED_TEST_COMMANDS: none`) over `git diff <r0-head>..HEAD`; never via `/skill:requesting-code-review`. An empty diff is nothing to review - no dispatch.
-c. Repair items = every failing command from a + every Critical/Moderate finding from b (`Behaviour-change: yes` included; the re-audit is its origin check). None → write the closure block; done. Any at the cap → escalate per step 6 with the test/CR trail. Any under the cap → re-enter step 2 as a one-task `tasks` wave: one `implementer` whose task is every repair item verbatim (ownership boundary = the files in `git diff <r0-head>..HEAD`, the CR findings' `touched-files`, and the files each failing command's output names, `SCOPED_TEST_COMMANDS: none`, no `Gn` tracker task, no gap selection), integrate as one `conformance fix CR`, re-audit, then Convergence again. That wave counts against `maxFixRounds`. Later Convergence CRs keep the same `<r0-head>..HEAD` range.
+c. Repair items = every failing command from a + every Critical/Moderate finding from b (`Behaviour-change: yes` included; the re-audit is its origin check). None → write the closure block; done. Any at the cap → escalate per step 6 with the test/CR trail (an explicit human approval re-enters via `grant_fix_rounds`, as step 6 describes). Any under the cap → re-enter step 2 as a one-task `tasks` wave: one `implementer` whose task is every repair item verbatim (ownership boundary = the files in `git diff <r0-head>..HEAD`, the CR findings' `touched-files`, and the files each failing command's output names, `SCOPED_TEST_COMMANDS: none`, no `Gn` tracker task, no gap selection), integrate as one `conformance fix CR`, re-audit, then Convergence again. That wave counts against `maxFixRounds`. Later Convergence CRs keep the same `<r0-head>..HEAD` range.
 
 `conformance fix CR` is not a gap fix: it is absent from the `auto-applied fix commits` index and has no `revert conformance fix Gn` action at the finish gate.