pi-gauntlet 4.6.2 → 4.8.0

package/CHANGELOG.md

@@ -1,5 +1,39 @@
 # Changelog
 
+## v4.8.0 - 2026-08-12
+
+- `writing-plans`: mandatory plan-time recon (fixed one-variable scout template writing a draft to the plan path); plan header `**Verification:**` command set (tests + style + format, header-only); per-task format-and-lint step; scoped-test and header-only-entrypoint Self-Review checks.
+- `subagent-driven-development`: wave test gate runs the wave's declared commands only; SR-per-task + CR-per-wave stated as a commit precondition with a doc-only (SR-only) exemption; full verification set runs once at verify before the conformance dispatch; new Red Flags (SR+CR fusion; full run during implement).
+- `phase-tracker`: advisory review-cadence flow guard - implement-phase parent commits warn when the last implementer postdates both reviewers. Presence-only, never blocks, honors `flowGuards.enforce`.
+- **Behavior change** - `verify-before-ship` no longer watches `git commit` (still watches `git push` / `gh pr create`): local wave commits are not ship events, and warning on them trained per-wave full-CI runs.
+- `verification-before-completion`: evidence-proportionality rule (scoped commands prove scoped claims; the full entrypoint proves phase completion, once at verify).
+- `implementer`: REFACTOR runs task-declared tests, not "the full relevant test suite".
+
+## v4.7.0 - 2026-08-07
+
+Sanction the spec-in-hand resume gesture and guard the implement phase (#6).
+Sessions that start with an approved spec from a handoff doc previously ran
+fully unarmed - the observed incident implemented an entire plan inline in the
+main loop with every enforcement surface dormant.
+
+- `writing-plans` gains a "Resuming with a spec in hand" subsection: a
+  state-detected handoff entry (branch on `phase_tracker status`) that verifies
+  the spec, confirms approval, sets up the worktree, and arms `gauntletEntered`
+  via the existing `start brainstorm -> skip brainstorm -> start plan`
+  sequence, plus guidance for writing handoff docs. Prose only - no new skill,
+  no new tracker action.
+- Fourth flow guard in `phase-tracker`: a warn-once advisory on parent
+  `write`/`edit` in the armed implement window (`implement` in progress, or
+  `plan` complete with `implement` still pending), exempting
+  `flowGuards.specDirs` plus each spec dir's sibling `plans` dir. Advisory,
+  never blocks (merge-conflict resolution between parallel waves proceeds past
+  it); subagent children (`PI_SUBAGENT_DEPTH` >= 1) never trip it; disabled
+  with the other guards via `flowGuards.enforce: false`. No new settings key.
+- Regression coverage: resumed-session replay arming, recovery edge, and
+  closure gate; test stub `SettingsManager` now reads the repo settings layer.
+- The 2026-07-19 sole-entry-point spec carries a supersession banner scoped to
+  its sole-arming claim.
+
 ## v4.6.2 - 2026-08-07
 
 Trim the always-shipped tool descriptions of the gauntlet-internal tools to

package/README.md

@@ -66,9 +66,9 @@ pi-gauntlet ships three kinds of pieces, layered on top of pi-cohort's dispatch:
 
 - **13 skills** - the workflow logic. They activate automatically when pi sees the matching kind of task, and each one gates the next: `brainstorming`, `writing-plans`, `roasting-the-spec`, `test-driven-development`, `subagent-driven-development`, `dispatching-parallel-agents`, `verification-before-completion`, `systematic-debugging`, `requesting-code-review`, `receiving-code-review`, `using-git-worktrees`, `finishing-a-development-branch`, `writing-skills`.
 - **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.
+- **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 push or open a PR without a passing test run since your last edit; a phase-tracker flow guard reminds on implement-phase commits missing spec/code review. See [doc/configuration.md](./doc/configuration.md) for the settings each one reads.
 
-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.
+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, and warns once if the main loop writes code during implement (subagents own implement-phase edits). 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
 

package/agents/implementer.md

@@ -16,7 +16,7 @@ You are an implementation specialist. You execute an approved plan using strict
 
 1. **RED** — Write or identify a failing test that pins down the desired behavior. Run it. Confirm it fails for the right reason (not a typo, not an import error).
 2. **GREEN** — Write the minimum code that makes the test pass. Run it.
-3. **REFACTOR** — Clean up without changing behavior. Run the full relevant test suite.
+3. **REFACTOR** — Clean up without changing behavior. Run the tests the task declares (its `Test:` files and stated commands).
 
 ## Three-scenario TDD
 

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

@@ -6,6 +6,8 @@ import {
   closureGateBlocks,
   closureModelGuardApplies,
   flowGuardApplies,
+  implementWriteGuardApplies,
+  implementExemptDirs,
   nextGauntletEntered,
   phaseLabel,
   parseGitCommit,
@@ -210,3 +212,29 @@ test("closureModelGuardApplies: requires both an entered flow and closure enforc
   assert.equal(closureModelGuardApplies(true, false), false); // enforce off
   assert.equal(closureModelGuardApplies(false, false), false);
 });
+
+test("implementWriteGuardApplies: window is implement in_progress or plan-complete/implement-pending", () => {
+  assert.equal(implementWriteGuardApplies("complete", "in_progress", true, false), true);
+  assert.equal(implementWriteGuardApplies("complete", "pending", true, false), true); // armed post-plan gap (incident window)
+  assert.equal(implementWriteGuardApplies("skipped", "in_progress", true, false), true); // window is implement itself
+  assert.equal(implementWriteGuardApplies("in_progress", "pending", true, false), false); // still planning
+  assert.equal(implementWriteGuardApplies("skipped", "pending", true, false), false); // plan skipped: accepted residual gap (spec Edge cases)
+  assert.equal(implementWriteGuardApplies("complete", "complete", true, false), false); // implement done
+});
+
+test("implementWriteGuardApplies: requires an armed flow and a parent process", () => {
+  assert.equal(implementWriteGuardApplies("complete", "in_progress", false, false), false); // unarmed
+  assert.equal(implementWriteGuardApplies("complete", "in_progress", true, true), false); // subagent child
+});
+
+test("implementExemptDirs: adds each spec dir's sibling plans dir, deduped", () => {
+  assert.deepEqual(implementExemptDirs(["doc/specs"]), ["doc/specs", "doc/plans"]);
+  assert.deepEqual(implementExemptDirs(["specs"]), ["specs", "plans"]);
+  assert.deepEqual(implementExemptDirs(["doc/specs/"]), ["doc/specs", "doc/plans"]);
+  assert.deepEqual(implementExemptDirs(["a/plans"]), ["a/plans"]); // already a plans dir: Set dedups
+  assert.deepEqual(implementExemptDirs(["doc/specs", "svc/doc/specs"]), ["doc/specs", "doc/plans", "svc/doc/specs", "svc/doc/plans"]);
+});
+
+test("nextGauntletEntered: skip preserves the marker (resume gesture)", () => {
+  assert.equal(nextGauntletEntered(true, "skip", "skipped"), true);
+});

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

@@ -145,6 +145,39 @@ export function flowGuardApplies(phaseActive: boolean, gauntletEntered: boolean)
   return phaseActive && gauntletEntered;
 }
 
+// Implement-write guard window (spec 2026-08-07-resume-spec-in-hand). Fires while
+// implement runs, or in the armed post-plan gap (plan complete, implement not yet
+// started) - the incident window where neither recoverableEdge (needs an idle
+// session) nor an implement-scoped check could fire. Marker-first like every other
+// surface; the enforce + path + fired conjuncts stay at the call site (settings and
+// ledger live there). isSubagentChild: implementer forks inherit extensions and
+// replay the parent's phase state, so without it every implementer's first write
+// would trip a spurious advisory.
+export function implementWriteGuardApplies(
+  planStatus: string,
+  implementStatus: string,
+  gauntletEntered: boolean,
+  isSubagentChild: boolean,
+): boolean {
+  const windowOpen =
+    implementStatus === "in_progress" || (planStatus === "complete" && implementStatus === "pending");
+  return windowOpen && gauntletEntered && !isSubagentChild;
+}
+
+// Exempt dirs for the implement-write guard: the configured spec dirs plus each
+// one's sibling `plans` dir (doc/specs -> doc/plans; plans live there per
+// writing-plans) - a routine parent plan-doc update must not burn the one-shot warning.
+export function implementExemptDirs(specDirs: string[]): string[] {
+  const dirs = new Set<string>();
+  for (const dir of specDirs) {
+    const parts = dir.split("/").filter((c) => c.length > 0);
+    if (parts.length === 0) continue;
+    dirs.add(parts.join("/"));
+    dirs.add([...parts.slice(0, -1), "plans"].join("/"));
+  }
+  return [...dirs];
+}
+
 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

