pi-gauntlet 4.4.2 → 4.5.0

package/CHANGELOG.md

@@ -1,5 +1,41 @@
 # Changelog
 
+## v4.5.0 - 2026-07-30
+
+Recover stalled automatic handoffs without weakening gauntlet gates (#3). The existing
+phase-tracker now sends one branch-local, fire-and-forget continuation nudge when an
+`agent_settled` event leaves either `plan -> implement` or `verify -> ship` pending. The
+handler requires brainstorming entry, no active phase, a non-aborted stop, an exact
+recognized edge, an unspent ancestry-local attempt, and a final idle check. Recovery
+messages persist their edge in custom-message details, so repeated settlements and session
+reconstruction do not re-trigger the same unchanged handoff.
+
+The implementation remains deliberately narrow: no transition engine, retry loop, timer,
+settings key, phase mutation, or older-host fallback. Prompt wording now reinforces both
+automatic handoffs, while specification approval and the final branch disposition remain
+human gates. Pure classifier tests and real extension event tests cover edge selection,
+persistence, abort/idleness guards, competing-handler ordering, and one-shot behavior.
+
+## v4.4.3 - 2026-07-19
+
+Brainstorming is the sole gauntlet entry point (#2): gate all three phase-tracker
+enforcement surfaces (closure completion gate, closure-model guard, flow guards) on a
+durable `gauntletEntered` marker so the gauntlet is dormant unless brainstorming started
+the flow. A reflexive `phase_tracker start verify` on an ad-hoc one-liner no longer trips
+the closure gate or forces a spurious conformance dispatch.
+
+The marker is derived in `reconstructState` from the session branch (mirroring
+`conformanceDispatched`: reset on reconstruct, threaded through replay, updated in the live
+start/reset handlers via one `nextGauntletEntered` transition), so it survives pi-condense
+pruning and `--session` resume. All three surfaces gate marker-first, so a dormant
+out-of-flow session short-circuits before any settings load; in-flow behavior is unchanged
+(`brainstormActive` implies `gauntletEntered`). New pure helpers `nextGauntletEntered` /
+`closureGateBlocks` / `closureModelGuardApplies` / `flowGuardApplies` are unit-tested; the
+two settings-dependent surfaces inline-match their predicate (the `markerGuardApplies`
+convention) to preserve marker-first laziness. Docs (README, configuration.md, AGENTS.md,
+conformance-check.md, the `phase_tracker` tool description) reworded: enforcement is opt-in
+by brainstorming entry, not ambient.
+
 ## v4.4.2 - 2026-07-15
 
 Condense the finish-time conformance disposition gate to a dense, human-readable

package/README.md

@@ -38,9 +38,11 @@ Concretely, one change through the gauntlet:
 1. You describe the change. **`brainstorming`** sets up an isolated worktree, explores the codebase, and turns your description into a written spec. A multi-model critique runs on it automatically. **You read and approve the spec - human gate 1.** No implementation code exists yet.
 2. **`writing-plans`** decomposes the approved spec into atomic, independently-verifiable tasks, grouped into parallel waves where they don't touch the same files.
 3. **`subagent-driven-development`** executes the plan one task at a time, each in a fresh subagent, behind spec-compliance review then code-quality review. TDD-locked: red, green, refactor.
-4. **verify**: a whole-diff code review, then the **conformance gate** - a subagent reads the finished code and docs against your *original words* from step 1, not the plan, and reports per-requirement: delivered, partial, missing, drifted, or unauthorized. This gate is machine-blocked from being skipped. Compatible executable recommendations auto-run through an isolated fix-and-re-audit loop with no prompt; anything still open surfaces as a dense list - one line per decision, plain-language, with its recommended choice inline. Reply `1` to take every recommendation, or `2:` with per-item overrides; a current `CONFORMS` / no-concerns result goes straight to the branch options with no extra conformance sign-off.
+4. **verify**: a whole-diff code review, then the **conformance gate** - a subagent reads the finished code and docs against your *original words* from step 1, not the plan, and reports per-requirement: delivered, partial, missing, drifted, or unauthorized. Inside a brainstorming-entered flow this gate is machine-blocked from being skipped. Compatible executable recommendations auto-run through an isolated fix-and-re-audit loop with no prompt; anything still open surfaces as a dense list - one line per decision, plain-language, with its recommended choice inline. Reply `1` to take every recommendation, or `2:` with per-item overrides; a current `CONFORMS` / no-concerns result goes straight to the branch options with no extra conformance sign-off.
 5. **`finishing-a-development-branch`**: squash, PR, keep, or discard. **Human gate 2** - the only other decision you make.
 
+Only the machine-owned `plan -> implement` and `verify -> ship` handoffs receive a branch-local one-shot nudge after an unexpected settled stop; it is fire-and-forget, does not bypass either human gate, and older Pi hosts without `agent_settled` retain existing behavior.
+
 ```mermaid
 flowchart LR
     R([request]) --> B[brainstorm<br/>+ spec]
@@ -66,13 +68,13 @@ pi-gauntlet ships three kinds of pieces, layered on top of pi-cohort's dispatch:
 - **7 subagent personas** - the specialized child agents the skills dispatch via pi-cohort: `implementer`, `code-reviewer`, `spec-reviewer`, `conformance-reviewer`, `spec-summarizer`, `spec-council-member`, `spec-council-synthesizer`. See [doc/personas.md](./doc/personas.md) for what each one does and why its permissions are scoped the way they are.
 - **3 runtime extensions** - the enforcement layer. `plan-tracker` and `phase-tracker` are tools skills call to track progress (with a TUI widget); `verify-before-ship` is a hook that warns if you commit/push without a passing test run since your last edit. See [doc/configuration.md](./doc/configuration.md) for the settings each one reads.
 
-pi-gauntlet is **opinionated**: every non-trivial change rides this one pipeline. There's no separate "just edit a file and commit" path - the skills gate each other, so the phase-tracker extension mechanically blocks a phase from closing before its gate runs. Reach for a shortcut and a gate stops you; that's the design, not friction.
+pi-gauntlet is **opinionated**: every non-trivial change is *meant* to ride this one pipeline, entered through `brainstorming`. Enforcement is opt-in by entry, not ambient: once brainstorming starts a flow, the phase-tracker extension mechanically blocks a phase from closing before its gate runs. A change made *without* entering the flow (a typo, a formatting run, a dependency bump - see "When to use / when NOT to use") is not gated; the discipline of routing real work through the pipeline is a convention the tooling supports, not a trap it springs on every edit.
 
 ## Key concepts
 
 | Term | Meaning |
 | --- | --- |
-| Gate | A machine-enforced checkpoint between phases (e.g. `complete verify` is blocked until conformance review has run). Not a suggestion. |
+| Gate | A machine-enforced checkpoint between phases (e.g. within a brainstorming-entered flow, `complete verify` is blocked until conformance review has run). Not a suggestion. |
 | Spec council | Multi-model critique of the spec before you see it (`roasting-the-spec`); falls back to a single-model critique if no council is configured. |
 | Conformance gate | The closing check: does the delivered code + docs match your *original prompt*, not the derived plan? Compatible executable recommendations auto-fix first; anything still open renders as a dense one-line-per-decision list with each recommended choice inline. Reply `1` to accept all recommendations or `2:` with per-item overrides; a current `CONFORMS` / no-concerns handoff goes straight to branch options with no extra sign-off. |
 | Wave | A batch of plan tasks that don't touch the same files, dispatched to implementers in parallel. |

package/extensions/lib/phase-tracker-helpers.test.ts

@@ -3,6 +3,10 @@ import assert from "node:assert/strict";
 import {
   CONTEXT_DRAFT_MARKER,
   checkSubstep,
+  closureGateBlocks,
+  closureModelGuardApplies,
+  flowGuardApplies,
+  nextGauntletEntered,
   phaseLabel,
   parseGitCommit,
   resolveRepoDir,
@@ -10,8 +14,51 @@ import {
   markerBlockReason,
   transitionPhaseState,
   markerGuardApplies,
+  recoverableEdge,
+  type RecoveryPhaseMap,
+  type RecoveryPhaseStatus,
 } from "./phase-tracker-helpers.ts";
 
+const recoveryPhases = (
+  overrides: Partial<Record<keyof RecoveryPhaseMap, RecoveryPhaseStatus>> = {},
+): RecoveryPhaseMap =>
+  Object.fromEntries(
+    (["brainstorm", "plan", "implement", "verify", "ship"] as const).map((phase) => [
+      phase,
+      { status: overrides[phase] ?? "pending" },
+    ]),
+  ) as RecoveryPhaseMap;
+
+test("recoverableEdge: recognizes only the two authorized edges", () => {
+  assert.equal(recoverableEdge(recoveryPhases({ plan: "complete" })), "plan-implement");
+  assert.equal(recoverableEdge(recoveryPhases({ verify: "complete" })), "verify-ship");
+});
+
+test("recoverableEdge: rejects any active phase", () => {
+  for (const phase of ["brainstorm", "plan", "implement", "verify", "ship"] as const) {
+    const recoverable: Partial<Record<keyof RecoveryPhaseMap, RecoveryPhaseStatus>> = phase === "verify" || phase === "ship" ? { plan: "complete" } : { verify: "complete" };
+    assert.equal(recoverableEdge(recoveryPhases(recoverable)), phase === "verify" || phase === "ship" ? "plan-implement" : "verify-ship");
+    assert.equal(recoverableEdge(recoveryPhases({ ...recoverable, [phase]: "in_progress" })), undefined);
+  }
+});
+
+test("recoverableEdge: rejects invalid source and destination states", () => {
+  for (const status of ["pending", "in_progress", "skipped"] as const) {
+    assert.equal(recoverableEdge(recoveryPhases({ plan: status })), undefined);
+    assert.equal(recoverableEdge(recoveryPhases({ verify: status })), undefined);
+  }
+  for (const status of ["in_progress", "complete", "skipped"] as const) {
+    assert.equal(recoverableEdge(recoveryPhases({ plan: "complete", implement: status })), undefined);
+    assert.equal(recoverableEdge(recoveryPhases({ verify: "complete", ship: status })), undefined);
+  }
+});
+
+test("recoverableEdge: rejects unrelated and ambiguous phase maps", () => {
+  assert.equal(recoverableEdge(recoveryPhases()), undefined);
+  assert.equal(recoverableEdge(recoveryPhases({ brainstorm: "complete", implement: "complete" })), undefined);
+  assert.equal(recoverableEdge(recoveryPhases({ plan: "complete", verify: "complete" })), undefined);
+});
+
 test("checkSubstep: in_progress -> ok", () => {
   assert.deepEqual(checkSubstep("in_progress"), { ok: true });
 });
@@ -118,3 +165,48 @@ test("markerGuardApplies: gated by flowGuards.enforce and brainstorm in_progress
   assert.equal(markerGuardApplies(true, "in_progress"), true);
   assert.equal(markerGuardApplies(true, "pending"), false);
 });
+
+test("nextGauntletEntered: arms only when a start makes brainstorm in_progress", () => {
+  assert.equal(nextGauntletEntered(false, "start", "in_progress"), true);
+  assert.equal(nextGauntletEntered(true, "start", "in_progress"), true); // re-arm idempotent
+});
+
+test("nextGauntletEntered: reset always disarms", () => {
+  assert.equal(nextGauntletEntered(true, "reset", "pending"), false);
+  assert.equal(nextGauntletEntered(true, "reset", "in_progress"), false);
+  assert.equal(nextGauntletEntered(false, "reset", "pending"), false);
+});
+
+test("nextGauntletEntered: marker survives downstream actions", () => {
+  assert.equal(nextGauntletEntered(true, "start", "complete"), true); // start plan/implement (brainstorm already complete)
+  assert.equal(nextGauntletEntered(true, "complete", "complete"), true);
+  assert.equal(nextGauntletEntered(true, "substep", "in_progress"), true);
+});
+
+test("nextGauntletEntered: a non-brainstorm start never arms a dormant flow", () => {
+  assert.equal(nextGauntletEntered(false, "start", "complete"), false); // cold start verify/implement
+  assert.equal(nextGauntletEntered(false, "start", "skipped"), false);
+  assert.equal(nextGauntletEntered(false, "complete", "pending"), false);
+});
+
+test("closureGateBlocks: blocks only for verify + entered + enforce + not-yet-dispatched", () => {
+  assert.equal(closureGateBlocks("verify", true, true, false), true);
+  assert.equal(closureGateBlocks("verify", false, true, false), false); // incident: not entered -> no block
+  assert.equal(closureGateBlocks("verify", true, true, true), false); // already dispatched
+  assert.equal(closureGateBlocks("verify", true, false, false), false); // enforce off
+  assert.equal(closureGateBlocks("plan", true, true, false), false); // wrong phase
+});
+
+test("flowGuardApplies: requires both an active guard phase and an entered flow", () => {
+  assert.equal(flowGuardApplies(true, true), true);
+  assert.equal(flowGuardApplies(true, false), false); // not entered
+  assert.equal(flowGuardApplies(false, true), false); // phase not active
+  assert.equal(flowGuardApplies(false, false), false);
+});
+
+test("closureModelGuardApplies: requires both an entered flow and closure enforcement", () => {
+  assert.equal(closureModelGuardApplies(true, true), true);
+  assert.equal(closureModelGuardApplies(false, true), false); // not entered -> dormant
+  assert.equal(closureModelGuardApplies(true, false), false); // enforce off
+  assert.equal(closureModelGuardApplies(false, false), false);
+});

package/extensions/lib/phase-tracker-helpers.ts

@@ -10,6 +10,21 @@ export const CONTEXT_DRAFT_MARKER = "# CONTEXT DRAFT - NOT A SPEC - fully replac
 
 export type SubstepCheck = { ok: true } | { ok: false; error: string };
 
+export type RecoveryEdge = "plan-implement" | "verify-ship";
+export type RecoveryPhaseStatus = "pending" | "in_progress" | "complete" | "skipped";
+export type RecoveryPhaseMap = Record<
+  "brainstorm" | "plan" | "implement" | "verify" | "ship",
+  { status: RecoveryPhaseStatus }
+>;
+
+export function recoverableEdge(phases: RecoveryPhaseMap): RecoveryEdge | undefined {
+  if (Object.values(phases).some((phase) => phase.status === "in_progress")) return undefined;
+  const planImplement = phases.plan.status === "complete" && phases.implement.status === "pending";
+  const verifyShip = phases.verify.status === "complete" && phases.ship.status === "pending";
+  if (planImplement === verifyShip) return undefined;
+  return planImplement ? "plan-implement" : "verify-ship";
+}
+
 export function checkSubstep(phaseStatus: string): SubstepCheck {
   if (phaseStatus === "in_progress") return { ok: true };
   return { ok: false, error: `substep requires an in_progress phase (status is ${phaseStatus})` };
@@ -90,6 +105,46 @@ export function markerGuardApplies(flowGuardsEnforced: boolean, brainstormStatus
   return flowGuardsEnforced && brainstormStatus === "in_progress";
 }
 
+// Flow-entry marker (spec 2026-07-19-sole-gauntlet-entry-point). The gauntlet is
+// opt-in: enforcement is dormant unless brainstorming started this flow. A `start`
+// that leaves brainstorm in_progress is the unique arming signal (exactly one phase
+// is in_progress at a time; the start target is not stored but is inferable). `reset`
+// disarms; every other action preserves the running marker so it survives brainstorm
+// -> plan -> implement -> verify. brainstormStatus is the phase status AFTER the action.
+export function nextGauntletEntered(prev: boolean, action: string, brainstormStatus: string): boolean {
+  if (action === "reset") return false;
+  if (action === "start" && brainstormStatus === "in_progress") return true;
+  return prev;
+}
+
+// Closure completion-gate decision. Marker-first: a non-entered flow never blocks
+// `complete verify`. Executable contract for the extension's inlined check (same
+// define-and-test-but-inline pattern as markerGuardApplies).
+export function closureGateBlocks(
+  phase: string,
+  gauntletEntered: boolean,
+  closureEnforced: boolean,
+  conformanceDispatched: boolean,
+): boolean {
+  return phase === "verify" && gauntletEntered && closureEnforced && !conformanceDispatched;
+}
+
+// Closure-model-guard applicability. Marker-first: the extension inlines this with the
+// settings read (closureEnforced()) as a lazy call AFTER gauntletEntered, so a dormant
+// (out-of-flow) session performs no settings I/O. This predicate is the tested contract
+// for that inlined check (same define-test-and-inline pattern as markerGuardApplies /
+// closureGateBlocks); it takes the already-resolved booleans, never triggering the read.
+export function closureModelGuardApplies(gauntletEntered: boolean, closureEnforced: boolean): boolean {
+  return gauntletEntered && closureEnforced;
+}
+
+// Flow-guard applicability: a guard fires only when its phase is active AND the flow
+// was entered via brainstorming. Both inputs are in-memory, so the extension calls
+// this directly with no settings-load cost.
+export function flowGuardApplies(phaseActive: boolean, gauntletEntered: boolean): boolean {
+  return phaseActive && gauntletEntered;
+}
+
 export const markerBlockReason = (file: string): string =>
   `Blocked: ${file} still begins with the context-draft marker - the spec-writing ` +
   `overwrite has not happened. Overwrite the draft with the real spec (write tool, ` +

package/extensions/phase-tracker.test.ts

@@ -0,0 +1,159 @@
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import registerPhaseTracker from "./phase-tracker.ts";
+
+const PHASES = ["brainstorm", "plan", "implement", "verify", "ship"] as const;
+type Phase = (typeof PHASES)[number];
+type Status = "pending" | "in_progress" | "complete" | "skipped";
+
+const phases = (overrides: Partial<Record<Phase, Status>> = {}) =>
+  Object.fromEntries(PHASES.map((phase) => [phase, { status: overrides[phase] ?? "pending" }])) as Record<
+    Phase,
+    { status: Status }
+  >;
+
+const phaseResult = (action: string, state: Record<Phase, { status: Status }>) => ({
+  type: "message",
+  message: { role: "toolResult", toolName: "phase_tracker", details: { action, phases: state } },
+});
+
+const assistant = (stopReason = "stop") => ({ type: "message", message: { role: "assistant", stopReason } });
+
+const enteredBranch = (state: Record<Phase, { status: Status }>, extra: unknown[] = []) => [
+  phaseResult("start", phases({ brainstorm: "in_progress" })),
+  phaseResult("complete", state),
+  ...extra,
+];
+
+function harness(options: { branch?: unknown[]; idle?: boolean; beforeSettled?: (setIdle: (idle: boolean) => void) => void; sendThrows?: boolean } = {}) {
+  const handlers = new Map<string, ((event: unknown, ctx: unknown) => unknown)[]>();
+  const tools: { name: string; execute: (...args: any[]) => unknown }[] = [];
+  const sent: { message: any; options: any }[] = [];
+  let idle = options.idle ?? true;
+  const ctx = {
+    cwd: process.cwd(),
+    hasUI: false,
+    isIdle: () => idle,
+    sessionManager: { getBranch: () => options.branch ?? [] },
+  };
+  const pi = {
+    on(event: string, handler: (event: unknown, context: unknown) => unknown) {
+      const registered = handlers.get(event) ?? [];
+      registered.push(handler);
+      handlers.set(event, registered);
+    },
+    registerTool(tool: { name: string; execute: (...args: any[]) => unknown }) {
+      tools.push(tool);
+    },
+    sendMessage(message: unknown, sendOptions: unknown) {
+      sent.push({ message, options: sendOptions });
+      if (options.sendThrows) throw new Error("send failed");
+    },
+  };
+  if (options.beforeSettled) pi.on("agent_settled", () => options.beforeSettled!(next => (idle = next)));
+  registerPhaseTracker(pi as any);
+  const emit = async (event: string) => {
+    for (const handler of handlers.get(event) ?? []) await handler({ type: event }, ctx);
+  };
+  return { emit, sent, tools, setIdle: (next: boolean) => (idle = next) };
+}
+
+const settle = async (h: ReturnType<typeof harness>) => {
+  await h.emit("session_start");
+  await h.emit("agent_settled");
+};
+
+test("agent_settled nudges each exact edge with persisted details", async () => {
+  for (const [state, edge, skill] of [
+    [phases({ brainstorm: "complete", plan: "complete" }), "plan-implement", "/skill:subagent-driven-development"],
+    [
+      phases({ brainstorm: "complete", plan: "complete", implement: "complete", verify: "complete" }),
+      "verify-ship",
+      "/skill:finishing-a-development-branch",
+    ],
+  ] as const) {
+    const h = harness({ branch: enteredBranch(state, [assistant()]) });
+    await settle(h);
+    assert.equal(h.sent.length, 1);
+    assert.deepEqual(h.sent[0].options, { triggerTurn: true });
+    assert.equal(h.sent[0].message.customType, "pi-gauntlet-transition-recovery");
+    assert.equal(h.sent[0].message.display, true);
+    assert.deepEqual(h.sent[0].message.details, { piGauntletRecoveryEdge: edge });
+    assert.match(h.sent[0].message.content, new RegExp(skill.replace(/[/-]/g, "\\$&")));
+  }
+});
+
+test("repeated settlement and persisted matching recovery details suppress a second nudge", async () => {
+  const state = phases({ brainstorm: "complete", plan: "complete" });
+  const h = harness({ branch: enteredBranch(state, [assistant()]) });
+  await settle(h);
+  await h.emit("agent_settled");
+  assert.equal(h.sent.length, 1);
+
+  const restored = harness({
+    branch: enteredBranch(state, [
+      { type: "custom_message", customType: "pi-gauntlet-transition-recovery", details: { piGauntletRecoveryEdge: "plan-implement" } },
+      assistant(),
+    ]),
+  });
+  await settle(restored);
+  assert.equal(restored.sent.length, 0);
+});
+
+test("foreign or malformed custom-message details do not suppress recovery", async () => {
+  const state = phases({ brainstorm: "complete", plan: "complete" });
+  for (const entry of [
+    { type: "custom_message", customType: "other", details: { piGauntletRecoveryEdge: "plan-implement" } },
+    { type: "custom_message", customType: "pi-gauntlet-transition-recovery", details: null },
+    { type: "custom_message", customType: "pi-gauntlet-transition-recovery", details: { piGauntletRecoveryEdge: "nope" } },
+  ]) {
+    const h = harness({ branch: enteredBranch(state, [entry, assistant()]) });
+    await settle(h);
+    assert.equal(h.sent.length, 1);
+  }
+});
+
+test("only brainstorming-entered, non-aborted settled flows recover", async () => {
+  const state = phases({ brainstorm: "complete", plan: "complete" });
+  const cold = harness({ branch: [phaseResult("complete", state), assistant()] });
+  await settle(cold);
+  assert.equal(cold.sent.length, 0);
+
+  const branch = enteredBranch(state, [assistant("aborted")]);
+  const aborted = harness({ branch });
+  await settle(aborted);
+  assert.equal(aborted.sent.length, 0);
+  branch.push(assistant());
+  await aborted.emit("agent_settled");
+  assert.equal(aborted.sent.length, 1);
+});
+
+test("active phases, non-idleness, and earlier competing handlers do not spend recovery", async () => {
+  for (const phase of PHASES) {
+    const h = harness({ branch: enteredBranch(phases({ brainstorm: phase === "brainstorm" ? "in_progress" : "complete", plan: phase === "plan" ? "in_progress" : "complete", implement: phase === "implement" ? "in_progress" : "pending", verify: phase === "verify" ? "in_progress" : "pending", ship: phase === "ship" ? "in_progress" : "pending" }), [assistant()]) });
+    await settle(h);
+    assert.equal(h.sent.length, 0, phase);
+  }
+
+  const state = phases({ brainstorm: "complete", plan: "complete" });
+  const notIdle = harness({ branch: enteredBranch(state, [assistant()]), idle: false });
+  await settle(notIdle);
+  notIdle.setIdle(true);
+  await notIdle.emit("agent_settled");
+  assert.equal(notIdle.sent.length, 1);
+
+  const ordered = harness({
+    branch: enteredBranch(state, [assistant()]),
+    beforeSettled: setIdle => setIdle(false),
+  });
+  await settle(ordered);
+  assert.equal(ordered.sent.length, 0);
+});
+
+test("a throwing send spends the in-memory edge", async () => {
+  const h = harness({ branch: enteredBranch(phases({ brainstorm: "complete", plan: "complete" }), [assistant()]), sendThrows: true });
+  await h.emit("session_start");
+  await assert.rejects(h.emit("agent_settled"), /send failed/);
+  await h.emit("agent_settled");
+  assert.equal(h.sent.length, 1);
+});

package/extensions/phase-tracker.ts

@@ -26,12 +26,16 @@ import { loadGauntletSettings } from "./lib/gauntlet-settings-loader.ts";
 import {
   checkSubstep,
   findMarkerFile,
+  flowGuardApplies,
   markerBlockReason,
+  nextGauntletEntered,
   parseGitCommit,
   phaseLabel,
+  recoverableEdge,
   resolveRepoDir,
   STMT_START,
   transitionPhaseState,
+  type RecoveryEdge,
 } from "./lib/phase-tracker-helpers.ts";
 
 const PHASES = ["brainstorm", "plan", "implement", "verify", "ship"] as const;
@@ -78,6 +82,18 @@ const SHIP_ADVISORY =
   "menu is the human gate that resolves any carried-open decision. Only reopen verify if\n" +
   "a `fix` gap was left unresolved (neither fixed nor deferred).";
 
+const RECOVERY_CUSTOM_TYPE = "pi-gauntlet-transition-recovery";
+const RECOVERY_MESSAGES: Record<RecoveryEdge, string> = {
+  "plan-implement": "Continue the approved workflow now. Invoke /skill:subagent-driven-development.",
+  "verify-ship": "Continue the approved workflow now. Invoke /skill:finishing-a-development-branch.",
+};
+
+const recoveryEdgeFromDetails = (details: unknown): RecoveryEdge | undefined => {
+  if (!details || typeof details !== "object") return undefined;
+  const edge = (details as { piGauntletRecoveryEdge?: unknown }).piGauntletRecoveryEdge;
+  return edge === "plan-implement" || edge === "verify-ship" ? edge : undefined;
+};
+
 // --- Flow guards (spec 2026-06-17-gauntlet-flow-guards) ---
 
 const GUARD_PHASES: Phase[] = ["brainstorm", "plan", "implement"];
@@ -239,6 +255,8 @@ function formatStatus(phases: PhaseMap): string {
 export default function (pi: ExtensionAPI) {
   let phases: PhaseMap = emptyPhases();
   let conformanceDispatched = false;
+  let gauntletEntered = false;
+  const attemptedRecoveryEdges = new Set<RecoveryEdge>();
 
   // Warn-once-per-phase ledger; cleared on every phase transition and on reconstruct.
   const firedGuards = new Map<string, boolean>();
@@ -283,12 +301,29 @@ export default function (pi: ExtensionAPI) {
     }
   };
 
+  const branchLatestAssistantStopReason = (ctx: ExtensionContext): string | undefined => {
+    let stopReason: string | undefined;
+    for (const entry of ctx.sessionManager.getBranch()) {
+      if (entry.type === "message" && entry.message.role === "assistant") stopReason = entry.message.stopReason;
+    }
+    return stopReason;
+  };
+
   const reconstructState = (ctx: ExtensionContext) => {
     phases = emptyPhases();
     conformanceDispatched = false;
+    gauntletEntered = false;
+    attemptedRecoveryEdges.clear();
     firedGuards.clear();
     pendingGuardWarnings.clear();
     for (const entry of ctx.sessionManager.getBranch()) {
+      if (entry.type === "custom_message") {
+        if (entry.customType === RECOVERY_CUSTOM_TYPE) {
+          const edge = recoveryEdgeFromDetails(entry.details);
+          if (edge) attemptedRecoveryEdges.add(edge);
+        }
+        continue;
+      }
       if (entry.type !== "message") continue;
       const msg = entry.message;
       if (msg.role !== "toolResult") continue;
@@ -296,6 +331,7 @@ export default function (pi: ExtensionAPI) {
         const details = msg.details as PhaseTrackerDetails | undefined;
         if (details && !details.error) {
           phases = details.phases;
+          gauntletEntered = nextGauntletEntered(gauntletEntered, details.action, details.phases.brainstorm.status);
           if (details.action === "reset") conformanceDispatched = false;
         }
       } else if (msg.toolName === "subagent") {
@@ -325,6 +361,23 @@ export default function (pi: ExtensionAPI) {
     });
   }
 
+  pi.on("agent_settled", (_event, ctx) => {
+    const latestAssistantStopReason = branchLatestAssistantStopReason(ctx);
+    if (!gauntletEntered || latestAssistantStopReason === "aborted") return;
+    const edge = recoverableEdge(phases);
+    if (!edge || attemptedRecoveryEdges.has(edge) || !ctx.isIdle()) return;
+    attemptedRecoveryEdges.add(edge);
+    pi.sendMessage(
+      {
+        customType: RECOVERY_CUSTOM_TYPE,
+        content: RECOVERY_MESSAGES[edge],
+        display: true,
+        details: { piGauntletRecoveryEdge: edge },
+      },
+      { triggerTurn: true },
+    );
+  });
+
   pi.on("tool_call", async (event, ctx) => {
     // D3.b: one fresh settings read per event, lazily, only if a guard needs it.
     const addGuardWarning = (id: string, text: string) => {
@@ -345,7 +398,11 @@ export default function (pi: ExtensionAPI) {
     const specDirs = () => resolveFlowGuards(g()).specDirs;
 
     // Closure-review model guard - independent of flowGuards, gated by closureReview.enforce.
-    if (event.toolName === "subagent" && closureEnforced()) {
+    // gating contract: closureModelGuardApplies (see helpers). Marker-first: gauntletEntered
+    // short-circuits before closureEnforced()'s settings load, so an ad-hoc (out-of-flow)
+    // 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.
@@ -371,8 +428,10 @@ export default function (pi: ExtensionAPI) {
     // event no guard inspects (any read-only tool, or any tool in a dormant session)
     // returns here without touching disk. Only genuinely guardable events pay for g().
     const brainstormActive = phases.brainstorm.status === "in_progress";
-    const guardableWrite = (event.toolName === "write" || event.toolName === "edit") && brainstormActive;
-    const guardableBash = event.toolName === "bash" && activeGuardPhase() !== undefined;
+    const guardableWrite =
+      (event.toolName === "write" || event.toolName === "edit") && flowGuardApplies(brainstormActive, gauntletEntered);
+    const guardableBash =
+      event.toolName === "bash" && flowGuardApplies(activeGuardPhase() !== undefined, gauntletEntered);
     if (!guardableWrite && !guardableBash) return undefined;
 
     if (!flowGuardsEnforced()) return undefined;
@@ -527,7 +586,8 @@ export default function (pi: ExtensionAPI) {
     description:
       "Track workflow phase progress (brainstorm → plan → implement → verify → ship). " +
       "Actions: start (mark phase in_progress), complete (mark phase complete), " +
-      "skip (mark phase skipped with reason), status (show all phases), reset (clear all phases), substep (set/clear a substep label on an in_progress phase).",
+      "skip (mark phase skipped with reason), status (show all phases), reset (clear all phases), substep (set/clear a substep label on an in_progress phase). " +
+      "Drives gauntlet-flow enforcement entered via brainstorming; the closure gate, closure-model guard, and flow guards arm only when brainstorming started the flow. Ad-hoc start verify/start implement calls do not arm the gates. Not for ad-hoc use.",
     parameters: PhaseTrackerParams,
 
     async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
@@ -572,6 +632,7 @@ export default function (pi: ExtensionAPI) {
             };
           }
           phases = { ...phases, [params.phase]: transitionPhaseState("in_progress") as PhaseState };
+          gauntletEntered = nextGauntletEntered(gauntletEntered, "start", phases.brainstorm.status);
           firedGuards.clear();
           updateWidget(ctx);
           return {
@@ -598,8 +659,12 @@ export default function (pi: ExtensionAPI) {
               } as PhaseTrackerDetails,
             };
           }
+          // gating contract: closureGateBlocks (see helpers). gauntletEntered is the leading
+          // conjunct so a cold-session `complete verify` (the #2 incident) neither blocks nor
+          // loads settings; the remaining conjuncts match closureGateBlocks exactly.
           if (
             params.phase === "verify" &&
+            gauntletEntered &&
             resolveClosureReview(loadGauntletSettings(ctx.cwd).gauntlet).enforce &&
             !conformanceDispatched
           ) {
@@ -694,6 +759,7 @@ export default function (pi: ExtensionAPI) {
             PHASES.map((p) => [p, transitionPhaseState("pending")]),
           ) as PhaseMap;
           conformanceDispatched = false;
+          gauntletEntered = nextGauntletEntered(gauntletEntered, "reset", phases.brainstorm.status);
           firedGuards.clear();
           updateWidget(ctx);
           return {

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

@@ -0,0 +1,41 @@
+const sources = {
+  "@earendil-works/pi-ai": `export const StringEnum = (values, options = {}) => ({ values, ...options });`,
+  "@earendil-works/pi-coding-agent": `
+    export class SettingsManager {
+      static create() { return new SettingsManager(); }
+      getGlobalSettings() { return {}; }
+      getProjectSettings() { return {}; }
+      drainErrors() { return []; }
+    }
+    export const getAgentDir = () => "/tmp/pi-gauntlet-test-agent";
+  `,
+  "@earendil-works/pi-tui": `
+    export class Text {
+      constructor(text) { this.text = text; }
+    }
+  `,
+  "@sinclair/typebox": `
+    const schema = (...args) => ({ args });
+    export const Type = {
+      Object: schema,
+      Optional: schema,
+      String: schema,
+      Boolean: schema,
+      Union: schema,
+      Null: schema,
+    };
+  `,
+};
+
+export async function resolve(specifier, context, nextResolve) {
+  if (specifier in sources) return { url: `pi-gauntlet-test:${encodeURIComponent(specifier)}`, shortCircuit: true };
+  return nextResolve(specifier, context);
+}
+
+export async function load(url, context, nextLoad) {
+  if (url.startsWith("pi-gauntlet-test:")) {
+    const specifier = decodeURIComponent(url.slice("pi-gauntlet-test:".length));
+    return { format: "module", source: sources[specifier], shortCircuit: true };
+  }
+  return nextLoad(url, context);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-gauntlet",
-  "version": "4.4.2",
+  "version": "4.5.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,8 @@ You are the **orchestrator**. You read the plan, dispatch, review the review, de
 - A subagent returns `NEEDS_CONTEXT` or `BLOCKED` (see [Implementer Status](#implementer-status))
 - A reviewer finds issues the implementer cannot resolve in two attempts
 - A ⚠️ workflow warning fires
-- You hit the end of the plan (then stop and report — see [After All Tasks](#after-all-tasks-complete))
+
+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).
 
 Periodic "should I continue?" prompts add latency without adding safety. The plan is the contract; execute it.
 

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

@@ -168,10 +168,10 @@ Per round:
    including DELIVERED rows and their `evidence` `file:line`) and the round's
    fix diff. Inject `model:` call-site per `gauntlet_setting({ key:
    "closureReview" }).model` — same mechanism as the initial audit; omit
-   `model:` when it is `undefined` to inherit the parent's model. 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.
+   `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
    within the cap → re-partition (per the rule above) and start the next
    round. Cap (`gauntlet_setting({ key: "closureReview" }).maxFixRounds`,

package/skills/writing-plans/SKILL.md

@@ -231,7 +231,7 @@ Then auto-select the execution mode and proceed — no pause, no picker. The mod
 - **If any wave contains ≥2 tasks → Parallel-Wave Mode.** The strengthened Wave Grouping contract (files + runtime-resource disjoint) guarantees every multi-task wave is parallel-safe.
 - **Otherwise (pure dependency chain, one task per wave) → Sequential Mode.**
 
-Announce the selected mode in one line (transparency), then auto-invoke `/skill:subagent-driven-development` in this session. Do not wait for confirmation — the spec gate already happened, and the plan is a mechanical derivative. The only pauses from here are in-flight STOPs (`BLOCKED` / `NEEDS_CONTEXT`) and the end gate, both owned by the executor.
+Auto-invoke `/skill:subagent-driven-development` in this session. Do not wait for confirmation — the spec gate already happened, and the plan is a mechanical derivative. The only pauses from here are in-flight STOPs (`BLOCKED` / `NEEDS_CONTEXT`) and the end gate, both owned by the executor.
 
 ## Red Flags — STOP