pi-gauntlet 5.5.1 → 5.5.3

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## 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)
+- `phase-tracker`: two new closure-review blocks inside a brainstorming-entered flow once `verify` is in progress and a conformance audit has been observed - a lone top-level `agent: "implementer"` `subagent` dispatch is blocked (one-task `tasks` wave is the only isolated shape), and an implementer dispatch past `closureReview.maxFixRounds` is blocked with the escalation text. Rounds are counted from non-error results carrying an implementer child; the counter resets with the audit latch. `closureReview.enforce: false` disables both.
+- `closureReview.maxFixRounds` default 2 -> 3.
+- `conformance-check.md` / `dispatching-parallel-agents`: retries inside the conformance loop are one-task `tasks` waves and count against the cap.
+
+## v5.5.2 - 2026-09-13
+
+- `release.sh <level>` promotes the CHANGELOG `## Unreleased` section to `## vX.Y.Z - <date>` and commits it with `package.json` in the single `Release X.Y.Z` commit, so `patch`/`minor`/`major` now work here (the `current`-only path is gone). New CONFIG field `CHANGELOG_HEADING`.
+- Release skill: a user instruction naming the level is the approval - no proposal step or re-confirmation; bundled follow-ups run after `verify`.
+- AGENTS.md rewritten to always-on essentials plus routing; shared core bumped to v3. Persona frontmatter knobs table and pin rationale moved to `doc/personas.md`. Gold rule scoped to agent-initiated writes; a user instruction naming the write is its confirmation.
+- Added `.pi/gauntlet-overrides.md` (`tracker: github`, release path, write-gate carve-out for user-named writes).
+- `verification-before-completion/reference/conformance-check.md`: the conformance fix round is one parallel `implementer` `tasks` wave (greedy `Gn` selection, `conflicts` partners held) -> `git apply` -> scoped tests -> delta re-audit. Per-gap `spec-reviewer`, per-round `code-reviewer`, and the per-round full test set are gone. New **Convergence** step after every `CONFORMS`: full `Verification` set once, one direct `code-reviewer` over `git diff <r0-head>..HEAD`; repairs re-enter the round as a `conformance fix CR` wave that counts against `maxFixRounds`. Finish grammar, personas, and settings unchanged.
+
 ## v5.5.1 - 2026-09-10
 
 - `linear`: copyable, version-scoped recovery for attachment-download 401s resolves the decrypted credential through linearis instead of reading encrypted token storage. Restricts credential delivery to HTTPS Linear uploads, rejects redirects, and checks downloaded bytes; an offline regression executes the documented example.

package/agents/code-reviewer.md

@@ -1,6 +1,6 @@
 ---
 name: code-reviewer
-description: Production-readiness code review with prioritized findings (Critical blocks merge, Minor is a nit). Read-only — does not edit.
+description: Production-readiness code review with prioritized findings (Critical and Moderate block merge, Minor is a nit). Read-only — does not edit.
 tools: read, grep, find, ls, bash
 defaultContext: fresh
 inheritProjectContext: true
