pi-gauntlet 4.7.0 → 4.8.0

package/CHANGELOG.md

@@ -1,5 +1,14 @@
 # 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).

package/README.md

@@ -66,7 +66,7 @@ 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, 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.
 

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/phase-tracker.test.ts

@@ -287,3 +287,192 @@ test("resumed session: closure gate blocks complete verify without a conformance
   };
   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

@@ -67,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" +
@@ -266,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).
@@ -329,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) {
@@ -349,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);
@@ -522,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,
@@ -548,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/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.7.0",
+  "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

@@ -55,7 +55,7 @@ On a fresh resume:
 
    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).
+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.
 
@@ -80,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.**
@@ -113,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.
@@ -143,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
@@ -160,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.
@@ -204,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
@@ -212,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:
@@ -235,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.