@@ -1,7 +1,25 @@
 import assert from "node:assert/strict";
-import { test } from "node:test";
+import { after, test } from "node:test";
+import { mkdtempSync, mkdirSync, writeFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
 import registerPhaseTracker from "./phase-tracker.ts";
 
+const tempDirs: string[] = [];
+after(() => {
+  for (const dir of tempDirs) rmSync(dir, { recursive: true, force: true });
+});
+
+const tempCwd = (settings?: unknown) => {
+  const dir = mkdtempSync(join(tmpdir(), "phase-tracker-test-"));
+  tempDirs.push(dir);
+  if (settings !== undefined) {
+    mkdirSync(join(dir, ".pi"), { recursive: true });
+    writeFileSync(join(dir, ".pi", "settings.json"), JSON.stringify(settings));
+  }
+  return dir;
+};
+
 const PHASES = ["brainstorm", "plan", "implement", "verify", "ship"] as const;
 type Phase = (typeof PHASES)[number];
 type Status = "pending" | "in_progress" | "complete" | "skipped";
@@ -25,13 +43,20 @@ const enteredBranch = (state: Record<Phase, { status: Status }>, extra: unknown[
   ...extra,
 ];
 
-function harness(options: { branch?: unknown[]; idle?: boolean; beforeSettled?: (setIdle: (idle: boolean) => void) => void; sendThrows?: boolean } = {}) {
+const resumedBranch = (rest: Partial<Record<Phase, Status>>) => [
+  phaseResult("start", phases({ brainstorm: "in_progress" })),
+  phaseResult("skip", phases({ brainstorm: "skipped" })),
+  phaseResult("start", phases({ brainstorm: "skipped", plan: "in_progress" })),
+  phaseResult("complete", phases({ brainstorm: "skipped", ...rest })),
+];
+
+function harness(options: { cwd?: string; 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(),
+    cwd: options.cwd ?? tempCwd(),
     hasUI: false,
     isIdle: () => idle,
     sessionManager: { getBranch: () => options.branch ?? [] },
@@ -55,7 +80,12 @@ function harness(options: { branch?: unknown[]; idle?: boolean; beforeSettled?:
   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 emitEvent = async (name: string, event: unknown) => {
+    const results: unknown[] = [];
+    for (const handler of handlers.get(name) ?? []) results.push(await handler(event, ctx));
+    return results;
+  };
+  return { emit, emitEvent, sent, tools, ctx, setIdle: (next: boolean) => (idle = next) };
 }
 
 const settle = async (h: ReturnType<typeof harness>) => {
@@ -157,3 +187,292 @@ test("a throwing send spends the in-memory edge", async () => {
   await h.emit("agent_settled");
   assert.equal(h.sent.length, 1);
 });
+
+const writeCall = (id: string, path: string) => ({ toolName: "write", toolCallId: id, input: { path } });
+const writeResult = (id: string) => ({ toolName: "write", toolCallId: id, content: [{ type: "text", text: "ok" }] });
+
+test("implement-write guard: warns once on parent write outside exempt dirs, exempt paths silent", async () => {
+  const priorDepth = process.env.PI_SUBAGENT_DEPTH;
+  delete process.env.PI_SUBAGENT_DEPTH; // isolate from an ambient subagent depth in the test-runner's own process
+  try {
+    const h = harness({ cwd: tempCwd(), branch: resumedBranch({ plan: "complete", implement: "in_progress" }) });
+    await h.emit("session_start");
+    await h.emitEvent("tool_call", writeCall("t1", "doc/specs/x.md"));
+    assert.equal((await h.emitEvent("tool_result", writeResult("t1")))[0], undefined); // spec dir exempt
+    await h.emitEvent("tool_call", writeCall("t2", "doc/plans/x.md"));
+    assert.equal((await h.emitEvent("tool_result", writeResult("t2")))[0], undefined); // plans dir exempt
+    await h.emitEvent("tool_call", writeCall("t3", "src/x.ts"));
+    const warned = (await h.emitEvent("tool_result", writeResult("t3")))[0] as { content: { text: string }[] };
+    assert.match(warned.content[0].text, /implement/);
+    assert.match(warned.content[0].text, /subagent-driven-development/);
+    assert.match(warned.content[0].text, /merge-conflict/);
+    await h.emitEvent("tool_call", writeCall("t4", "src/y.ts"));
+    assert.equal((await h.emitEvent("tool_result", writeResult("t4")))[0], undefined); // warn-once
+  } finally {
+    if (priorDepth !== undefined) process.env.PI_SUBAGENT_DEPTH = priorDepth;
+  }
+});
+
+test("implement-write guard: fires in the armed post-plan gap (plan complete, implement pending)", async () => {
+  const priorDepth = process.env.PI_SUBAGENT_DEPTH;
+  delete process.env.PI_SUBAGENT_DEPTH;
+  try {
+    const h = harness({ cwd: tempCwd(), branch: resumedBranch({ plan: "complete" }) });
+    await h.emit("session_start");
+    await h.emitEvent("tool_call", writeCall("t1", "src/x.ts"));
+    const warned = (await h.emitEvent("tool_result", writeResult("t1")))[0] as { content: { text: string }[] };
+    assert.match(warned.content[0].text, /implement/);
+  } finally {
+    if (priorDepth !== undefined) process.env.PI_SUBAGENT_DEPTH = priorDepth;
+  }
+});
+
+test("implement-write guard: silent when unarmed, when enforce is false, and in subagent children", async () => {
+  const cold = harness({ cwd: tempCwd(), branch: [phaseResult("complete", phases({ plan: "complete", implement: "in_progress" }))] });
+  await cold.emit("session_start");
+  await cold.emitEvent("tool_call", writeCall("t1", "src/x.ts"));
+  assert.equal((await cold.emitEvent("tool_result", writeResult("t1")))[0], undefined);
+
+  const off = harness({
+    cwd: tempCwd({ piGauntlet: { flowGuards: { enforce: false } } }),
+    branch: resumedBranch({ plan: "complete", implement: "in_progress" }),
+  });
+  await off.emit("session_start");
+  await off.emitEvent("tool_call", writeCall("t1", "src/x.ts"));
+  assert.equal((await off.emitEvent("tool_result", writeResult("t1")))[0], undefined);
+
+  const priorDepth = process.env.PI_SUBAGENT_DEPTH;
+  process.env.PI_SUBAGENT_DEPTH = "1";
+  try {
+    const child = harness({ cwd: tempCwd(), branch: resumedBranch({ plan: "complete", implement: "in_progress" }) });
+    await child.emit("session_start");
+    await child.emitEvent("tool_call", writeCall("t1", "src/x.ts"));
+    assert.equal((await child.emitEvent("tool_result", writeResult("t1")))[0], undefined);
+  } finally {
+    if (priorDepth === undefined) delete process.env.PI_SUBAGENT_DEPTH;
+    else process.env.PI_SUBAGENT_DEPTH = priorDepth;
+  }
+});
+
+test("brainstorm write guard is unchanged by the implement guard", async () => {
+  const priorDepth = process.env.PI_SUBAGENT_DEPTH;
+  delete process.env.PI_SUBAGENT_DEPTH;
+  try {
+    const h = harness({ cwd: tempCwd(), branch: [phaseResult("start", phases({ brainstorm: "in_progress" }))] });
+    await h.emit("session_start");
+    await h.emitEvent("tool_call", writeCall("t1", "src/x.ts"));
+    const warned = (await h.emitEvent("tool_result", writeResult("t1")))[0] as { content: { text: string }[] };
+    assert.match(warned.content[0].text, /brainstorm/);
+  } finally {
+    if (priorDepth !== undefined) process.env.PI_SUBAGENT_DEPTH = priorDepth;
+  }
+});
+
+test("resumed session: plan-implement recovery edge fires (AC 3)", async () => {
+  const h = harness({ cwd: tempCwd(), branch: [...resumedBranch({ plan: "complete" }), assistant()] });
+  await settle(h);
+  assert.equal(h.sent.length, 1);
+  assert.deepEqual(h.sent[0].message.details, { piGauntletRecoveryEdge: "plan-implement" });
+});
+
+test("resumed session: closure gate blocks complete verify without a conformance dispatch (AC 3)", async () => {
+  const h = harness({
+    cwd: tempCwd(),
+    branch: resumedBranch({ plan: "complete", implement: "complete", verify: "in_progress" }),
+  });
+  await h.emit("session_start");
+  const tool = h.tools.find((t) => t.name === "phase_tracker")!;
+  const res = (await tool.execute("t1", { action: "complete", phase: "verify" }, undefined, undefined, h.ctx)) as {
+    details: { error?: string };
+  };
+  assert.equal(res.details.error, "no conformance-reviewer dispatch observed");
+});
+
+const subagentResult = (agents: string[]) => ({
+  type: "message",
+  message: {
+    role: "toolResult",
+    toolName: "subagent",
+    details: { results: agents.map((agent) => ({ agent, exitCode: 0 })) },
+  },
+});
+
+const implementBranch = (extra: unknown[] = []) => [
+  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" })),
+  ...extra,
+];
+
+const commitCall = (id: string) => ({
+  toolName: "bash",
+  toolCallId: id,
+  input: { command: "git commit -m 'integrate wave'" },
+});
+const commitResult = (id: string) => ({
+  toolName: "bash",
+  toolCallId: id,
+  isError: false,
+  content: [{ type: "text", text: "ok" }],
+});
+
+test("implement-phase commit with implementer newer than both reviewers warns", async () => {
+  const priorDepth = process.env.PI_SUBAGENT_DEPTH;
+  delete process.env.PI_SUBAGENT_DEPTH; // isolate from an ambient subagent depth in the test-runner's own process
+  try {
+    const h = harness({ branch: implementBranch([subagentResult(["implementer"])]) });
+    await h.emit("session_start");
+    await h.emitEvent("tool_call", commitCall("c1"));
+    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;
+  }
+});
+
+test("cadence guard silent in subagent children", async () => {
+  const priorDepth = process.env.PI_SUBAGENT_DEPTH;
+  process.env.PI_SUBAGENT_DEPTH = "1";
+  try {
+    const branch = implementBranch([subagentResult(["implementer"])]);
+    const h = harness({ branch });
+    await h.emit("session_start");
+    await h.emitEvent("tool_call", commitCall("c1"));
+    assert.equal((await h.emitEvent("tool_result", commitResult("c1")))[0], undefined);
+  } finally {
+    if (priorDepth === undefined) delete process.env.PI_SUBAGENT_DEPTH;
+    else process.env.PI_SUBAGENT_DEPTH = priorDepth;
+  }
+});
+
+test("fresh SR and CR after the implementer keep the commit silent", async () => {
+  const priorDepth = process.env.PI_SUBAGENT_DEPTH;
+  delete process.env.PI_SUBAGENT_DEPTH;
+  try {
+    const h = harness({
+      branch: implementBranch([
+        subagentResult(["implementer"]),
+        subagentResult(["spec-reviewer"]),
+        subagentResult(["code-reviewer"]),
+      ]),
+    });
+    await h.emit("session_start");
+    await h.emitEvent("tool_call", commitCall("c1"));
+    assert.equal((await h.emitEvent("tool_result", commitResult("c1")))[0], undefined);
+  } finally {
+    if (priorDepth !== undefined) process.env.PI_SUBAGENT_DEPTH = priorDepth;
+  }
+});
+
+test("AND-logic: fresh SR with stale CR stays silent (doc-only wave shape)", async () => {
+  const priorDepth = process.env.PI_SUBAGENT_DEPTH;
+  delete process.env.PI_SUBAGENT_DEPTH;
+  try {
+    const h = harness({
+      branch: implementBranch([subagentResult(["implementer"]), subagentResult(["spec-reviewer"])]),
+    });
+    await h.emit("session_start");
+    await h.emitEvent("tool_call", commitCall("c1"));
+    assert.equal((await h.emitEvent("tool_result", commitResult("c1")))[0], undefined);
+  } finally {
+    if (priorDepth !== undefined) process.env.PI_SUBAGENT_DEPTH = priorDepth;
+  }
+});
+
+test("fused implementer+reviewer results in one dispatch stay silent", async () => {
+  const priorDepth = process.env.PI_SUBAGENT_DEPTH;
+  delete process.env.PI_SUBAGENT_DEPTH;
+  try {
+    const h = harness({
+      branch: implementBranch([subagentResult(["implementer", "spec-reviewer", "code-reviewer"])]),
+    });
+    await h.emit("session_start");
+    await h.emitEvent("tool_call", commitCall("c1"));
+    assert.equal((await h.emitEvent("tool_result", commitResult("c1")))[0], undefined);
+  } finally {
+    if (priorDepth !== undefined) process.env.PI_SUBAGENT_DEPTH = priorDepth;
+  }
+});
+
+test("no implementer observed: commit stays silent", async () => {
+  const priorDepth = process.env.PI_SUBAGENT_DEPTH;
+  delete process.env.PI_SUBAGENT_DEPTH;
+  try {
+    const h = harness({ branch: implementBranch() });
+    await h.emit("session_start");
+    await h.emitEvent("tool_call", commitCall("c1"));
+    assert.equal((await h.emitEvent("tool_result", commitResult("c1")))[0], undefined);
+  } finally {
+    if (priorDepth !== undefined) process.env.PI_SUBAGENT_DEPTH = priorDepth;
+  }
+});
+
+test("guard silent outside implement and when flowGuards.enforce is false", async () => {
+  const priorDepth = process.env.PI_SUBAGENT_DEPTH;
+  delete process.env.PI_SUBAGENT_DEPTH;
+  try {
+    const planOnly = harness({
+      branch: [
+        phaseResult("start", phases({ brainstorm: "in_progress" })),
+        phaseResult("complete", phases({ brainstorm: "complete" })),
+        phaseResult("start", phases({ brainstorm: "complete", plan: "in_progress" })),
+        subagentResult(["implementer"]),
+      ],
+    });
+    await planOnly.emit("session_start");
+    await planOnly.emitEvent("tool_call", commitCall("c1"));
+    assert.equal((await planOnly.emitEvent("tool_result", commitResult("c1")))[0], undefined);
+
+    const off = harness({
+      cwd: tempCwd({ piGauntlet: { flowGuards: { enforce: false } } }),
+      branch: implementBranch([subagentResult(["implementer"])]),
+    });
+    await off.emit("session_start");
+    await off.emitEvent("tool_call", commitCall("c1"));
+    assert.equal((await off.emitEvent("tool_result", commitResult("c1")))[0], undefined);
+  } finally {
+    if (priorDepth !== undefined) process.env.PI_SUBAGENT_DEPTH = priorDepth;
+  }
+});
+
+test("live tool_result observation updates the ledger", async () => {
+  const priorDepth = process.env.PI_SUBAGENT_DEPTH;
+  delete process.env.PI_SUBAGENT_DEPTH;
+  try {
+    const h = harness({ branch: implementBranch([subagentResult(["implementer"])]) });
+    await h.emit("session_start");
+    await h.emitEvent("tool_result", {
+      toolName: "subagent",
+      toolCallId: "s1",
+      content: [],
+      details: { results: [{ agent: "spec-reviewer", exitCode: 0 }, { agent: "code-reviewer", exitCode: 0 }] },
+    });
+    await h.emitEvent("tool_call", commitCall("c1"));
+    assert.equal((await h.emitEvent("tool_result", commitResult("c1")))[0], undefined);
+  } finally {
+    if (priorDepth !== undefined) process.env.PI_SUBAGENT_DEPTH = priorDepth;
+  }
+});
+
+test("second implementer after reviews re-arms the warning", async () => {
+  const priorDepth = process.env.PI_SUBAGENT_DEPTH;
+  delete process.env.PI_SUBAGENT_DEPTH;
+  try {
+    const h = harness({
+      branch: implementBranch([
+        subagentResult(["implementer"]),
+        subagentResult(["spec-reviewer"]),
+        subagentResult(["code-reviewer"]),
+        subagentResult(["implementer"]),
+      ]),
+    });
+    await h.emit("session_start");
+    await h.emitEvent("tool_call", commitCall("c1"));
+    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;
+  }
+});

package/extensions/phase-tracker.ts

@@ -27,6 +27,8 @@ import {
   checkSubstep,
   findMarkerFile,
   flowGuardApplies,
+  implementExemptDirs,
+  implementWriteGuardApplies,
   markerBlockReason,
   nextGauntletEntered,
   parseGitCommit,
@@ -65,6 +67,30 @@ const qualifiesAsClosureDispatch = (details: unknown): boolean => {
   return d.results.some((r) => r?.agent === "conformance-reviewer" && r?.exitCode === 0);
 };
 
+// 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
+// number, so a fused implementer+reviewer result never reads as reviewer-stale.
+const CADENCE_AGENTS = ["implementer", "spec-reviewer", "code-reviewer"] as const;
+type CadenceAgent = (typeof CADENCE_AGENTS)[number];
+
+const completedCadenceAgents = (details: unknown): CadenceAgent[] => {
+  const d = details as { results?: { agent?: unknown; exitCode?: unknown }[] } | undefined;
+  if (!d || !Array.isArray(d.results)) return [];
+  const seen = new Set<CadenceAgent>();
+  for (const r of d.results) {
+    if (r?.exitCode === 0 && (CADENCE_AGENTS as readonly unknown[]).includes(r?.agent)) {
+      seen.add(r.agent as CadenceAgent);
+    }
+  }
+  return [...seen];
+};
+
+const REVIEW_CADENCE_WARNING =
+  "⚠️ Reminder: no spec-reviewer or code-reviewer observed since the last implementer.\n" +
+  "SR is required per task; CR per wave for code waves (doc-only waves are SR-only).\n" +
+  "Dispatch the missing review(s) before committing integrated work.";
+
 const CLOSURE_GATE_ERROR =
   "Error: cannot complete 'verify': no conformance-reviewer dispatch observed.\n" +
   "The closing loop is required before verify completes. Either:\n" +
@@ -169,6 +195,12 @@ const brainstormWriteWarning = (specDirs: string[]): string =>
   `Brainstorming may only edit the spec under ${specDirs.join(", ")}. Implementation\n` +
   "waits for the spec approval gate. If this edit IS the spec, place it under the spec dir.";
 
+const implementWriteWarning = (): string =>
+  "⚠️ Parent write during the implement phase.\n" +
+  "During implement the main loop orchestrates; subagents write the code - dispatch\n" +
+  "this via /skill:subagent-driven-development instead of editing directly.\n" +
+  "If this edit is merge-conflict resolution between parallel waves, proceed.";
+
 // Contiguous-subsequence match of a configured spec dir against path components.
 const pathInSpecDirs = (rawPath: string, specDirs: string[]): boolean => {
   const comps = rawPath.split("/").filter((c) => c.length > 0 && c !== ".");
@@ -258,6 +290,19 @@ export default function (pi: ExtensionAPI) {
   let gauntletEntered = false;
   const attemptedRecoveryEdges = new Set<RecoveryEdge>();
 
+  let cadenceSeq = 0;
+  const cadenceLastSeen: Record<CadenceAgent, number> = {
+    implementer: 0,
+    "spec-reviewer": 0,
+    "code-reviewer": 0,
+  };
+  const observeCadence = (details: unknown) => {
+    const agents = completedCadenceAgents(details);
+    if (agents.length === 0) return;
+    cadenceSeq++;
+    for (const a of agents) cadenceLastSeen[a] = cadenceSeq;
+  };
+
   // Warn-once-per-phase ledger; cleared on every phase transition and on reconstruct.
   const firedGuards = new Map<string, boolean>();
   // Warnings stashed at tool_call, prepended at tool_result (verify-before-ship pattern).
@@ -272,6 +317,11 @@ export default function (pi: ExtensionAPI) {
   // (Inside a submodule the comparison is git-version-dependent and irrelevant here -
   // gauntlet flows do not run inside submodule git internals; whichever way it
   // resolves, the guard merely staying off in that edge case is harmless.)
+  // pi-cohort sets PI_SUBAGENT_DEPTH >= 1 in every spawned child (getSubagentDepthEnv).
+  // Implementer forks replay the parent's phase state; without this gate every
+  // implementer's first write would trip a spurious advisory.
+  const isSubagentChild = Number(process.env.PI_SUBAGENT_DEPTH ?? "0") > 0;
+
   const inPrimaryCheckout = (() => {
     try {
       const lines = execSync("git rev-parse --git-dir --git-common-dir", {
@@ -316,6 +366,10 @@ export default function (pi: ExtensionAPI) {
     attemptedRecoveryEdges.clear();
     firedGuards.clear();
     pendingGuardWarnings.clear();
+    cadenceSeq = 0;
+    cadenceLastSeen.implementer = 0;
+    cadenceLastSeen["spec-reviewer"] = 0;
+    cadenceLastSeen["code-reviewer"] = 0;
     for (const entry of ctx.sessionManager.getBranch()) {
       if (entry.type === "custom_message") {
         if (entry.customType === RECOVERY_CUSTOM_TYPE) {
@@ -336,6 +390,7 @@ export default function (pi: ExtensionAPI) {
         }
       } else if (msg.toolName === "subagent") {
         if (qualifiesAsClosureDispatch(msg.details)) conformanceDispatched = true;
+        observeCadence(msg.details);
       } else if (msg.toolName === "plan_tracker") {
         const details = msg.details as { tasks?: { status: string }[]; error?: string } | undefined;
         if (details && !details.error) applyPlanActivity(details.tasks);
@@ -429,7 +484,9 @@ export default function (pi: ExtensionAPI) {
     // 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") && flowGuardApplies(brainstormActive, gauntletEntered);
+      (event.toolName === "write" || event.toolName === "edit") &&
+      (flowGuardApplies(brainstormActive, gauntletEntered) ||
+        implementWriteGuardApplies(phases.plan.status, phases.implement.status, gauntletEntered, isSubagentChild));
     const guardableBash =
       event.toolName === "bash" && flowGuardApplies(activeGuardPhase() !== undefined, gauntletEntered);
     if (!guardableWrite && !guardableBash) return undefined;
@@ -437,12 +494,21 @@ export default function (pi: ExtensionAPI) {
     if (!flowGuardsEnforced()) return undefined;
 
     // Guard 3 — write/edit outside the spec dir during brainstorm.
+    // Guard 4 — parent write/edit in the armed implement window (spec
+    // 2026-08-07-resume-spec-in-hand): advisory, warn-once, plans dir also exempt.
     if (event.toolName === "write" || event.toolName === "edit") {
-      if (phases.brainstorm.status !== "in_progress" || firedGuards.get("brainstorm-write")) return undefined;
       const p = (event.input as { path?: unknown } | undefined)?.path;
-      if (typeof p !== "string" || pathInSpecDirs(p, specDirs())) return undefined;
-      firedGuards.set("brainstorm-write", true);
-      addGuardWarning(event.toolCallId, brainstormWriteWarning(specDirs()));
+      if (phases.brainstorm.status === "in_progress") {
+        if (firedGuards.get("brainstorm-write")) return undefined;
+        if (typeof p !== "string" || pathInSpecDirs(p, specDirs())) return undefined;
+        firedGuards.set("brainstorm-write", true);
+        addGuardWarning(event.toolCallId, brainstormWriteWarning(specDirs()));
+        return undefined;
+      }
+      if (firedGuards.get("implement-write")) return undefined;
+      if (typeof p !== "string" || pathInSpecDirs(p, implementExemptDirs(specDirs()))) return undefined;
+      firedGuards.set("implement-write", true);
+      addGuardWarning(event.toolCallId, implementWriteWarning());
       return undefined;
     }
 
@@ -498,6 +564,20 @@ export default function (pi: ExtensionAPI) {
       }
     }
 
+    // Guard 5 — review-cadence reminder (presence-only, advisory). Parent-session
+    // commits during implement only; child sessions (PI_SUBAGENT_DEPTH >= 1) are
+    // the implementers' own task commits and are exempt by design.
+    if (
+      !isSubagentChild &&
+      phases.implement.status === "in_progress" &&
+      parseGitCommit(command) &&
+      cadenceLastSeen.implementer > 0 &&
+      cadenceLastSeen.implementer > cadenceLastSeen["spec-reviewer"] &&
+      cadenceLastSeen.implementer > cadenceLastSeen["code-reviewer"]
+    ) {
+      warnings.push(REVIEW_CADENCE_WARNING);
+    }
+
     // Guard 3 — bash mutation outside the spec dir during brainstorm.
     if (phases.brainstorm.status === "in_progress" && !firedGuards.get("brainstorm-write")) {
       // Redirect target is cleanly extractable: judge it directly against the spec dirs,
@@ -524,6 +604,7 @@ export default function (pi: ExtensionAPI) {
   pi.on("tool_result", async (event) => {
     if (event.toolName === "subagent") {
       if (qualifiesAsClosureDispatch(event.details)) conformanceDispatched = true;
+      observeCadence(event.details);
       const warning = pendingGuardWarnings.get(event.toolCallId);
       if (warning) {
         pendingGuardWarnings.delete(event.toolCallId);

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

@@ -1,10 +1,17 @@
 const sources = {
   "@earendil-works/pi-ai": `export const StringEnum = (values, options = {}) => ({ values, ...options });`,
+  // Reads only the repo (project) settings layer - guard tests exercise repo-local
+  // settings via tempCwd()'s .pi/settings.json; there is no preset layer to stub.
   "@earendil-works/pi-coding-agent": `
+    import { readFileSync } from "node:fs";
     export class SettingsManager {
-      static create() { return new SettingsManager(); }
+      static create(cwd) { return new SettingsManager(cwd); }
+      constructor(cwd) { this.cwd = cwd; }
       getGlobalSettings() { return {}; }
-      getProjectSettings() { return {}; }
+      getProjectSettings() {
+        try { return JSON.parse(readFileSync(this.cwd + "/.pi/settings.json", "utf8")); }
+        catch { return {}; }
+      }
       drainErrors() { return []; }
     }
     export const getAgentDir = () => "/tmp/pi-gauntlet-test-agent";

package/extensions/verify-before-ship.test.ts

@@ -0,0 +1,92 @@
+import assert from "node:assert/strict";
+import { after, test } from "node:test";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import registerVerifyBeforeShip from "./verify-before-ship.ts";
+
+const tempDirs: string[] = [];
+after(() => {
+  for (const dir of tempDirs) rmSync(dir, { recursive: true, force: true });
+});
+
+function harness() {
+  const handlers = new Map<string, ((event: unknown, ctx: unknown) => unknown)[]>();
+  const dir = mkdtempSync(join(tmpdir(), "verify-before-ship-test-"));
+  tempDirs.push(dir);
+  const ctx = { cwd: dir };
+  const pi = {
+    on(event: string, handler: (event: unknown, context: unknown) => unknown) {
+      const registered = handlers.get(event) ?? [];
+      registered.push(handler);
+      handlers.set(event, registered);
+    },
+  };
+  registerVerifyBeforeShip(pi as any);
+  const emitEvent = async (name: string, event: unknown) => {
+    const results: unknown[] = [];
+    for (const handler of handlers.get(name) ?? []) results.push(await handler(event, ctx));
+    return results;
+  };
+  return { emitEvent };
+}
+
+const bashCall = (id: string, command: string) => ({ toolName: "bash", toolCallId: id, input: { command } });
+const bashResult = (id: string, isError = false) => ({
+  toolName: "bash",
+  toolCallId: id,
+  isError,
+  content: [{ type: "text", text: "ok" }],
+});
+const writeCall = (id: string, path: string) => ({ toolName: "write", toolCallId: id, input: { path } });
+
+const editSource = async (h: ReturnType<typeof harness>) => {
+  await h.emitEvent("tool_call", writeCall("w1", "src/x.ts"));
+};
+
+const warningOf = (results: unknown[]): string | undefined => {
+  const r = results[0] as { content?: { text?: string }[] } | undefined;
+  return r?.content?.[0]?.text;
+};
+
+test("git commit is not watched: no warning even when unverified", async () => {
+  const h = harness();
+  await editSource(h);
+  await h.emitEvent("tool_call", bashCall("c1", "git commit -m 'wave 1'"));
+  assert.equal((await h.emitEvent("tool_result", bashResult("c1")))[0], undefined);
+});
+
+test("git push warns when unverified", async () => {
+  const h = harness();
+  await editSource(h);
+  await h.emitEvent("tool_call", bashCall("p1", "git push origin main"));
+  const warning = warningOf(await h.emitEvent("tool_result", bashResult("p1")));
+  assert.match(warning ?? "", /ran without verification/);
+});
+
+test("gh pr create warns when unverified", async () => {
+  const h = harness();
+  await editSource(h);
+  await h.emitEvent("tool_call", bashCall("pr1", "gh pr create --fill"));
+  const warning = warningOf(await h.emitEvent("tool_result", bashResult("pr1")));
+  assert.match(warning ?? "", /ran without verification/);
+});
+
+test("a passing recognised run clears the warning for push", async () => {
+  const h = harness();
+  await editSource(h);
+  await h.emitEvent("tool_call", bashCall("t1", "npm test"));
+  await h.emitEvent("tool_result", bashResult("t1"));
+  await h.emitEvent("tool_call", bashCall("p1", "git push"));
+  assert.equal((await h.emitEvent("tool_result", bashResult("p1")))[0], undefined);
+});
+
+test("a failing recognised run does not clear", async () => {
+  const h = harness();
+  await editSource(h);
+  await h.emitEvent("tool_call", bashCall("t1", "npm test"));
+  await h.emitEvent("tool_result", bashResult("t1", true));
+  await h.emitEvent("tool_call", bashCall("p1", "git push"));
+  const warning = warningOf(await h.emitEvent("tool_result", bashResult("p1")));
+  assert.match(warning ?? "", /ran without verification/);
+});

package/extensions/verify-before-ship.ts

@@ -1,8 +1,9 @@
 /**
  * Verify-before-ship extension
  *
- * Single-session verification gate for shipping commands (git commit / git push /
- * gh pr create). Tracks whether a recognised verification command has succeeded
+ * Single-session verification gate for shipping commands (git push / gh pr create).
+ * Local commits are not ship events; commit-time review-cadence advisories live in
+ * phase-tracker. Tracks whether a recognised verification command has succeeded
  * since the last source-file write; injects an advisory warning into the tool
  * result of any ship command when verification is stale.
  *
@@ -39,7 +40,7 @@ const DEFAULT_TEST_COMMANDS = [
   "go\\s+test",
 ];
 
-const SHIP_CMD = /\b(git\s+commit|git\s+push|gh\s+pr\s+create)\b/;
+const SHIP_CMD = /\b(git\s+push|gh\s+pr\s+create)\b/;
 
 const SOURCE_EXT = /\.(ts|tsx|js|jsx|py|rb|go|rs|java|swift|kt)$/;
 const TEST_PATH = /(^|\/)(tests?|__tests__)\/|\.(test|spec)\.|_test\.(py|go|rb)$/;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-gauntlet",
-  "version": "4.6.2",
+  "version": "4.8.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

@@ -57,7 +57,7 @@ For each task in `plan_tracker`:
 2. **Handle implementer status** (see below).
 3. **Dispatch spec reviewer.** Verify the diff matches the spec — nothing missing, nothing extra.
 4. If spec reviewer finds gaps → re-dispatch implementer to fix → re-review. Loop until ✅.
-5. **Dispatch code-quality reviewer.** Only after spec is ✅.
+5. **Dispatch code-quality reviewer.** Only after spec is ✅. Skip for doc-only tasks (every file in the task's `Files:` block documentation-only) — SR-only, same exemption as doc-only waves.
 6. If quality reviewer finds issues → re-dispatch implementer → re-review. Loop until ✅.
 7. Mark task complete in `plan_tracker`.
 
@@ -142,13 +142,13 @@ Auto-selected at handoff by `writing-plans` (any wave with ≥2 tasks) when the
 
 1. **Independence check.** Parse the wave's tasks' `Files:` blocks; assert pairwise-disjoint (mechanical). Runtime-resource disjointness (DB/schema, port, fixture, external service, shared temp path) is not machine-checkable here — trust the plan's wave grouping, which `writing-plans`' D5 contract guarantees. Either kind of overlap → the wave is mis-grouped; run those tasks as sequential single-task waves and note it.
 2. **Fan out.** One parallel dispatch (shape below): `implementer` per task, `context: "fresh"`, `worktree: true`. Each returns a status + a patch.
-3. **Status + spec review per task.** Parse each `DONE`/`BLOCKED`/etc. (see [Implementer Status](#implementer-status)) **first**. Then **dispatch a `spec-reviewer` per accepted patch** (`DONE`, or a `DONE_WITH_CONCERNS` you proceeded with) in one parallel fan-out — `context: "fresh"`, `cwd: <this worktree>`, **no `worktree` flag** (read-only) — each passed its task text, the returned **patch diff**, and the absolute spec path. Review is **diff-based**: the diff's hunks carry `file:line`, and test execution is not the reviewer's job here (the wave test gate in step 5 runs the suite). Inline verdicts are fine at normal wave sizes; large waves use `output:` + `outputMode: "file-only"` to keep verdicts out of your context. **Re-dispatch by cause:** `BLOCKED`/`NEEDS_CONTEXT` per the [Implementer Status](#implementer-status) matrix; a **spec gap** re-dispatches the implementer (fresh, `worktree: true`) carrying the prior patch + the reviewer's findings, the new patch superseding the old at step 4. Loop until accepted + spec ✅.
+3. **Status + spec review per task.** Parse each `DONE`/`BLOCKED`/etc. (see [Implementer Status](#implementer-status)) **first**. Then **dispatch a `spec-reviewer` per accepted patch** (`DONE`, or a `DONE_WITH_CONCERNS` you proceeded with) in one parallel fan-out — `context: "fresh"`, `cwd: <this worktree>`, **no `worktree` flag** (read-only) — each passed its task text, the returned **patch diff**, and the absolute spec path. Review is **diff-based**: the diff's hunks carry `file:line`, and test execution is not the reviewer's job here (the wave test gate in step 5 runs the wave's declared test commands). Inline verdicts are fine at normal wave sizes; large waves use `output:` + `outputMode: "file-only"` to keep verdicts out of your context. **Re-dispatch by cause:** `BLOCKED`/`NEEDS_CONTEXT` per the [Implementer Status](#implementer-status) matrix; a **spec gap** re-dispatches the implementer (fresh, `worktree: true`) carrying the prior patch + the reviewer's findings, the new patch superseding the old at step 4. Loop until accepted + spec ✅.
 4. **Integrate.** `git apply` each task's patch sequentially onto HEAD. Apply fails = textual conflict → drop that task, finish the rest, re-run the dropped task sequentially on the updated HEAD.
-5. **Test gate.** Run the suite on the integrated tree. Failure = semantic conflict or bug → re-run the offending task sequentially, else fix per [When a Subagent Fails](#when-a-subagent-fails).
-6. **Quality review.** Code-quality review on the integrated wave diff; loop fixes to ✅.
+5. **Test gate.** Run the union of the wave's tasks' declared test commands on the integrated tree — the full verification set is the verify phase's job, run once. Failure = semantic conflict or bug → re-run the offending task sequentially, else fix per [When a Subagent Fails](#when-a-subagent-fails).
+6. **Quality review.** Code-quality review on the integrated wave diff; loop fixes to ✅. Skip for doc-only waves (SR-only per the commit precondition below).
 7. **Commit the wave.** Leaves a clean tree; the next wave's children branch from this commit and so see the integrated work.
 
-**Two-stage review is preserved:** spec review per task (pre-integration, dispatched `spec-reviewer` — not inline), quality review per wave (post-integration). Both gates required before the wave commits.
+**Two-stage review is preserved:** spec review per task (pre-integration, dispatched `spec-reviewer` — not inline), quality review per wave (post-integration). A wave commit requires one spec-review verdict per accepted task, plus one code-review verdict on the integrated diff for waves that touch code. A doc-only wave (every task's `Files:` block documentation-only, per `writing-plans`' Wave Grouping) is SR-only — the CR gate does not apply.
 
 **Dependent context across waves:** wave N+1 tasks branch from a HEAD containing wave N, so they see the code; still forward wave N's task summaries into wave N+1 prompts.
 
@@ -191,9 +191,10 @@ For the fan-out + worktree + patch-integration + conflict mechanics, see `dispat
 
 0. Call `phase_tracker({ action: "start", phase: "verify" })`. (The `implement` phase was started at execution start and auto-completes from `plan_tracker` once all tasks are done; this flow runs its own verify gate instead of `/skill:verification-before-completion`, so it must mark verify itself.)
 1. **Run the whole-diff code review.** Dispatch `/skill:requesting-code-review` against the worktree's full diff vs `main` (already covered in [The Process](#the-process) step "After all tasks"). Address Critical and Moderate findings before handoff. (Consumers wanting an in-flow project-specific audit re-add it as an explicit step in `.pi/gauntlet-overrides.md`, or run `/self-audit` manually.)
-2. **Close the loop — conformance check.** The review in step 1 is plan-vs-code (single-step); it inherits any requirement the plan already dropped. Before marking verify complete, dispatch a fresh-context **`conformance-reviewer`** — its **own** dispatch, never fused into the step-1 review — to confront the deliverable (code **and** docs) against the *origin* — the spec **and** the original prompt — per `verification-before-completion/reference/conformance-check.md`. Pass the spec path, the verbatim original prompt, and the full diff. Follow that reference for the partition rule, concern decomposition, and fix-loop mechanics; do not reimplement them here. The fix loop may drive `plan_tracker` to surface fix-wave progress (task name = `Gn: <short desc>`, lifecycle `pending → in_progress → complete` per gap); it never calls `phase_tracker`. Call `phase_tracker({ action: "complete", phase: "verify" })` only when the reference says the handoff is durably complete: either a current `CONFORMS` result, or a current `## Closure / conformance` inventory whose carried-open concerns all come from valid deferred gaps, including `recommended: fix` gaps carried open because a declared precondition made the fix loop unavailable (`maxFixRounds: 0`, or no eligible named-branch worktree). A started positive-cap fix loop that blocks, fails, or exhausts its rounds with an open `fix` gap is escalation, not completion; on escalation, do not complete verify, stop and report.
-3. Summarize what was implemented (tasks completed, files changed, test counts, code-review verdict). Emit the `## Closure / conformance` block exactly as defined in `verification-before-completion/reference/conformance-check.md`: it must open with the two-line sentinel (`status: CONFORMS (0 open)` or `status: GAPS (N open)`, then `audited-base: <full HEAD SHA>`), then carry the exact durable concern schema by reference with no renamed or reformatted fields. `finishing-a-development-branch` Step 3.5 consumes that block verbatim.
-4. **Proceed to finishing — no confirmation prompt.** Once verify is complete per step 2's criterion, invoke `/skill:finishing-a-development-branch` immediately. Its Step 4 menu (squash / PR / keep / discard) is the human gate; a separate "ready to finish?" prompt only stacks a second stop in front of it. Carried-open concerns are resolved there per concern via the `## Closure / conformance` block from step 3. Manual testing is a follow-up after the finishing choice (on `<base-branch>` after a squash-merge, or on the PR branch), never a reason to hold this gate.
+2. **Run the full verification set — once.** Read the plan header's `**Verification:**` line and run it: tests + style + format (a single bundling entrypoint, or the listed individual commands). Green output is the fresh evidence verify requires; this is the only full run before conformance — task and wave gates ran scoped commands only. After conformance fix rounds land, re-run the set before re-dispatching the gate.
+3. **Close the loop — conformance check.** The review in step 1 is plan-vs-code (single-step); it inherits any requirement the plan already dropped. Before marking verify complete, dispatch a fresh-context **`conformance-reviewer`** — its **own** dispatch, never fused into the step-1 review — to confront the deliverable (code **and** docs) against the *origin* — the spec **and** the original prompt — per `verification-before-completion/reference/conformance-check.md`. Pass the spec path, the verbatim original prompt, and the full diff. Follow that reference for the partition rule, concern decomposition, and fix-loop mechanics; do not reimplement them here. The fix loop may drive `plan_tracker` to surface fix-wave progress (task name = `Gn: <short desc>`, lifecycle `pending → in_progress → complete` per gap); it never calls `phase_tracker`. Call `phase_tracker({ action: "complete", phase: "verify" })` only when the reference says the handoff is durably complete: either a current `CONFORMS` result, or a current `## Closure / conformance` inventory whose carried-open concerns all come from valid deferred gaps, including `recommended: fix` gaps carried open because a declared precondition made the fix loop unavailable (`maxFixRounds: 0`, or no eligible named-branch worktree). A started positive-cap fix loop that blocks, fails, or exhausts its rounds with an open `fix` gap is escalation, not completion; on escalation, do not complete verify, stop and report.
+4. Summarize what was implemented (tasks completed, files changed, test counts, code-review verdict). Emit the `## Closure / conformance` block exactly as defined in `verification-before-completion/reference/conformance-check.md`: it must open with the two-line sentinel (`status: CONFORMS (0 open)` or `status: GAPS (N open)`, then `audited-base: <full HEAD SHA>`), then carry the exact durable concern schema by reference with no renamed or reformatted fields. `finishing-a-development-branch` Step 3.5 consumes that block verbatim.
+5. **Proceed to finishing — no confirmation prompt.** Once verify is complete per step 3's criterion, invoke `/skill:finishing-a-development-branch` immediately. Its Step 4 menu (squash / PR / keep / discard) is the human gate; a separate "ready to finish?" prompt only stacks a second stop in front of it. Carried-open concerns are resolved there per concern via the `## Closure / conformance` block from step 4. Manual testing is a follow-up after the finishing choice (on `<base-branch>` after a squash-merge, or on the PR branch), never a reason to hold this gate.
 
 ## Red Flags — STOP
 
@@ -208,6 +209,8 @@ For the fan-out + worktree + patch-integration + conflict mechanics, see `dispat
 - Pausing to "check in" between tasks (continuous execution rule)
 - Skipping the `Implementer Status` parse — treating every response as DONE
 - Starting on main without explicit user consent
+- Dispatching `code-reviewer` before every one of the wave's spec-review verdicts has landed (including fusing SR+CR into one parallel call)
+- About to run the full verification entrypoint during the implement phase — task and wave gates run scoped, plan-declared commands only; the full set belongs to verify
 
 ## Integration
 

package/skills/verification-before-completion/SKILL.md

@@ -36,7 +36,7 @@ If you haven't run the verification command in this message, you cannot claim it
 BEFORE claiming any status or expressing satisfaction:
 
 1. IDENTIFY: What command proves this claim?
-2. RUN: Execute the FULL command (fresh, complete)
+2. RUN: Execute the full command for the claim from step 1 (fresh, complete, unabridged)
 3. READ: Full output, check exit code, count failures
 4. VERIFY: Does output confirm the claim?
    - If NO: State actual status with evidence
@@ -46,6 +46,8 @@ BEFORE claiming any status or expressing satisfaction:
 Skip any step = lying, not verifying
 ```
 
+Evidence is proportionate to the claim: a task or wave claim is proven by the commands the plan declares for it — a scoped run is **complete** evidence for a scoped claim. Phase-completion and ship claims require the project's full verification entrypoint (tests + style + format), run once at verify before the conformance gate.
+
 ## Common Failures
 
 | Claim | Requires | Not Sufficient |
@@ -69,7 +71,7 @@ Skip any step = lying, not verifying
 | "Linter passed" | Linter ≠ compiler |
 | "Agent said success" | Verify independently |
 | "I'm tired" | Exhaustion ≠ excuse |
-| "Partial check is enough" | Partial proves nothing |
+| "Partial check is enough" | Partial = less than the claim requires; scoped-for-scoped is complete |
 | "Different words so rule doesn't apply" | Spirit over letter |
 
 ## Red Flags - STOP
@@ -152,7 +154,7 @@ From recurring failure modes:
 
 ## Enforcement
 
-The `verify-before-ship` extension shipped by pi-gauntlet watches `git commit`, `git push`, and `gh pr create`. If you have not run a passing recognised verification command since your last source-file edit in this session, an advisory warning is injected into the tool result. The warning clears automatically after a fresh passing run.
+The `verify-before-ship` extension shipped by pi-gauntlet watches `git push` and `gh pr create`. If you have not run a passing recognised verification command since your last source-file edit in this session, an advisory warning is injected into the tool result. The warning clears automatically after a fresh passing run.
 
 Defaults recognise `make ci`, `make test`, `npm test`, `pnpm test`, `yarn test`, `pytest`, `rspec`, `cargo test`, `go test`. Projects can override (or narrow) the list via `settings.json#piGauntlet.verifyBeforeShip.testCommands`.
 

package/skills/writing-plans/SKILL.md

@@ -3,7 +3,7 @@ name: writing-plans
 description: Use when you have a spec or requirements for a multi-step task, before touching code
 ---
 
-> **Related skills:** Reached via the auto-chain from `/skill:brainstorming` (not a direct human entry point). On completion this skill auto-invokes `/skill:subagent-driven-development`.
+> **Related skills:** Reached via the auto-chain from `/skill:brainstorming`, or via the spec-in-hand handoff path (see "Resuming with a spec in hand" below) — otherwise not a direct human entry point. On completion this skill auto-invokes `/skill:subagent-driven-development`.
 
 # Writing Plans
 
@@ -15,9 +15,9 @@ DRY. YAGNI. TDD. Frequent commits.
 
 **Announce at start:** "I'm using the writing-plans skill to create the implementation plan."
 
-Before drafting the plan, call `phase_tracker({ action: "start", phase: "plan" })`.
+Before drafting the plan, call `phase_tracker({ action: "start", phase: "plan" })` (if resuming with a spec in hand, see "Resuming with a spec in hand" below first -- its arming sequence already performs this call).
 
-**Input:** an approved spec in `<project>/doc/specs/<filename>.md` (produced by `/skill:brainstorming`).
+**Input:** an approved spec in `<project>/doc/specs/<filename>.md` — produced by `/skill:brainstorming` in this session, or handed off from another session (see "Resuming with a spec in hand").
 
 **Save plans to:** the sibling `doc/plans/` directory next to the spec. The plan filename matches the spec filename exactly — same date, same Linear ID (if any), same topic slug, no `-design` suffix.
 
@@ -29,6 +29,36 @@ Before drafting the plan, call `phase_tracker({ action: "start", phase: "plan" }
 
 If no spec exists, send the work back to `/skill:brainstorming`. Do not invent a plan without a spec.
 
+## Resuming with a spec in hand
+
+A handoff path, not a shortcut: use it when an **approved spec arrives from another session** (a handoff doc, a fresh top-level session resuming ratified work). New work still enters via `/skill:brainstorming`. The trigger is **phase-tracker state, not handoff prose** — it works even when the handoff doc says nothing about arming. On invocation, check `phase_tracker({ action: "status" })` and branch on the brainstorm phase:
+
+| brainstorm status | meaning | action |
+|---|---|---|
+| `in_progress` or `complete` | auto-chain from brainstorming | normal flow below, unchanged |
+| `pending`, no other phase `in_progress` | fresh resume | arm, then plan (this section) |
+| `skipped` | already resumed in this session | do **not** re-run the sequence (`start` errors on a skipped phase without `force`); verify plan state and continue |
+| `pending`, another phase `in_progress` | not a fresh resume (`start brainstorm` would error) | stop and ask the user; do not arm |
+
+On a fresh resume:
+
+1. **Verify the spec exists** at the given path. Missing → stop and ask; never arm on a missing spec.
+2. **Confirm approval.** Any unambiguous assertion in the prompt, handoff doc, or user message ("Brainstorming is complete", "spec approved" — examples, not an allowlist) counts. No assertion → ask once; on "no", route to `/skill:brainstorming`.
+3. **Worktree.** If not already in an isolated worktree, set one up per `/skill:using-git-worktrees` and commit the spec there (the spec must live in the worktree, same as the brainstorm path).
+4. **Arm the flow** — run exactly:
+
+   ```
+   phase_tracker({ action: "start", phase: "brainstorm" })
+   phase_tracker({ action: "skip", phase: "brainstorm", reason: "resume: approved spec at <path>" })
+   phase_tracker({ action: "start", phase: "plan" })
+   ```
+
+   This is the existing arming mechanism, not new mechanics: the `start` arms `gauntletEntered`, `skip` preserves it, session replay reconstructs it, `reset` disarms. The sequence already performed this skill's own `start plan` call — **do not** issue a second one (a repeat `start` on the in_progress phase is a no-op reset that re-clears the warn-once guard ledger).
+
+Then continue with the normal flow below (Scope Check onward, including Recon).
+
+**Writing a handoff doc** (from the producing session): name `/skill:writing-plans` as the entry point — never a phase past planning, since this gesture only arms through `start plan` — give the spec's path, and assert its approval status.
+
 ## Boundaries
 
 - Read code and docs: yes
@@ -50,6 +80,26 @@ If yes, decompose into separate plans and call it out:
 
 A single plan should land in one PR worth of work. Multi-PR sequences get separate plans.
 
+## Recon (mandatory)
+
+Before mapping files, dispatch a scout to build the implementation map. Foreground, no announcement, no user interaction. The task template below is fixed — fill exactly **one** variable, the absolute spec path; compose nothing else:
+
+```
+subagent({ agent: "scout", context: "fresh", cwd: "<abs worktree path>",
+  phase: "plan-recon", output: "<abs plan path — same filename as the spec, per the table above>",
+  task: <the fixed template below, with the spec path filled> })
+```
+
+> Recon for implementation planning. Read the approved spec at `<abs spec path>` - it is the single source of truth for what is being built. Also read the repo's `AGENTS.md` and, if present, `.pi/gauntlet-overrides.md` for conventions. Build an implementation map for the spec: exact file paths to create/modify/delete; existing call sites and tests with line ranges; conventions and patterns the plan must match; the project's test runner and the exact scoped-invocation form for running individual test files (derived from the repo's Makefile/bin/config and the overrides file); the style/lint and auto-format commands in both scoped per-file form and repo-wide form (same sources); separately, the full-suite verification entrypoint and whether it bundles style/format checks. Flag any spec claim that contradicts the code. Read-only recon: do not edit any file except writing your report to your output path. Start your report with the line `# CONTEXT DRAFT - NOT A PLAN - fully replaced at plan-writing` verbatim. End with an "Open questions that matter for the plan" section. Compact handoff, not a dump.
+
+Consumption:
+
+- `Read` the draft at the plan path before mapping files — the on-disk copy is canonical (prune-proof, restart-proof).
+- The draft is a helper, not a fence: verify load-bearing claims against real code before planning against them.
+- Plan-writing is a **full-replacement `write`** at the same path. Re-read the draft in the same turn immediately before the overwrite. After the write, confirm line 1 is no longer the draft marker before self-review and handoff.
+- **Degradation:** the scout failed when its task errored or the output file is missing or empty. Proceed from your own reads with a one-line note; never block. If the file is absent, no marker check applies at the overwrite.
+- **Re-entry:** re-dispatching recon overwrites whatever the plan path holds — including a committed prior plan (recoverable from git history) or an uncommitted one (destroyed). Re-planning is a deliberate overwrite.
+
 ## File Structure
 
 **Before drafting tasks, map the files.**
@@ -83,6 +133,8 @@ Group tasks into **waves** so the executor can parallelize independent work (see
 
 **File-ownership contract.** The per-task `**Files:**` block *is* the ownership declaration — no new syntax. Rule: **within a wave, the union of every task's declared paths must be pairwise disjoint.** Globs are allowed for `Modify` when exact paths are unknown, but must not overlap another same-wave task's paths. A task that must touch another's file belongs in a later wave.
 
+**Test-command contract.** Every code-touching wave declares at least one scoped test command across its tasks' steps. A wave with zero test commands is legal only when every task's `Files:` block is documentation-only (the trailing doc-only wave below).
+
 **Runtime-resource disjointness.** File-disjoint is necessary but not sufficient: two tasks with disjoint files that both mutate the same DB, bind the same port, or share a fixture are **not** parallel-safe and must land in different waves. The executor auto-selects parallel for *every* multi-task wave, so this grouping is the sole parallel-safety guarantee — there is no selection-time judgment downstream. No new mandatory per-task syntax; when a shared runtime resource is the reason two file-disjoint tasks sit in different waves, record it in an inline note on the later wave.
 
 **Doc tasks.** Doc updates are real plan tasks, not an afterthought. Task-local docs (a doc that only describes the file(s) a task already touches) ride with that task. Cross-cutting or index docs (README, `AGENTS.md`, topic guides, taxonomy indexes) sequence into a dedicated trailing doc-only wave — last wave by convention, file-disjoint from every code task so the pairwise-disjoint wave contract holds.
@@ -113,6 +165,7 @@ Each step is **one action, 2-5 minutes**:
 - "Run it, confirm it fails" — step
 - "Implement minimal code to pass" — step
 - "Run tests, confirm green" — step
+- "Format & lint the task's files" — step
 - "Commit" — step
 
 ## Plan Document Header
@@ -130,11 +183,15 @@ Each step is **one action, 2-5 minutes**:
 
 **Spec:** `<project>/doc/specs/<same-filename-as-this-plan>.md`
 
+**Verification:** `<full verification command set — tests + style + format; a single bundling entrypoint, or the listed individual commands; from the recon report / project overrides>`
+
 **Linear:** `E-XXXX` (omit if no ticket)
 
 ---
 ```
 
+The `**Verification:**` line is the **only** place the full verification entrypoint may appear — never in any task or wave step. The verify phase reads it from the plan instead of re-deriving it; execution runs scoped commands only.
+
 ## Task Structure
 
 Each task uses `- [ ]` checkbox steps so execution tools (and humans) can track progress.
@@ -174,7 +231,12 @@ Each task uses `- [ ]` checkbox steps so execution tools (and humans) can track
   Run: `uv run pytest tests/path/test.py::test_name -v`
   Expected: PASS
 
-- [ ] **Step 5: Commit**
+- [ ] **Step 5: Format & lint the task's files**
+
+  Run: `<scoped fmt/lint command from recon> exact/path/to/file.py tests/exact/path/to/test.py`
+  Expected: no diff after re-run / 0 offenses
+
+- [ ] **Step 6: Commit**
 
   ```bash
   git add tests/path/test.py src/path/file.py
@@ -182,6 +244,8 @@ Each task uses `- [ ]` checkbox steps so execution tools (and humans) can track
   ```
 ```
 
+Every code task carries this step (red -> green -> fmt/lint -> commit). Doc-only tasks omit it unless the project formats Markdown.
+
 ## No Placeholders
 
 Every plan failure mode:
@@ -205,6 +269,8 @@ After drafting the plan and before announcing it complete, run three checks your
 - **Placeholder scan.** Grep the doc for `TODO`, `TBD`, `xxx`, `[fill in]`, `<example>`, `etc.`, "probably", "something like". Resolve or convert each into an explicit Open Question.
 - **Type / API consistency.** Function signatures and field names that appear in multiple tasks must match exactly. The plan is its own contract — internal contradictions surface as bugs during execution.
 - **Wave disjointness.** For every multi-task wave, confirm the tasks' `Files:` sets are pairwise disjoint **and** that no two tasks contend on a shared mutable runtime resource (DB/schema, port, fixture, external service, shared temp path). Either kind of overlap = mis-grouped wave; split or re-order before handoff.
+- **Scoped-test coverage.** Every code-touching wave declares at least one scoped test command; only doc-only waves may have none.
+- **Header-only entrypoint.** The full verification entrypoint appears only in the plan header's `**Verification:**` line. Grep the task body for the header's command string — expect zero hits.
 
 Fix what this review finds before handoff.
 

package/skills/writing-skills/SKILL.md

@@ -183,7 +183,7 @@ If a skill leans on pi capabilities, name them explicitly:
 |---|---|
 | Plan/phase persistence | `plan_tracker` tool (provided by the `pi-gauntlet` package's `plan-tracker` extension) |
 | Progressive disclosure | Direct `read` of `reference/<topic>.md` paths named inline in SKILL.md |
-| Runtime enforcement | `verify-before-ship` extension from `pi-gauntlet` (advisory warning before `git commit` / `git push` / `gh pr create` when no canonical verification command has succeeded since the last source edit) |
+| Runtime enforcement | `verify-before-ship` extension from `pi-gauntlet` (advisory warning before `git push` / `gh pr create` when no canonical verification command has succeeded since the last source edit) |
 | Subagent dispatch | `subagent` tool from `pi-cohort`; baseline subagents from `pi-gauntlet` are `implementer`, `code-reviewer`, `spec-reviewer`, `conformance-reviewer`. Consumer repos can add project-specific subagents under `.pi/agents/`. |
 
 Don't invent capabilities. Don't reference Claude Code's `Task` tool, OpenCode hooks, or Codex `spawn_agent` unless the skill is explicitly for that harness.