@@ -44,11 +44,15 @@ Parallel-safe: F1,F3 disjoint; F2 conflicts F1 (both touch auth.ts)
 Behaviour-change: yes | no
 ```
 
+Severity decides SHIP versus FIX_FIRST. A Critical or Moderate finding means
+FIX_FIRST. Minor-only findings and clean reports mean SHIP. REJECT overrides
+both: refuse a change that must not land at all.
+
 Severity:
 
 - **Critical** — must fix before merge (data loss, security, broken correctness on a common path, broken contract).
-- **Moderate** — should fix; open for discussion (significant but not strictly blocking).
-- **Minor** — nit, style, preference, suggestion.
+- **Moderate** — must fix before merge (significant defect or drift that does not rise to Critical).
+- **Minor** — nit, style, preference, suggestion; the only severity declinable without a fix round or re-review.
 
 Label every finding with a globally unique `F1..Fn` ID (no restart per severity),
 and a `touched-files:`/`touched-resources:` pair (files/resources a fix would

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

@@ -122,11 +122,12 @@ test("closureReview: enforce default true; false only when explicitly false", ()
   assert.equal(resolveClosureReview({ closureReview: { enforce: true } }).enforce, true);
 });
 
-test("closureReview: maxFixRounds default 2, <0 -> 0, non-int -> 2", () => {
-  assert.equal(resolveClosureReview({}).maxFixRounds, 2);
+test("closureReview: maxFixRounds default 3, <0 -> 0, non-int -> 3", () => {
+  assert.equal(resolveClosureReview({}).maxFixRounds, 3);
   assert.equal(resolveClosureReview({ closureReview: { maxFixRounds: 5 } }).maxFixRounds, 5);
+  assert.equal(resolveClosureReview({ closureReview: { maxFixRounds: 0 } }).maxFixRounds, 0);
   assert.equal(resolveClosureReview({ closureReview: { maxFixRounds: -3 } }).maxFixRounds, 0);
-  assert.equal(resolveClosureReview({ closureReview: { maxFixRounds: 1.5 } }).maxFixRounds, 2);
+  assert.equal(resolveClosureReview({ closureReview: { maxFixRounds: 1.5 } }).maxFixRounds, 3);
 });
 
 test("flowGuards: defaults + overrides", () => {

package/extensions/lib/gauntlet-settings.ts

@@ -84,7 +84,7 @@ export function resolveClosureReview(g: PiGauntlet): ClosureReviewResolved {
   const model = nonEmptyString(cr?.model) ? cr!.model.trim() : undefined;
   const enforce = cr?.enforce !== false;
   const raw = cr?.maxFixRounds;
-  const maxFixRounds = typeof raw === "number" && Number.isInteger(raw) ? (raw < 0 ? 0 : raw) : 2;
+  const maxFixRounds = typeof raw === "number" && Number.isInteger(raw) ? (raw < 0 ? 0 : raw) : 3;
   return { model, enforce, maxFixRounds };
 }
 

package/extensions/phase-tracker.test.ts

@@ -6,9 +6,14 @@ import { tmpdir } from "node:os";
 import { isAbsolute, join } from "node:path";
 import registerPhaseTracker from "./phase-tracker.ts";
 
+const originalSubagentDepth = process.env.PI_SUBAGENT_DEPTH;
+process.env.PI_SUBAGENT_DEPTH = "0";
+
 const tempDirs: string[] = [];
 after(() => {
   for (const dir of tempDirs) rmSync(dir, { recursive: true, force: true });
+  if (originalSubagentDepth === undefined) delete process.env.PI_SUBAGENT_DEPTH;
+  else process.env.PI_SUBAGENT_DEPTH = originalSubagentDepth;
 });
 
 const tempCwd = (settings?: unknown) => {
@@ -529,7 +534,8 @@ test("implement-phase commit with implementer newer than both reviewers warns",
     const warned = (await h.emitEvent("tool_result", commitResult("c1")))[0] as { content: { text: string }[] };
     assert.match(warned.content[0].text, /no spec-reviewer or code-reviewer observed/);
   } finally {
-    if (priorDepth !== undefined) process.env.PI_SUBAGENT_DEPTH = priorDepth;
+    if (priorDepth === undefined) delete process.env.PI_SUBAGENT_DEPTH;
+    else process.env.PI_SUBAGENT_DEPTH = priorDepth;
   }
 });
 
@@ -1164,3 +1170,255 @@ test("gauntlet_setting escalationLoop: setting absent -> ctx-derived main-loop m
   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");
 });
+
+// --- Conformance fix-loop dispatch guard (spec 2026-09-13-conformance-dispatch-guard) ---
+
+const verifyBranch = (extra: unknown[] = []) => [
+  ...implementBranch(),
+  phaseResult("complete", phases({ brainstorm: "complete", plan: "complete", implement: "complete" })),
+  phaseResult("start", phases({ brainstorm: "complete", plan: "complete", implement: "complete", verify: "in_progress" })),
+  ...extra,
+];
+
+const subagentCall = (id: string, input: unknown) => ({ toolName: "subagent", toolCallId: id, input });
+const loneImplementer = (extra: Record<string, unknown> = {}) => ({ agent: "implementer", task: "fix G1", ...extra });
+const implementerWave = (n = 1) => ({
+  tasks: Array.from({ length: n }, (_, i) => ({ agent: "implementer", task: `fix G${i + 1}`, worktree: true })),
+});
+
+const firstCallResult = async (h: ReturnType<typeof harness>, id: string, input: unknown) =>
+  (await h.emitEvent("tool_call", subagentCall(id, input)))[0] as { block?: boolean; reason?: string } | undefined;
+
+test("shape guard: lone implementer blocked in verify after the audit, with and without closureReview.model, async or not", async () => {
+  for (const settings of [
+    { piGauntlet: { closureReview: { enforce: true } } },
+    { piGauntlet: { closureReview: { enforce: true, model: "x/y" } } },
+  ]) {
+    const h = harness({ cwd: tempCwd(settings), branch: verifyBranch([subagentResult(["conformance-reviewer"])]) });
+    await h.emit("session_start");
+    const sync = await firstCallResult(h, "s1", loneImplementer());
+    assert.equal(sync?.block, true);
+    assert.match(sync?.reason ?? "", /dispatch implementers as a one-task tasks wave/);
+    assert.match(sync?.reason ?? "", /piGauntlet\.closureReview\.enforce: false/);
+    const async = await firstCallResult(h, "s2", loneImplementer({ async: true }));
+    assert.equal(async?.block, true);
+  }
+});
+
+test("shape guard: lone implementer passes before the audit, in implement, in ship, and on management calls", async () => {
+  const preLatch = harness({ branch: verifyBranch() });
+  await preLatch.emit("session_start");
+  assert.equal(await firstCallResult(preLatch, "s1", loneImplementer()), undefined);
+
+  const implement = harness({ branch: implementBranch([subagentResult(["conformance-reviewer"])]) });
+  await implement.emit("session_start");
+  assert.equal(await firstCallResult(implement, "s1", loneImplementer()), undefined);
+
+  const ship = harness({
+    branch: verifyBranch([
+      subagentResult(["conformance-reviewer"]),
+      phaseResult("complete", phases({ brainstorm: "complete", plan: "complete", implement: "complete", verify: "complete" })),
+      phaseResult("start", phases({ brainstorm: "complete", plan: "complete", implement: "complete", verify: "complete", ship: "in_progress" })),
+    ]),
+  });
+  await ship.emit("session_start");
+  assert.equal(await firstCallResult(ship, "s1", loneImplementer()), undefined);
+
+  const mgmt = harness({ branch: verifyBranch([subagentResult(["conformance-reviewer"])]) });
+  await mgmt.emit("session_start");
+  assert.equal(await firstCallResult(mgmt, "s1", { action: "status", agent: "implementer" }), undefined);
+});
+
+test("shape guard: dormant when the flow was never entered (cold start verify) and when closureReview.enforce is false", async () => {
+  const cold = harness({
+    cwd: tempCwd({ piGauntlet: { closureReview: { maxFixRounds: 0 } } }),
+    branch: [phaseResult("start", phases({ verify: "in_progress" })), subagentResult(["conformance-reviewer"])],
+  });
+  await cold.emit("session_start");
+  assert.equal(await firstCallResult(cold, "s1", loneImplementer()), undefined);
+  assert.equal(await firstCallResult(cold, "s2", implementerWave(1)), undefined);
+  assert.equal(await firstCallResult(cold, "s3", { chain: [{ agent: "implementer", task: "fix" }] }), undefined);
+
+  const off = harness({
+    cwd: tempCwd({ piGauntlet: { closureReview: { enforce: false } } }),
+    branch: verifyBranch([subagentResult(["conformance-reviewer"])]),
+  });
+  await off.emit("session_start");
+  assert.equal(await firstCallResult(off, "s1", loneImplementer()), undefined);
+});
+
+test("shape guard: a one-task tasks wave and a chain step are not the lone shape", async () => {
+  const h = harness({ branch: verifyBranch([subagentResult(["conformance-reviewer"])]) });
+  await h.emit("session_start");
+  assert.equal(await firstCallResult(h, "s1", implementerWave(1)), undefined);
+  assert.equal(await firstCallResult(h, "s2", { chain: [{ agent: "implementer", task: "fix" }] }), undefined);
+});
+
+const waveResult = (id: string, results: { agent: string; exitCode: number }[], isError = false) => ({
+  toolName: "subagent",
+  toolCallId: id,
+  isError,
+  content: [],
+  details: { results },
+});
+const okWave = (id: string) => waveResult(id, [{ agent: "implementer", exitCode: 0 }]);
+
+const guardedHarness = (settings: unknown, extra: unknown[] = []) =>
+  harness({ cwd: tempCwd(settings), branch: verifyBranch([subagentResult(["conformance-reviewer"]), ...extra]) });
+
+test("cap guard: default 3 waves pass, the fourth is blocked with the escalation text", async () => {
+  const h = guardedHarness({ piGauntlet: { closureReview: { enforce: true } } });
+  await h.emit("session_start");
+  for (let i = 1; i <= 3; i++) {
+    assert.equal(await firstCallResult(h, `c${i}`, implementerWave(2)), undefined, `round ${i} passes`);
+    await h.emitEvent("tool_result", okWave(`c${i}`));
+  }
+  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/);
+});
+
+test("cap guard: maxFixRounds 0 blocks the first wave; 1 blocks the second; a chain implementer is cap-checked and counted", async () => {
+  const zero = guardedHarness({ piGauntlet: { closureReview: { maxFixRounds: 0 } } });
+  await zero.emit("session_start");
+  assert.equal((await firstCallResult(zero, "c1", implementerWave(1)))?.block, true);
+
+  const one = guardedHarness({ piGauntlet: { closureReview: { maxFixRounds: 1 } } });
+  await one.emit("session_start");
+  assert.equal(await firstCallResult(one, "c1", { chain: [{ agent: "implementer", task: "fix" }] }), undefined);
+  await one.emitEvent("tool_result", okWave("c1"));
+  assert.equal((await firstCallResult(one, "c2", implementerWave(1)))?.block, true);
+});
+
+test("counter: results while closure review enforcement is off do not consume budget", async () => {
+  const h = guardedHarness({ piGauntlet: { closureReview: { enforce: false, maxFixRounds: 1 } } });
+  await h.emit("session_start");
+  await h.emitEvent("tool_result", okWave("c1"));
+  await h.emitEvent("tool_result", okWave("c2"));
+  writeFileSync(
+    join(h.ctx.cwd, ".pi", "settings.json"),
+    JSON.stringify({ piGauntlet: { closureReview: { enforce: true, maxFixRounds: 1 } } }),
+  );
+  assert.equal(await firstCallResult(h, "c3", implementerWave(1)), undefined);
+});
+
+test("fix-loop guard and counter are dormant in subagent children", async () => {
+  const priorDepth = process.env.PI_SUBAGENT_DEPTH;
+  process.env.PI_SUBAGENT_DEPTH = "1";
+  let live: ReturnType<typeof harness>;
+  let replay: ReturnType<typeof harness>;
+  try {
+    live = guardedHarness({ piGauntlet: { closureReview: { maxFixRounds: 0 } } });
+    replay = guardedHarness(
+      { piGauntlet: { closureReview: { maxFixRounds: 2 } } },
+      [subagentResult(["implementer"]), subagentResult(["implementer"])],
+    );
+  } finally {
+    if (priorDepth === undefined) delete process.env.PI_SUBAGENT_DEPTH;
+    else process.env.PI_SUBAGENT_DEPTH = priorDepth;
+  }
+
+  await live.emit("session_start");
+  assert.equal(await firstCallResult(live, "c1", loneImplementer()), undefined);
+  assert.equal(await firstCallResult(live, "c2", implementerWave(1)), undefined);
+  await live.emitEvent("tool_result", okWave("c2"));
+  await replay.emit("session_start");
+  assert.equal(await firstCallResult(replay, "c3", implementerWave(1)), undefined);
+});
+
+test("cap guard: non-implementer dispatches never blocked; enforce false passes everything", async () => {
+  const h = guardedHarness({ piGauntlet: { closureReview: { maxFixRounds: 0 } } });
+  await h.emit("session_start");
+  assert.equal(await firstCallResult(h, "r1", { agent: "conformance-reviewer", task: "re-audit" }), undefined);
+  assert.equal(await firstCallResult(h, "r2", { agent: "code-reviewer", task: "review" }), undefined);
+
+  const off = guardedHarness({ piGauntlet: { closureReview: { enforce: false, maxFixRounds: 0 } } });
+  await off.emit("session_start");
+  assert.equal(await firstCallResult(off, "c1", implementerWave(1)), undefined);
+  assert.equal(await firstCallResult(off, "c2", loneImplementer()), undefined);
+});
+
+test("counter: blocked, errored, empty, non-implementer, and out-of-window results do not count; non-zero exit does", async () => {
+  const h = guardedHarness({ piGauntlet: { closureReview: { maxFixRounds: 1 } } });
+  await h.emit("session_start");
+  await h.emitEvent("tool_result", waveResult("e1", [{ agent: "implementer", exitCode: 0 }], true));
+  await h.emitEvent("tool_result", waveResult("e2", []));
+  await h.emitEvent("tool_result", waveResult("e3", [{ agent: "code-reviewer", exitCode: 0 }]));
+  const blockedLone = await firstCallResult(h, "b1", loneImplementer());
+  assert.equal(blockedLone?.block, true);
+  assert.equal(await firstCallResult(h, "c1", implementerWave(1)), undefined, "budget untouched");
+  await h.emitEvent("tool_result", waveResult("c1", [{ agent: "implementer", exitCode: 1 }]));
+  assert.equal((await firstCallResult(h, "c2", implementerWave(1)))?.block, true);
+});
+
+test("counter: a ship-phase implementer wave with the latch set does not count", async () => {
+  const h = harness({
+    cwd: tempCwd({ piGauntlet: { closureReview: { maxFixRounds: 1 } } }),
+    branch: verifyBranch([
+      subagentResult(["conformance-reviewer"]),
+      phaseResult("complete", phases({ brainstorm: "complete", plan: "complete", implement: "complete", verify: "complete" })),
+      phaseResult("start", phases({ brainstorm: "complete", plan: "complete", implement: "complete", verify: "complete", ship: "in_progress" })),
+      subagentResult(["implementer"]),
+      phaseResult("start", phases({ brainstorm: "complete", plan: "complete", implement: "complete", verify: "in_progress", ship: "in_progress" })),
+    ]),
+  });
+  await h.emit("session_start");
+  assert.equal(await firstCallResult(h, "c1", implementerWave(1)), undefined);
+});
+
+test("counter reset: start implement and reset zero it; start verify --force keeps it", async () => {
+  const mk = () => guardedHarness({ piGauntlet: { closureReview: { maxFixRounds: 1 }, flowGuards: { enforce: false } } }, [subagentResult(["implementer"])]);
+
+  const force = mk();
+  await force.emit("session_start");
+  const forceTool = force.tools.find((t) => t.name === "phase_tracker")!;
+  const forced = (await forceTool.execute("p1", { action: "start", phase: "verify", force: true }, undefined, undefined, force.ctx)) as { details: { error?: string } };
+  assert.equal(forced.details.error, undefined);
+  assert.equal((await firstCallResult(force, "c1", implementerWave(1)))?.block, true, "budget survives verify --force");
+
+  const impl = mk();
+  await impl.emit("session_start");
+  const implTool = impl.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) {
+    const result = (await implTool.execute(id, input, undefined, undefined, impl.ctx)) as { details: { error?: string } };
+    assert.equal(result.details.error, undefined);
+  }
+  assert.equal(await firstCallResult(impl, "c1", loneImplementer()), undefined, "latch cleared by start implement");
+  await impl.emitEvent("tool_result", waveResult("audit", [{ agent: "conformance-reviewer", exitCode: 0 }]));
+  assert.equal(await firstCallResult(impl, "c2", implementerWave(1)), undefined, "counter cleared by start implement");
+
+  const reset = mk();
+  await reset.emit("session_start");
+  const resetTool = reset.tools.find((t) => t.name === "phase_tracker")!;
+  const resetResult = (await resetTool.execute("p1", { action: "reset" }, undefined, undefined, reset.ctx)) as { details: { error?: string } };
+  assert.equal(resetResult.details.error, undefined);
+  assert.equal(await firstCallResult(reset, "c1", loneImplementer()), undefined, "dormant after reset");
+});
+
+test("replay: two implementer waves after the audit in verify restore fixRounds 2; the same waves in ship restore 0", async () => {
+  const inVerify = guardedHarness({ piGauntlet: { closureReview: { maxFixRounds: 2 } } }, [
+    subagentResult(["implementer"]),
+    subagentResult(["implementer", "code-reviewer"]),
+  ]);
+  await inVerify.emit("session_start");
+  assert.equal((await firstCallResult(inVerify, "c1", implementerWave(1)))?.block, true);
+
+  const inShip = harness({
+    cwd: tempCwd({ piGauntlet: { closureReview: { maxFixRounds: 2 } } }),
+    branch: verifyBranch([
+      subagentResult(["conformance-reviewer"]),
+      phaseResult("complete", phases({ brainstorm: "complete", plan: "complete", implement: "complete", verify: "complete" })),
+      phaseResult("start", phases({ brainstorm: "complete", plan: "complete", implement: "complete", verify: "complete", ship: "in_progress" })),
+      subagentResult(["implementer"]),
+      subagentResult(["implementer"]),
+      phaseResult("start", phases({ brainstorm: "complete", plan: "complete", implement: "complete", verify: "in_progress", ship: "in_progress" })),
+    ]),
+  });
+  await inShip.emit("session_start");
+  assert.equal(await firstCallResult(inShip, "c1", implementerWave(1)), undefined);
+});

package/extensions/phase-tracker.ts

@@ -86,6 +86,17 @@ const qualifiesAsClosureDispatch = (details: unknown): boolean => {
   return d.results.some((r) => r?.agent === "conformance-reviewer" && r?.exitCode === 0);
 };
 
+// One conformance fix round = one non-error subagent result carrying at least one
+// implementer child, regardless of dispatch mode or per-child exit code (a failed
+// implementer still spent the round; its retry is the next one). Async and
+// management dispatches return results: [] and never count.
+const isImplementerWave = (details: unknown, isError: boolean | undefined): boolean => {
+  if (isError === true) return false;
+  const d = details as { results?: { agent?: unknown }[] } | undefined;
+  if (!d || !Array.isArray(d.results) || d.results.length === 0) return false;
+  return d.results.some((r) => r?.agent === "implementer");
+};
+
 // Review-cadence guard (spec 2026-08-12-execution-fidelity-hardening): presence-only
 // advisory ledger of the most recent completed implementer / spec-reviewer /
 // code-reviewer dispatch. Agents completing in the SAME dispatch share a sequence
@@ -164,22 +175,14 @@ const branchBlockReason = (phase: Phase): string =>
   "create/enter one with /skill:using-git-worktrees and run this there. " +
   "To override, set piGauntlet.flowGuards.enforce: false.";
 
-// Closure-review model guard: when piGauntlet.closureReview.model is configured,
-// a conformance-reviewer dispatch should inject that model call-site. The persona
-// ships model-free, so a bare omission silently inherits the parent session's
-// builder model - defeating the point of an independent closing gate. Walk the
-// single / tasks / chain / parallel dispatch shapes and collect the model of every
-// conformance-reviewer entry (undefined = absent/empty/non-string). A bare omission
-// is BLOCKED; an explicit model that differs from the configured one is WARNED
-// (non-blocking), preserving the documented retry-with-fallback hatch while
-// surfacing drift.
-const conformanceModels = (input: unknown): (string | undefined)[] => {
-  const models: (string | undefined)[] = [];
-  const norm = (m: unknown) => (typeof m === "string" && m.trim() ? m.trim() : undefined);
+// Walk the single / tasks / chain / parallel dispatch shapes and return every
+// entry whose `agent` matches `name` (the raw node, so callers can read its model).
+const collectAgents = (input: unknown, name: string): Record<string, unknown>[] => {
+  const hits: Record<string, unknown>[] = [];
   const collect = (node: unknown): void => {
     if (!node || typeof node !== "object") return;
     const o = node as Record<string, unknown>;
-    if (o.agent === "conformance-reviewer") models.push(norm(o.model));
+    if (o.agent === name) hits.push(o);
     for (const key of ["tasks", "chain", "parallel"] as const) {
       const v = o[key];
       if (Array.isArray(v)) for (const item of v) collect(item);
@@ -187,9 +190,27 @@ const conformanceModels = (input: unknown): (string | undefined)[] => {
     }
   };
   collect(input);
-  return models;
+  return hits;
 };
 
+const conformanceModels = (input: unknown): (string | undefined)[] =>
+  collectAgents(input, "conformance-reviewer").map((o) =>
+    typeof o.model === "string" && o.model.trim() ? o.model.trim() : undefined,
+  );
+
+// Conformance fix-loop dispatch guard (spec 2026-09-13-conformance-dispatch-guard):
+// after the first audit, pi-cohort honours worktree: true only in tasks mode, so a
+// lone implementer runs unisolated and yields no patch for the integrate step.
+const loneImplementerBlockReason =
+  'Conformance fix loop: dispatch implementers as a one-task tasks wave (tasks: [{ agent: "implementer", worktree: true, ... }]); ' +
+  "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 closureModelBlockReason = (model: string, missing: number, total: number): string =>
   `Blocked: ${missing} of ${total} conformance-reviewer ${total === 1 ? "dispatch" : "entries"} ` +
   `omitted a model while piGauntlet.closureReview.model is set to "${model}".\n` +
@@ -306,7 +327,23 @@ function formatStatus(phases: PhaseMap): string {
 export default function (pi: ExtensionAPI) {
   let phases: PhaseMap = emptyPhases();
   let conformanceDispatched = false;
+  let fixRounds = 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
+  // R0 audit result itself never counts as a wave.
+  const observeFixWave = (details: unknown, isError: boolean | undefined, ctx: ExtensionContext) => {
+    if (
+      !isSubagentChild &&
+      gauntletEntered &&
+      phases.verify.status === "in_progress" &&
+      conformanceDispatched &&
+      isImplementerWave(details, isError) &&
+      resolveClosureReview(loadGauntletSettings(ctx.cwd).gauntlet).enforce
+    ) {
+      fixRounds += 1;
+    }
+  };
   let planCheckStamp: PlanCheckStamp | undefined;
   const attemptedRecoveryEdges = new Set<RecoveryEdge>();
 
@@ -382,6 +419,7 @@ export default function (pi: ExtensionAPI) {
   const reconstructState = (ctx: ExtensionContext) => {
     phases = emptyPhases();
     conformanceDispatched = false;
+    fixRounds = 0;
     gauntletEntered = false;
     planCheckStamp = undefined;
     attemptedRecoveryEdges.clear();
@@ -409,9 +447,11 @@ export default function (pi: ExtensionAPI) {
           gauntletEntered = nextGauntletEntered(gauntletEntered, details.action, details.phases.brainstorm.status);
           if (details.action === "start" && details.phases.implement.status === "in_progress") {
             conformanceDispatched = false;
+            fixRounds = 0;
           }
           if (details.action === "reset") {
             conformanceDispatched = false;
+            fixRounds = 0;
             planCheckStamp = undefined;
           }
         }
@@ -423,6 +463,7 @@ export default function (pi: ExtensionAPI) {
           planCheckStamp = undefined;
         }
       } else if (msg.toolName === "subagent") {
+        observeFixWave(msg.details, msg.isError, ctx);
         if (qualifiesAsClosureDispatch(msg.details)) conformanceDispatched = true;
         observeCadence(msg.details);
       } else if (msg.toolName === "plan_tracker") {
@@ -492,10 +533,20 @@ export default function (pi: ExtensionAPI) {
     // subagent dispatch never loads settings or leaks a settingsErrorWarning onto its result.
     // Inline-matched (not called) so closureEnforced() stays a lazy second conjunct.
     if (event.toolName === "subagent" && gauntletEntered && closureEnforced()) {
-      const model = closureReviewModel();
-      // Only execution-mode dispatches carry a model; management/control modes
-      // (action: list/get/create/update/delete/status/...) execute nothing, so skip them.
+      // Only execution-mode dispatches carry a model or run agents; management/control
+      // modes (action: list/get/create/update/delete/status/...) execute nothing, so skip them.
       const hasAction = !!(event.input as { action?: unknown })?.action;
+      // Fix-loop window: verify in progress and the R0 audit observed. Read directly,
+      // not via activeGuardPhase() - verify is not a GUARD_PHASES member.
+      const fixLoopWindow = !isSubagentChild && !hasAction && phases.verify.status === "in_progress" && conformanceDispatched;
+      if (fixLoopWindow && (event.input as { agent?: unknown })?.agent === "implementer") {
+        return { block: true, reason: loneImplementerBlockReason };
+      }
+      if (fixLoopWindow && collectAgents(event.input, "implementer").length > 0) {
+        const cap = resolveClosureReview(g()).maxFixRounds;
+        if (fixRounds >= cap) return { block: true, reason: fixRoundCapBlockReason(fixRounds, cap) };
+      }
+      const model = closureReviewModel();
       if (model && !hasAction) {
         const configured = model.trim();
         const models = conformanceModels(event.input);
@@ -635,8 +686,9 @@ export default function (pi: ExtensionAPI) {
     return undefined;
   });
 
-  pi.on("tool_result", async (event) => {
+  pi.on("tool_result", async (event, ctx) => {
     if (event.toolName === "subagent") {
+      observeFixWave(event.details, event.isError, ctx);
       if (qualifiesAsClosureDispatch(event.details)) conformanceDispatched = true;
       observeCadence(event.details);
       const warning = pendingGuardWarnings.get(event.toolCallId);
@@ -859,7 +911,10 @@ export default function (pi: ExtensionAPI) {
           }
           phases = { ...phases, [params.phase]: transitionPhaseState("in_progress") as PhaseState };
           // A rewind must not inherit the prior verify's conformance latch.
-          if (params.phase === "implement") conformanceDispatched = false;
+          if (params.phase === "implement") {
+            conformanceDispatched = false;
+            fixRounds = 0;
+          }
           gauntletEntered = nextGauntletEntered(gauntletEntered, "start", phases.brainstorm.status);
           firedGuards.clear();
           updateWidget(ctx);
@@ -1024,6 +1079,7 @@ export default function (pi: ExtensionAPI) {
             PHASES.map((p) => [p, transitionPhaseState("pending")]),
           ) as PhaseMap;
           conformanceDispatched = false;
+          fixRounds = 0;
           gauntletEntered = nextGauntletEntered(gauntletEntered, "reset", phases.brainstorm.status);
           firedGuards.clear();
           updateWidget(ctx);

package/package.json

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

package/skills/dispatching-parallel-agents/SKILL.md

@@ -105,7 +105,7 @@ When agents return:
 
 **If integrated changes apply cleanly but the suite fails (semantic conflict):** agents made incompatible assumptions across disjoint files (renamed symbol, changed shape). Diagnose the incompatible pair and re-run the offending task sequentially on the integrated HEAD.
 
-**If some agents failed:** Integrate successful agents first (commit their work). Then retry the failed agent with fresh context that includes the integrated changes.
+**If some agents failed:** Integrate successful agents first (commit their work). Then retry the failed agent with fresh context that includes the integrated changes. Inside the conformance loop the retry is a one-task `tasks` wave, never a lone `agent: "implementer"`.
 
 ## Fix fan-out
 

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

@@ -142,29 +142,26 @@ prerequisites hold.
 Per round:
 
 1. **Synchronize gap tasks** — append only a genuinely new gap that is entering remediation, named `Gn: <gap origin clause verbatim, truncated>`; never `init`. Find existing gaps by their exact `Gn:` prefix and reuse that index even if origin wording changes. Carried-OPEN inventory-only gaps add nothing. Before dispatch, mark every remediated gap's existing index `in_progress`; a re-audit needing more work reopens that same `Gn` index. The lifecycle traces `[T1,T2]`, then `[T1,T2,G1]`, then `[T1,T2,G1,G2]`; no test-retry or review-round wrapper task.
-2. **Fix dispatch** — per `dispatching-parallel-agents` "Fix fan-out": a `disjoint`
-   group of ≥ 2 gaps (per the report's `Parallel-safe:` line) fixes in one parallel
-   foreground dispatch — one `implementer` per gap (fresh context, `async: false`,
-   `worktree: true`, `cwd` = the conformance worktree, task = the gap block verbatim
-   with `touched-files` as the ownership boundary). For an `UNAUTHORIZED` `fix` gap
+2. **Fix wave** — select gaps greedily in `Gn` order: take each `fix` gap unless a gap it `conflicts` with (per the report's `Parallel-safe:` line) is already taken; the certificate's `disjoint` grouping is ignored, and a certificate still malformed after the one re-ask means every gap `conflicts` with every other. Held gaps carry to the next round; the wave is never empty while an eligible `fix` gap exists. Dispatch **one** call - `subagent({ context: "fresh", async: false, tasks: [...] })` - with one `implementer` task per selected gap (`worktree: true`, `cwd` = the conformance worktree, task = the gap block verbatim with `touched-files` as the ownership boundary). A single gap is a one-task `tasks` call; a lone `agent: "implementer"` call never appears in this loop. For an `UNAUTHORIZED` `fix` gap
    whose `evidence` opens with the over-spec provenance (`spec "<section>" - "<clause>" (over-spec)`), the orchestrator adds the spec path to that gap's `touched-files` before dispatch,
    so the implementer deletes the surface **and** the clause/AC line in the same
    fix commit; the re-audit then has no `Rn` for it and no `MISSING` echo. The dispatch adds `SCOPED_TEST_COMMANDS`
-   to the gap block: the gap-relevant plan-declared commands, or `none` (the round's
-   test gate owns execution). `conflicts` pairs serialize. Gaps outside any ≥ 2-ID
-   `disjoint` group run sequentially as before. Then dispatch foreground `spec-reviewer`
-   per gap on the gap-block reference contract below.
+   to the gap block: the gap-relevant plan-declared commands, or `none`; on an ad-hoc no-plan path, the project's canonical test command.
 3. **Integrate** serially via `git apply` onto the worktree HEAD, one gap's
-   patch at a time. Failure handling is inherited verbatim from
+   patch at a time. Commit each per-gap fix with the message **`conformance fix Gn`** (durable,
+   `git log`-readable pre-squash) so the finish gate and any revert can identify
+   auto-applied fixes; a Convergence repair wave commits as one **`conformance fix CR`**.
+   Failure handling is inherited verbatim from
    `dispatching-parallel-agents` "Review and Integrate": textual conflict →
    re-run one agent sequentially with the other's integrated changes as
    context; semantic conflict (applies clean, suite fails) → re-run the
    offending task sequentially on integrated HEAD; a failed agent → integrate
    the successes, then retry the failure with fresh context including the
-   integrated changes. A `BLOCKED`/`NEEDS_CONTEXT` return surfaces to the user.
-4. **Test gate** on the integrated tree. In a plan flow, run the full plan-header `Verification` set once here; on an ad-hoc no-plan path, use the project's canonical test command. A failure re-enters the failure-handling rules above.
-5. **Round CR and completion** — run `code-reviewer` once on the round's cumulative fix delta (not per gap), foreground with `async: false` and `SCOPED_TEST_COMMANDS` = the round's gap-relevant commands, or `none` (the round's test gate owns execution). After integration, tests, and this CR accept the work, explicitly mark every remediated gap's same `Gn` index `complete`, before re-audit.
-6. **Re-audit**: foreground re-dispatch `conformance-reviewer` with `async: false` over the fixes **plus** the
+   integrated changes. Every re-run or retry inside this loop is itself a
+   one-task `tasks` wave (never a lone `agent: "implementer"`) and counts as a
+   wave against `maxFixRounds`. A `BLOCKED`/`NEEDS_CONTEXT` return surfaces to the user.
+4. **Scoped tests** on the integrated tree: the round's `SCOPED_TEST_COMMANDS` union. A failure re-enters the failure-handling rules above.
+5. **Re-audit**: foreground re-dispatch `conformance-reviewer` with `async: false` over the fixes **plus** the
    regression guard (any prior-`DELIVERED` requirement whose `evidence` file
    the fix diff touched). Pass the full prior conformance report (every row,
    including DELIVERED rows and their `evidence` `file:line`) and the round's
@@ -173,18 +170,26 @@ Per round:
    `model:` when it is `undefined` to inherit the parent's model. Inside a
    brainstorming-entered flow, the phase-tracker closure guard blocks a dispatch
    that omits `model:` when `closureReview.model` is set, and warns (non-blocking)
-   on one whose model differs.
-7. **Converge or continue**: verdict `CONFORMS` → record it, done. Open gaps
+   on one whose model differs. Mark every `Gn` the re-audit reports `DELIVERED`
+   `complete`; open ones stay `in_progress`.
+6. **Converge or continue**: verdict `CONFORMS` → Convergence below. Open gaps
    within the cap → re-partition (per the rule above) and start the next
    round. Cap (`gauntlet_setting({ key: "closureReview" }).maxFixRounds`,
-   default `2`, floors negatives at `0`, coerces non-integers to `2`) reached
-   with an open `fix` gap → **escalate to the human** with the per-gap
+   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.
+   terminal state — no silent re-loop, no auto-ship. 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).
 
-Commit each per-gap fix with the message **`conformance fix Gn`** (durable,
-`git log`-readable pre-squash) so the finish gate and any revert can identify
-auto-applied fixes.
+**Convergence** — runs after R0 `CONFORMS` and after every `CONFORMS` re-audit. `r0-head` is HEAD when the loop was entered (the R0 dispatch, or the finish-time `fix-now` entry) - the parent of the oldest `conformance fix` commit; `audited-base` stays the last audit's HEAD SHA.
+
+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.
+
+`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.
 
 **`maxFixRounds: 0`**: skip this loop entirely; every `recommended: fix` gap is
 carried OPEN to the finish gate per the precondition-unavailable
@@ -194,22 +199,6 @@ auto-fix, so treat `fix` gaps like any other deferred gap — unlike a cap > 0
 that is *exhausted*, which escalates mid-verify because the loop tried and
 could not converge.
 
-### `spec-reviewer` gap-block reference contract
-
-Per-gap `spec-reviewer` in step 2 above is a **pre-integration mechanical
-check**, distinct from the round-level re-audit in step 6 (which still
-references the *origin* — spec + original prompt — unchanged). Frame the
-per-gap dispatch against the **gap block**, not a plan task:
-
-- **Requirement** = the gap's `origin` + `remediation` (what must be true
-  after the fix).
-- **Closure proof** = the patch satisfies that requirement within the gap's
-  `touched-files` — nothing missing, nothing extra.
-- **Output** = `spec-reviewer`'s normal MATCH/DRIFT verdict, referenced to the
-  gap block instead of a plan task.
-
-This is a task-framing contract in the dispatch, not a new persona.
-
 ## Concern decomposition
 
 The main verification orchestrator — **not** `conformance-reviewer` — decomposes
@@ -459,15 +448,15 @@ concerns into one gap-scoped fix contract:
   boundary).
 
 Rescoped, accepted, and followed-up sibling concerns are **excluded** from the
-projection. The `implementer` and the pre-integration `spec-reviewer` receive
-this projected contract in place of the original whole-gap block.
-
-The projected task runs the existing full loop above: it retains the gap-level
-`conformance fix Gn` commit name, reruns the project's tests, runs
-`code-reviewer`, re-audits against the amended spec, and reenters the gate only
-if concerns remain. Gap-level revert stays available through the flat commit
-index. The gate records the final result by concern ID and title before showing
-branch integration options.
+projection. The `implementer` receives this projected contract in place of the
+original whole-gap block.
+
+The projected task runs the round and Convergence above with `r0-head` = HEAD at
+this entry: it retains the gap-level `conformance fix Gn` commit name, re-audits
+against the amended spec, and reenters the gate only if concerns remain.
+Gap-level revert stays available through the flat commit index. The gate records
+the final result by concern ID and title before showing branch integration
+options.
 
 ## Checklist
 

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

@@ -22,7 +22,7 @@ does not recurse into their leaves.
 whole-object, a repo file that sets only *one* leaf of a key silently drops the
 preset's other leaves for that key. A repo `closureReview: { "model": "..." }` with
 no `enforce`/`maxFixRounds` makes those fall back to their code defaults
-(`enforce` true, `maxFixRounds` 2), **not** to the preset's values. Define every
+(`enforce` true, `maxFixRounds` 3), **not** to the preset's values. Define every
 leaf you care about together in the file that owns the key. (Sibling keys are
 unaffected - only the key the repo redefines is replaced.)