pi-gauntlet 6.0.0 → 6.1.0

package/extensions/phase-tracker.test.ts

@@ -290,6 +290,19 @@ test("brainstorm write guard is unchanged by the implement guard", async () => {
   }
 });
 
+test("brainstorm write confinement: a docs/specs write under the default dirs does not warn", 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", "docs/specs/x.md"));
+    assert.equal((await h.emitEvent("tool_result", writeResult("t1")))[0], undefined);
+  } 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);
@@ -1244,6 +1257,17 @@ test("gauntlet_setting escalationLoop: setting absent -> ctx-derived main-loop m
   assert.equal(res.details.implModel, "p/strong:high");
 });
 
+test("gauntlet_setting flowGuards: default dirs + derived plan dirs; repo override replaces them", async () => {
+  const h = harness({ cwd: tempCwd({ piGauntlet: {} }) });
+  const tool = h.tools.find((t) => t.name === "gauntlet_setting")!;
+  const def = (await tool.execute("f1", { key: "flowGuards" }, undefined, undefined, h.ctx)) as { details: unknown };
+  assert.deepEqual(def.details, { key: "flowGuards", enforce: true, specDirs: ["doc/specs", "docs/specs"], planDirs: ["doc/plans", "docs/plans"], errors: [] });
+  const set = harness({ cwd: tempCwd({ piGauntlet: { flowGuards: { specDirs: ["design/specs"] } } }) });
+  const res = (await set.tools.find((t) => t.name === "gauntlet_setting")!.execute("f2", { key: "flowGuards" }, undefined, undefined, set.ctx)) as { details: { specDirs: string[]; planDirs: string[] } };
+  assert.deepEqual(res.details.specDirs, ["design/specs"]);
+  assert.deepEqual(res.details.planDirs, ["design/plans"]);
+});
+
 // --- Conformance fix-loop dispatch guard (spec 2026-09-13-conformance-dispatch-guard) ---
 
 const verifyBranch = (extra: unknown[] = []) => [

package/extensions/phase-tracker.ts

@@ -17,6 +17,7 @@ import { Text } from "@earendil-works/pi-tui";
 import { type Static, Type } from "@sinclair/typebox";
 import {
   mainLoopModel,
+  planDirsFor,
   resolveClosureReview,
   resolveEscalationLoop,
   resolveFlowGuards,
@@ -734,7 +735,7 @@ export default function (pi: ExtensionAPI) {
   });
 
   const GauntletSettingParams = Type.Object({
-    key: StringEnum(["specCouncil", "closureReview", "escalationLoop"] as const, {
+    key: StringEnum(["specCouncil", "closureReview", "escalationLoop", "flowGuards"] as const, {
       description: "Which gauntlet setting to resolve (merged repo-over-preset).",
     }),
   });
@@ -747,16 +748,19 @@ export default function (pi: ExtensionAPI) {
     executionMode: "sequential",
     async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
       const { gauntlet, errors } = loadGauntletSettings(ctx.cwd);
+      const fg = resolveFlowGuards(gauntlet);
       const payload =
         params.key === "specCouncil"
           ? { key: "specCouncil" as const, ...resolveSpecCouncil(gauntlet), errors }
           : params.key === "closureReview"
             ? { key: "closureReview" as const, ...resolveClosureReview(gauntlet), errors }
-            : {
-                key: "escalationLoop" as const,
-                ...resolveEscalationLoop(gauntlet, mainLoopModel(ctx.model, ctx.thinkingLevel)),
-                errors,
-              };
+            : params.key === "flowGuards"
+              ? { key: "flowGuards" as const, ...fg, planDirs: planDirsFor(fg.specDirs), errors }
+              : {
+                  key: "escalationLoop" as const,
+                  ...resolveEscalationLoop(gauntlet, mainLoopModel(ctx.model, ctx.thinkingLevel)),
+                  errors,
+                };
       return {
         content: [{ type: "text", text: "```json\n" + JSON.stringify(payload, null, 2) + "\n```" }],
         details: payload,

package/extensions/telemetry.test.ts

@@ -4,7 +4,7 @@
   import { join } from "node:path";
   import { after, test } from "node:test";
   import registerTelemetry, { realFs, replayBranch, type Deps, type GitResult } from "./telemetry.ts";
-  import { DEFAULT_TELEMETRY_BUCKETS } from "./lib/gauntlet-settings.ts";
+  import { DEFAULT_TELEMETRY_BUCKETS, planDirsFor, resolveFlowGuards } from "./lib/gauntlet-settings.ts";
   import { emptyAccumulators, parseRecord, serializeRecord } from "./lib/telemetry-record.ts";
   import { guardReason } from "./lib/telemetry-ship.ts";
 
@@ -24,6 +24,7 @@
     const root = mkdtempSync(join(tmpdir(), "telemetry-test-"));
     tempDirs.push(root);
     mkdirSync(join(root, "doc/specs"), { recursive: true });
+    mkdirSync(join(root, "docs/specs"), { recursive: true });
     mkdirSync(join(root, "doc/plans"), { recursive: true });
     mkdirSync(join(root, ".worktrees/x/doc/specs"), { recursive: true });
     const handlers = new Map<string, Handler[]>();
@@ -31,6 +32,7 @@
     const gitCwds: string[] = [];
     const jjCalls: string[][] = [];
     const readFileCalls: string[] = [];
+    const specDirs = resolveFlowGuards({}).specDirs;
     let clock = Date.parse("2026-09-17T10:00:00Z");
     const deps: Deps = {
       fs: { ...realFs, readFile: (p) => { readFileCalls.push(p); return realFs.readFile(p); } },
@@ -56,7 +58,7 @@
         if (args[0] === "ls-files") return { code: 0, stdout: "", stderr: "" };
         return { code: 0, stdout: "", stderr: "" };
       },
-      settings: () => ({ telemetry: { enabled: o.enabled ?? true, dir: o.telemetryDir ?? ".pi/gauntlet/telemetry", buckets: DEFAULT_TELEMETRY_BUCKETS, warning: o.telemetryWarning }, errors: [], agentOverrides: { implementer: { model: "p/x" } }, versions: { pi: "0.85.1" } }),
+      settings: () => ({ specDirs, planDirs: planDirsFor(specDirs), telemetry: { enabled: o.enabled ?? true, dir: o.telemetryDir ?? ".pi/gauntlet/telemetry", buckets: DEFAULT_TELEMETRY_BUCKETS, warning: o.telemetryWarning }, errors: [], agentOverrides: { implementer: { model: "p/x" } }, versions: { pi: "0.85.1" } }),
       // A plain jj workspace: `jj root` answers the temp root while git rev-parse fails.
       jj: async (args, cwd) => {
         jjCalls.push(args);
@@ -180,6 +182,19 @@
     assert.equal(readFileSync(h.excludeFile(), "utf8"), ".pi/gauntlet/telemetry/\n", "exclude line is written once after rebind");
   });
 
+  test("a docs/specs write binds under the default dirs and the record lands under telemetry.dir/docs/specs", async () => {
+    const h = harness();
+    await h.phaseResult("start", P({ brainstorm: "in_progress" }));
+    assert.equal(existsSync(h.recordPath("docs/specs/x.md")), false);
+    await h.writeSpec("docs/specs/x.md");
+    assert.equal(h.recordPath("docs/specs/x.md"), join(h.root, ".pi/gauntlet/telemetry/docs/specs/x.yaml"));
+    assert.equal(h.readRecord("docs/specs/x.md").spec, "docs/specs/x.md");
+    await h.phaseResult("complete", P({ brainstorm: "complete" }));
+    const rec = h.readRecord("docs/specs/x.md");
+    assert.equal(rec.approved_at, rec.events.at(-1)!.ts);
+    assert.equal(h.gitWrites().length, 0);
+  });
+
   test("bind derives approved_at from a buffered brainstorm completion", async () => {
     const h = harness();
     await h.phaseResult("start", P({ brainstorm: "in_progress" }));
@@ -231,7 +246,7 @@
       { type: "message", message: { role: "toolResult", toolName: "write", toolCallId: "w1", isError: false } },
       { type: "message", message: { role: "toolResult", toolName: "write", toolCallId: "w2", isError: false } },
       { type: "message", message: { role: "toolResult", toolName: "write", toolCallId: "w3", isError: true } },
-    ]);
+    ], ["doc/specs", "docs/specs"]);
     assert.deepEqual(replay.phases, successfulPhases);
     assert.equal(replay.gauntletEntered, true);
     assert.equal(replay.planCheckSpec, "/repo/doc/specs/a.md");
@@ -246,7 +261,7 @@
     const unarmed = replayBranch([
       ...write("w1", "doc/specs/a.md"),
       { type: "message", message: { role: "toolResult", toolName: "plan_check", details: { status: "pass", specPath: "/repo/doc/specs/a.md" } } },
-    ]);
+    ], ["doc/specs", "docs/specs"]);
     assert.equal(unarmed.gauntletEntered, false);
     assert.equal(unarmed.lastSpecWrite, undefined);
     assert.equal(unarmed.planCheckSpec, undefined);
@@ -254,21 +269,31 @@
       ...write("w0", "doc/specs/before.md"),
       { type: "message", message: { role: "toolResult", toolName: "phase_tracker", details: { action: "start", phases: P({ brainstorm: "in_progress" }) } } },
       ...write("w1", "doc/specs/a.md", "edit"),
-    ]);
+    ], ["doc/specs", "docs/specs"]);
     assert.deepEqual([armed.gauntletEntered, armed.lastSpecWrite], [true, "doc/specs/a.md"]);
     const reset = replayBranch([
       { type: "message", message: { role: "toolResult", toolName: "phase_tracker", details: { action: "start", phases: P({ brainstorm: "in_progress" }) } } },
       ...write("w1", "doc/specs/a.md"),
       { type: "message", message: { role: "toolResult", toolName: "phase_tracker", details: { action: "reset", phases: P() } } },
-    ]);
+    ], ["doc/specs", "docs/specs"]);
     assert.deepEqual([reset.gauntletEntered, reset.lastSpecWrite], [false, undefined]);
     const resumed = replayBranch([
       { type: "message", message: { role: "toolResult", toolName: "phase_tracker", details: { action: "start", phases: P({ brainstorm: "in_progress" }) } } },
       { type: "message", message: { role: "toolResult", toolName: "phase_tracker", details: { action: "skip", phases: { ...P({ brainstorm: "skipped" }), brainstorm: { status: "skipped", reason: "resume: /repo/doc/specs/a.md" } } } } },
-    ]);
+    ], ["doc/specs", "docs/specs"]);
     assert.deepEqual([resumed.gauntletEntered, resumed.lastSpecWrite], [true, "/repo/doc/specs/a.md"]);
   });
 
+  test("replayBranch honors a custom spec dir list", () => {
+    const branch = [
+      { type: "message", message: { role: "toolResult", toolName: "phase_tracker", details: { action: "start", phases: P({ brainstorm: "in_progress" }) } } },
+      { type: "message", message: { role: "assistant", content: [{ type: "toolCall", id: "w1", name: "write", arguments: { path: "design/specs/a.md" } }] } },
+      { type: "message", message: { role: "toolResult", toolName: "write", toolCallId: "w1", isError: false } },
+    ];
+    assert.equal(replayBranch(branch, ["design/specs"]).lastSpecWrite, "design/specs/a.md");
+    assert.equal(replayBranch(branch, ["doc/specs"]).lastSpecWrite, undefined);
+  });
+
   test("session_start replay binds from plan_check details with no spec write, extends sessions, preserves run_id", async () => {
     const first = harness();
     await first.phaseResult("start", P({ brainstorm: "in_progress" }));

package/extensions/telemetry.ts

@@ -14,7 +14,7 @@
   import * as piRuntime from "@earendil-works/pi-coding-agent";
   import { SettingsManager, getAgentDir } from "@earendil-works/pi-coding-agent";
   import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
-  import { DEFAULT_TEST_COMMANDS, resolveTelemetry, settingsErrorWarning, type TelemetryResolved } from "./lib/gauntlet-settings.ts";
+  import { DEFAULT_TEST_COMMANDS, planDirsFor, resolveFlowGuards, resolveTelemetry, settingsErrorWarning, type TelemetryResolved } from "./lib/gauntlet-settings.ts";
   import { loadGauntletSettings } from "./lib/gauntlet-settings-loader.ts";
   import { checkoutOf } from "./lib/checkout.ts";
   import { CONTEXT_DRAFT_MARKER, nextGauntletEntered } from "./lib/phase-tracker-helpers.ts";
@@ -43,6 +43,8 @@
   }
   export interface SettingsSnapshot {
     telemetry: TelemetryResolved;
+    specDirs: string[];
+    planDirs: string[];
     errors: string[];
     agentOverrides?: Record<string, unknown>;
     versions: Record<string, string>;
@@ -118,6 +120,8 @@
   function realSettings(cwd: string): SettingsSnapshot {
     const { gauntlet, errors, root } = loadGauntletSettings(cwd);
     const telemetry = resolveTelemetry(gauntlet);
+    const { specDirs } = resolveFlowGuards(gauntlet);
+    const planDirs = planDirsFor(specDirs);
     const sm = SettingsManager.create(root, getAgentDir());
     const layer = (s: unknown) => ((s as { subagents?: { agentOverrides?: unknown } })?.subagents?.agentOverrides ?? undefined) as Record<string, unknown> | undefined;
     const preset = layer(sm.getGlobalSettings());
@@ -125,7 +129,7 @@
     const agentOverrides = preset || repo ? { ...(preset ?? {}), ...(repo ?? {}) } : undefined;
     const rawCmds = gauntlet.verifyBeforeShip?.testCommands;
     const testCommands = Array.isArray(rawCmds) && rawCmds.length > 0 && rawCmds.every((c) => typeof c === "string" && c.trim()) ? (rawCmds as string[]) : undefined;
-    return { telemetry, errors, agentOverrides, versions: realVersions(), testCommands };
+    return { telemetry, specDirs, planDirs, errors, agentOverrides, versions: realVersions(), testCommands };
   }
 
   export const realDeps: Deps = { fs: realFs, git: realGit, jj: realJj, now: isoNow, settings: realSettings };
@@ -142,16 +146,16 @@
   // gauntlet-resume's reconstruction skips brainstorm with `resume: <spec path>`; the path
   // is the bind candidate on that route because no spec write follows.
   const RESUME_REASON_RE = /^resume: (\S+)$/;
-  export function resumeSpecOf(phases: PhaseMap | undefined): string | undefined {
+  export function resumeSpecOf(phases: PhaseMap | undefined, specDirs: readonly string[]): string | undefined {
     const b = phases?.brainstorm;
     const m = b?.status === "skipped" && typeof b.reason === "string" ? RESUME_REASON_RE.exec(b.reason) : null;
-    return m && isSpecPath(toPosix(m[1])) ? m[1] : undefined;
+    return m && isSpecPath(toPosix(m[1]), specDirs) ? m[1] : undefined;
   }
 
   // Walks the session branch like phase-tracker.ts: successful phase_tracker results set
   // the phase map and the flow-entry marker; bind candidates are taken only while armed
   // and dropped on reset. Silent: no events are emitted.
-  export function replayBranch(entries: Iterable<unknown>): ReplayResult {
+  export function replayBranch(entries: Iterable<unknown>, specDirs: readonly string[]): ReplayResult {
     const out: ReplayResult = { phases: emptyPhases(), gauntletEntered: false };
     const calls = new Map<string, { name: string; args: unknown }>();
     for (const raw of entries) {
@@ -173,14 +177,14 @@
           out.planCheckSpec = undefined;
           out.lastSpecWrite = undefined;
         }
-        const resumed = d.action === "skip" ? resumeSpecOf(d.phases) : undefined;
+        const resumed = d.action === "skip" ? resumeSpecOf(d.phases, specDirs) : undefined;
         if (out.gauntletEntered && resumed) out.lastSpecWrite = resumed;
       } else if (msg.toolName === "plan_check") {
         const d = msg.details as { status?: string; specPath?: string } | undefined;
         if (out.gauntletEntered && d?.status === "pass" && typeof d.specPath === "string") out.planCheckSpec = d.specPath;
       } else if ((msg.toolName === "write" || msg.toolName === "edit") && !msg.isError && msg.toolCallId) {
         const p = (calls.get(msg.toolCallId)?.args as { path?: unknown } | undefined)?.path;
-        if (out.gauntletEntered && typeof p === "string" && isSpecPath(toPosix(p))) out.lastSpecWrite = p;
+        if (out.gauntletEntered && typeof p === "string" && isSpecPath(toPosix(p), specDirs)) out.lastSpecWrite = p;
       }
     }
     return out;
@@ -328,7 +332,7 @@
       predecessorLinks.clear();
       record = loadOrCreate(specRel);
       for (const link of record.supersedes ?? []) {
-        if (!isSafeSpecLink(link)) continue;
+        if (!isSafeSpecLink(link, snap.specDirs)) continue;
         const predecessor = deps.fs.readFile(abs(link));
         if (predecessor !== undefined && isSupersededByBanner(predecessor, record.spec)) predecessorLinks.add(link);
       }
@@ -369,9 +373,9 @@
       councilPending = undefined;
     };
 
-    const isSafeSpecLink = (link: string): boolean => {
+    const isSafeSpecLink = (link: string, specDirs: readonly string[]): boolean => {
       const normalized = posix.normalize(link);
-      return isSpecPath(link) && !posix.isAbsolute(link) && normalized !== ".." && !normalized.startsWith("../");
+      return isSpecPath(link, specDirs) && !posix.isAbsolute(link) && normalized !== ".." && !normalized.startsWith("../");
     };
 
     const refreshLinks = () => {
@@ -449,9 +453,9 @@
       }
       phases = details.phases;
       if (action === "skip" && !boundSpec && canBind() && lastCtx) {
-        const resumed = resumeSpecOf(details.phases);
+        const resumed = resumeSpecOf(details.phases, snap.specDirs);
         const loc = resumed ? await locate(lastCtx, resumed) : undefined;
-        if (loc && isSpecPath(loc.rel)) {
+        if (loc && isSpecPath(loc.rel, snap.specDirs)) {
           await bind(loc.rel, snap, loc.toplevel, loc.via);
           flush();
         }
@@ -481,13 +485,13 @@
       pendingTest.clear();
       sessionId = ctx.sessionManager.getSessionId();
       currentDir = snap.telemetry.dir;
-      const replay = replayBranch(ctx.sessionManager.getBranch());
+      const replay = replayBranch(ctx.sessionManager.getBranch(), snap.specDirs);
       phases = replay.phases;
       gauntletEntered = replay.gauntletEntered;
       if (!canBind()) return;
       const candidate = replay.planCheckSpec ?? replay.lastSpecWrite;
       const loc = candidate ? await locate(ctx, candidate) : undefined;
-      if (loc && isSpecPath(loc.rel)) {
+      if (loc && isSpecPath(loc.rel, snap.specDirs)) {
         await bind(loc.rel, snap, loc.toplevel, loc.via);
         flush();
       }
@@ -537,7 +541,7 @@
         const rawPath = (event.input as { path?: unknown }).path;
         const loc = typeof rawPath === "string" ? await locate(ctx, rawPath) : undefined;
         if (!loc) {
-          if (typeof rawPath === "string" && isSpecPath(toPosix(rawPath))) warn(`spec ${rawPath} is outside a git checkout; telemetry not recorded`);
+          if (typeof rawPath === "string" && isSpecPath(toPosix(rawPath), snap.specDirs)) warn(`spec ${rawPath} is outside a git checkout; telemetry not recorded`);
           return undefined;
         }
         return onSpecInteraction(event.toolName, loc, event, snap);
@@ -568,13 +572,13 @@
     const onSpecInteraction = async (tool: "write" | "edit" | "read", loc: { toplevel: string; rel: string; via: "git" | "jj" }, event: { input: unknown; content: unknown[] }, snap: SettingsSnapshot): Promise<unknown> => {
       const rel = loc.rel;
       if (!boundSpec) {
-        if ((tool === "write" || tool === "edit") && isSpecPath(rel)) {
+        if ((tool === "write" || tool === "edit") && isSpecPath(rel, snap.specDirs)) {
           await bind(rel, snap, loc.toplevel, loc.via);
           if (!boundSpec) return undefined;
           const patch = onBoundSpecWrite(tool, rel, event);
           flush();
           return patch;
-        } else if (isPlanPath(rel)) {
+        } else if (isPlanPath(rel, snap.planDirs)) {
           const spec = planSpecHeader(deps.fs.readFile(join(loc.toplevel, rel)) ?? "");
           const specRel = spec ? repoRelativeToolPath(loc.toplevel, loc.toplevel, spec) : undefined;
           if (specRel && deps.fs.exists(join(loc.toplevel, specRel))) {
@@ -586,7 +590,7 @@
       }
       if (loc.toplevel !== toplevel) {
         // Another checkout: a fresh run, never a rename of this record.
-        if ((tool === "write" || tool === "edit") && isSpecPath(rel) && canBind() && !sealedOnDisk(loc.toplevel, rel, snap.telemetry.dir)) {
+        if ((tool === "write" || tool === "edit") && isSpecPath(rel, snap.specDirs) && canBind() && !sealedOnDisk(loc.toplevel, rel, snap.telemetry.dir)) {
           unbind();
           await bind(rel, snap, loc.toplevel, loc.via);
           if (!boundSpec) return undefined;
@@ -602,13 +606,13 @@
         flush();
         return patch;
       }
-      if (tool === "write" && isSpecPath(rel) && phases.brainstorm.status === "in_progress" && isDraftOrMissing(boundSpec)) {
+      if (tool === "write" && isSpecPath(rel, snap.specDirs) && phases.brainstorm.status === "in_progress" && isDraftOrMissing(boundSpec)) {
         if (await rebind(rel)) onBoundSpecWrite(tool, rel, event);
         flush();
         return undefined;
       }
-      if (tool === "edit" && isSpecPath(rel)) {
-        onOtherSpecEdit(rel, event);
+      if (tool === "edit" && isSpecPath(rel, snap.specDirs)) {
+        onOtherSpecEdit(rel, event, snap.specDirs);
         flush();
       }
       return undefined;
@@ -616,7 +620,7 @@
 
     // Defined in block 2.
     let onBoundSpecWrite: (tool: "write" | "edit", rel: string, event: { input: unknown; content: unknown[] }) => unknown;
-    let onOtherSpecEdit: (rel: string, event: { input: unknown }) => void;
+    let onOtherSpecEdit: (rel: string, event: { input: unknown }, specDirs: string[]) => void;
 
     let amendmentOpen = false;
     let lastPlanTasks: { status: string }[] | undefined;
@@ -728,7 +732,7 @@
       if (!record || !toplevel || liveShipEvent(record.events)) return;
       record.status = "shipped";
       record.shipped_at = deps.now();
-      const out = await computeJjDiff({ jj: deps.jj ?? realJj, cwd: toplevel, spec: record.spec, dir: currentDir, buckets: snap.telemetry.buckets });
+      const out = await computeJjDiff({ jj: deps.jj ?? realJj, cwd: toplevel, spec: record.spec, dir: currentDir, buckets: snap.telemetry.buckets, planDirs: snap.planDirs });
       if (out.warning) warn(out.warning);
       record.derived.modified_files = out.modified_files;
       record.derived.diff = out.diff;
@@ -743,7 +747,7 @@
         const rawPath = (event.input as { path?: unknown }).path;
         if (typeof rawPath === "string" && phases.brainstorm.status === "in_progress") {
           const loc = await locate(ctx, rawPath);
-          if (loc && isSpecPath(loc.rel)) {
+          if (loc && isSpecPath(loc.rel, snap.specDirs)) {
             const recRel = recordPathFor(snap.telemetry.dir, loc.rel);
             const existing = deps.fs.readFile(join(loc.toplevel, recRel));
             const parsed = existing ? parseRecord(existing) : undefined;
@@ -832,8 +836,8 @@
       return undefined;
     };
 
-    onOtherSpecEdit = (rel, event) => {
-      if (!record || !boundSpec || !isSafeSpecLink(rel)) return;
+    onOtherSpecEdit = (rel, event, specDirs) => {
+      if (!record || !boundSpec || !isSafeSpecLink(rel, specDirs)) return;
       if (!isSupersededByBanner(insertedText(event.input), boundSpec)) return;
       predecessorLinks.add(rel);
       refreshLinks();

package/package.json

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

package/skills/brainstorming/SKILL.md

@@ -17,9 +17,9 @@ Identify the target project → set up an isolated worktree → understand curre
 
 Do **not** implement until the design is presented and approved, regardless of simplicity. Implementation-heavy requests define spec scope; they do not lift this gate.
 
-You **may** read code/docs, run the existing system to observe current behavior, write under `doc/specs/`, and `edit` a predecessor spec there to add a [supersession banner](reference/superseding.md).
+You **may** read code/docs, run the existing system to observe current behavior, write under a resolved spec dir (`gauntlet_setting({ key: "flowGuards" })` -> `specDirs`), and `edit` a predecessor spec there to add a [supersession banner](reference/superseding.md).
 
-You may **not** write outside `doc/specs/`; build, deploy, validate, or exercise the proposed change; run implementation skills; commit the spec on `main`; or start `/skill:writing-plans`.
+You may **not** write outside the resolved spec dirs; build, deploy, validate, or exercise the proposed change; run implementation skills; commit the spec on `main`; or start `/skill:writing-plans`.
 
 The line: current-system observation is research; exercising the proposed change waits for approval.
 
@@ -63,7 +63,7 @@ Detection order: (1) infer from ticket labels, description, or paths; (2) use th
 The spec is the first commit in a dedicated worktree, never a separate commit on `main`.
 
 1. Invoke `/skill:using-git-worktrees`; use `.worktrees/` or the project-native location.
-2. Carry its `Worktree ready at <full-path>` value: spec path `<full-path>/doc/specs/<filename>.md`; every dispatch uses that `cwd`; git uses `git -C <full-path>`. Keep the process cwd unchanged.
+2. Carry its `Worktree ready at <full-path>` value: spec path `<full-path>/<spec dir>/<filename>.md`; every dispatch uses that `cwd`; git uses `git -C <full-path>`. Keep the process cwd unchanged.
 3. Write, review, and commit there.
 
 Spec, plan, and implementation share this worktree. The spec and its telemetry record (`<telemetry.dir>/<spec path with .md -> .yaml>`, default `.pi/gauntlet/telemetry/doc/specs/<spec>.yaml`) are deliverables and ship in the squash; only the plan is stripped. `/skill:finishing-a-development-branch` strips the plan, then seals and commits the record before landing. Explicit trivial one-off edits outside this flow need no worktree.
@@ -146,7 +146,7 @@ Shared schemas, contracts, and invariants require a spec. If work is mechanical
 
 ## Filename Convention
 
-Write under the routed `doc/specs/`: ticketed `YYYY-MM-DD-<ticket-id>-<topic>.md`, otherwise `YYYY-MM-DD-<topic>.md`. Use a filename-safe tracker slug (`E-12345`, `gh-123`), but native references in plan headers and commits. `<topic>` is 3-6 kebab-case words without `-design` or another suffix.
+Write under the routed spec dir: pick the routing prose's dir (overrides file, `AGENTS.md`) when it is one of the resolved dirs, else the one resolved dir from `gauntlet_setting({ key: "flowGuards" })` that already exists in the repo, else the first resolved dir (`doc/specs` under the default). Name ticketed files `YYYY-MM-DD-<ticket-id>-<topic>.md`, otherwise `YYYY-MM-DD-<topic>.md`. Use a filename-safe tracker slug (`E-12345`, `gh-123`), but native references in plan headers and commits. `<topic>` is 3-6 kebab-case words without `-design` or another suffix.
 
 Mint the slug once during gather and reuse it. If questionary invalidates it, write to the new path and delete the uncommitted draft.
 
@@ -293,7 +293,7 @@ One question at a time, YAGNI, 2-3 approaches, two design rounds, clarify freely
 
 ## Red Flags — STOP
 
-- Writes outside `doc/specs/` ([owner](#hard-constraint)).
+- Writes outside the resolved spec dirs ([owner](#hard-constraint)).
 - Draft overwrite without the same-turn full read, or overwrite via `edit` ([owner](#spec-self-review-before-user-review-gate)).
 - Dispatch while line 1 is the context-draft marker ([owner](#spec-self-review-before-user-review-gate)).
 - Inline scope or ambiguity checks ([owner](#spec-council-optional)).

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

@@ -111,7 +111,7 @@ When agents return:
 
 Fix rounds in review loops reuse the fan-out mechanics above, keyed off the reviewer's partition certificate — the orchestrator never partitions findings itself.
 
-Reviewers certify fix concurrency with a `Parallel-safe:` line (see the reviewer's report contract). The fan-out trigger is a `disjoint` group naming **≥ 2 finding IDs**: that group IS the parallel wave — dispatch **one `implementer` per finding ID in the group** (`context: "fresh"`, `worktree: true`, `cwd` = the current worktree; task = that finding's block **verbatim**, including its `touched-files` line as the ownership boundary). A finding named in any `conflicts` pair runs sequentially after every finding it names has integrated (chained `conflicts` define a partial order; remaining serial findings run in the line's order). Findings outside any ≥ 2-ID `disjoint` group run sequentially. Fan out per review line only — never merge or co-schedule groups from different `Parallel-safe:` lines; run those fan-outs serially.
+Reviewers certify fix concurrency with a `Parallel-safe:` line (see the reviewer's report contract). The fan-out trigger is a `disjoint` group naming **≥ 2 actionable finding IDs**: that group IS the parallel wave — dispatch **one `implementer` per actionable finding ID in the group (the probe's actionable set; the consuming loop places non-actionable findings)** (`context: "fresh"`, `worktree: true`, `cwd` = the current worktree; task = that finding's block **verbatim**, including its `touched-files` line as the ownership boundary). An actionable finding named in any `conflicts` pair runs sequentially after every finding it names has integrated (chained `conflicts` define a partial order; remaining serial findings run in the line's order). Actionable findings outside any ≥ 2-ID `disjoint` group run sequentially. Fan out per review line only — never merge or co-schedule groups from different `Parallel-safe:` lines; run those fan-outs serially.
 
 **Precondition:** a clean committed HEAD containing the code under review. When the reviewed change is an unintegrated patch (a wave-mode per-patch spec review), each fix task branches from the wave's base HEAD and carries the prior patch verbatim in its task text — the consuming loop's existing re-dispatch protocol. When the tree is dirty (e.g. post-integration, before the wave commit), the fan-out is unavailable: fix sequentially in place.
 

package/skills/finishing-a-development-branch/SKILL.md

@@ -82,7 +82,9 @@ This is an **enforced disposition gate**, not a surface-only notice. The user is
 
 **Freshness precondition - before any verdict branch, including `CONFORMS`.** The durable block opens with a sentinel: `status: CONFORMS (0 open)` or `status: GAPS (N open)`, then `audited-base: <full HEAD SHA at audit time>`, then an optional `happy-path: <outcome>` line (present exactly when a happy-path run happened; informational, never a freshness input). Read the sentinel, then apply the reference's freshness rule (its `## Closure / conformance` block is the single source): compare `audited-base` to the current working tree; any change, doubt, missing/mismatched sentinel, legacy terse row, or malformed structured reviewer block triggers a fresh audit and replacement of the closure block. Never infer `CONFORMS` from the absence of bullets. Only a clean, valid `status: CONFORMS (0 open)` handoff enters the zero-gap fast path.
 
-**Zero-gap fast path:** print exactly
+**Whole-diff minors (both paths).** Read the block's `whole-diff minors:` section (`conformance-check.md` "Closure / conformance") and render it as one informational, non-blocking line in the `happy-path:` position - directly under the `happy-path:` line when present, otherwise directly under `Closure / conformance: CONFORMS` or the `Conformance: N decisions needed before shipping.` header: `whole-diff minors (3, not blocking): F3, F7, F9`, `whole-diff minors: none`, or `whole-diff minors: not recorded` (section absent). Never a re-audit trigger. The reply point is the Step 4 menu.
+
+**Zero-gap fast path:** print (plus the informational lines below)
 
 ```
 Closure / conformance: CONFORMS
@@ -177,7 +179,9 @@ Which option?
 
 Rows 1-2 run the Option 1/2 blocks; row 3 runs the Keep block and row 4 the Discard block.
 
-**Don't add explanation** - keep options concise.
+**Don't add explanation** - keep options concise. When the minors line lists findings and the block has no `whole-diff minors fix:` line, add only this line under the menu: `Or reply "fix minors" (or "fix minors F3, F9") for one Minor fix round.` This line is the only addition to the exact numbered options.
+
+**Standalone extra reply - `fix minors`.** When the rendered `whole-diff minors` line lists findings, `fix minors` (all) or `fix minors F3, F9` (a subset by `Fn`) is a valid reply beside the numbered options. It dispatches one `implementer` round (`cwd` = the worktree; task = the selected finding lines verbatim; `SCOPED_TEST_COMMANDS` = the plan-header verification set), commits `whole-diff minors fix`, and returns to Step 3.5, where the freshness rule re-audits conformance as for any working-tree change and the regenerated block records the spent round (`whole-diff minors fix: <full SHA>`); Step 4 then re-renders. No code review follows this round: the whole-diff review is an unscoped first review, so its Minors are graded Minors. A block that already carries `whole-diff minors fix:` refuses the reply with "minors round already spent". Any numbered choice ships without them.
 
 ### Step 5: Execute Choice
 
@@ -185,11 +189,11 @@ Rows 1-2 run the Option 1/2 blocks; row 3 runs the Keep block and row 4 the Disc
 
 Run this on the feature branch before any landing path. The spec and its telemetry record (`<telemetry.dir>/<spec path with .md -> .yaml>`, default `.pi/gauntlet/telemetry/doc/specs/<spec>.yaml`) are deliverables and ship in the squash; only the plan is stripped. The record is an untracked, git-excluded file until this step commits it. `<bin>` is `<directory of this skill's SKILL.md>/../../bin`, resolved from the skill's `<location>` in the system prompt.
 
-Read the plan's `**Spec:**` header (repo-relative, backticks stripped) before the strip; that value is `--spec`.
+Read the plan's `**Spec:**` header (repo-relative, backticks stripped) before the strip; pass that value as `--spec`. Resolve the spec dirs with `gauntlet_setting({ key: "flowGuards" })` and use their sibling `plans` dirs for plan paths.
 
 ```bash
 # Plans are ephemeral - if one was committed on this branch, remove it before landing.
-PLAN_PATH=doc/plans/<plan-file>.md   # or <service>/doc/plans/<plan-file>.md
+PLAN_PATH=<sibling-plans-dir>/<plan-file>.md   # the sibling plans dir of the spec's dir
 if git -C "$WORKTREE" ls-files --error-unmatch "$PLAN_PATH" >/dev/null 2>&1; then
   git -C "$WORKTREE" rm "$PLAN_PATH" && git -C "$WORKTREE" commit -m "Remove ephemeral plan doc"
 fi

package/skills/gauntlet-resume/reference/reconstruction.md

@@ -25,10 +25,7 @@ for a base ref before reading any artifact.
 
 A pinned spec (seed route, `seed.md`) skips this section.
 
-Spec/plan directories: `piGauntlet.flowGuards.specDirs` plus each one's sibling `plans` directory. Resolve with the precedence `doc/configuration.md` documents for every `piGauntlet.*` key: the session cwd's `.pi/settings.json` if it defines `flowGuards`,
-else the active pi profile's `settings.json`, else the default `["doc/specs"]` (sibling
-`doc/plans`). An empty array is the default. `<dirs>` below is that resolved list,
-space-separated - never the literal defaults when a setting is present.
+Resolve with `gauntlet_setting({ key: "flowGuards" })`; `<dirs>` below is its `specDirs` plus `planDirs` (each spec dir's sibling `plans` dir), space-separated.
 
 ```bash
 git -C <worktree> diff --diff-filter=A --name-only <base>..HEAD -- <dirs>

package/skills/requesting-code-review/SKILL.md

@@ -51,9 +51,11 @@ subagent({ agent: "code-reviewer", async: false, task: "... filled template ..."
 - `{DESCRIPTION}` - Brief summary
 - `{SCOPED_TEST_COMMANDS}` - the scoped verification commands the reviewer may run, or `none`
 
-**Fix rounds.** Critical and Moderate findings trigger a fix round; when dispatched from an orchestrating skill, fixes go to `implementer` subagents (per the orchestrator's no-self-coding rule), fanned out per `dispatching-parallel-agents` "Fix fan-out" when the review's `Parallel-safe:` line certifies a `disjoint` group of ≥ 2 findings. Before fanning out, validate the review's `Parallel-safe:` line with the structural probe in `dispatching-parallel-agents` § Fix fan-out (exactly-one-line grammar check, one re-ask, then explicit sequential fallback). After integration and the project's test command, re-dispatch the reviewer once on the integrated delta in the foreground with top-level `async: false`; await its terminal result. If Critical or Moderate findings remain, run one more fix round and one more foreground re-review; still failing → escalate to the user. Minor findings never trigger the fan-out.
+**Fix rounds.** A `FIX_FIRST` report triggers a fix round. A `SHIP` report dispatches nothing and ends the loop, whatever Minors it lists. `REJECT` is neither: stop and report (in SDD, per its `stop-note.md`); no fix round. When dispatched from an orchestrating skill, fixes go to `implementer` subagents (per the orchestrator's no-self-coding rule), fanned out per `dispatching-parallel-agents` "Fix fan-out" when the review's `Parallel-safe:` line certifies a `disjoint` group of ≥ 2 Critical/Moderate findings. Before fanning out, validate the review's `Parallel-safe:` line with the structural probe in `dispatching-parallel-agents` § Fix fan-out (exactly-one-line grammar check, one re-ask, then explicit sequential fallback). Sequential round (one task): the task carries the whole report; every Minor rides. Fan-out: the certificate partitions the Critical and Moderate findings; each Minor attaches once to the first task, in `Fn` order, whose ownership boundary - the union of its findings' `touched-files:` - already contains the Minor's `touched-files:`; a Minor no boundary contains is not dispatched this round, and a boundary never grows for a Minor. The implementer fixes its Minors or declines one with a stated reason. After integration and the project's test command, re-dispatch the reviewer once on the integrated delta in the foreground with top-level `async: false`; await its terminal result. A `FIX_FIRST` re-review buys one more fix round and one more foreground re-review; still `FIX_FIRST` -> escalate to the user. A `SHIP` report's Minors are not carried, with one exception: the whole-diff review's Minor finding lines go verbatim into the closure block's `whole-diff minors:` section (`verification-before-completion/reference/conformance-check.md` "Closure / conformance").
 
-Take the recipient stance from `receiving-code-review`: verify each finding, answer a wrong finding with evidence, defer Minor items explicitly.
+Worked example: a `FIX_FIRST` report with 1 Moderate and 3 Minors -> one implementer task holding all four findings (one actionable ID, no fan-out). A `SHIP` report with 4 Minors -> no dispatch; the loop ends.
+
+Take the recipient stance from `receiving-code-review`: verify each finding, answer a wrong finding with evidence.
 
 ## Integration with Workflows
 

package/skills/subagent-driven-development/SKILL.md

@@ -62,7 +62,7 @@ For each task in `plan_tracker`:
 3. **Dispatch spec reviewer.** Pass the task text, the patch diff, the absolute spec path, and the task's `**Spec:**` anchors, plus the task's `**Tests:**` block and `- Test:` paths as contract (never as commands - SR never executes) — SR reads the anchored ranges from the spec file itself; never inline spec excerpts. The spec wins every dispute; the authority hierarchy and finding labels live in `./spec-reviewer-prompt.md`. Anchor-less tasks (no `**Spec:**` line): task text alone is the contract. Verify the change satisfies the anchored spec — nothing missing, nothing extra.
 4. If spec reviewer finds gaps → re-dispatch implementer to fix → re-review. Loop until ✅, within [Fix-Loop Rounds](#fix-loop-rounds).
 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. Pass the task's `SCOPED_TEST_COMMANDS`.
-6. If quality reviewer finds issues → re-dispatch implementer → re-review. Loop until ✅, within [Fix-Loop Rounds](#fix-loop-rounds).
+6. If the quality review is issue-bearing → re-dispatch the implementer per `/skill:requesting-code-review` Fix rounds → re-review. Loop until ✅, within [Fix-Loop Rounds](#fix-loop-rounds).
 7. After its existing reviews accept the work (and its required commit point), mark that same task index `complete` in `plan_tracker`. A subagent exit or green tests alone are not acceptance.
 
 The orchestrator is the spec's only writer during execution. Amendment trigger: implementer `BLOCKED` citing a spec defect, or a review finding showing the spec (not the code) is wrong -> pause the fix loop, execute brainstorming's [amendment path](../brainstorming/SKILL.md#amending-an-approved-spec) in place (it reviews first, stops only on escalation or redraw), resume. Code-vs-spec mismatch stays in the SR loop. An SR unable to read the spec at a cited anchor (missing file, unresolvable heading/range) returns a blocking finding — the contract is spec+task or stop, never a silent fallback to task-only review.
@@ -73,15 +73,15 @@ After all tasks: proceed to [After All Tasks](#after-all-tasks-complete) - it ow
 
 One rule governs both review loops - spec-compliance and code-quality - in sequential and parallel-wave modes alike.
 
-**Re-review dispatch rule:** every re-review task includes the complete prior review report verbatim under the marker `## Previous review report (re-review trigger)`, plus the trajectory block from the reviewer's prompt template. The marker's presence is what obligates the reviewer to emit the `TRAJECTORY:` line. You never select, summarize, or diff findings yourself - pattern-match the sentinel line only.
+**Re-review dispatch rule:** every re-review task includes the complete prior review report verbatim under the marker `## Previous review report (re-review trigger)`, plus the trajectory block from the reviewer's prompt template. The marker's presence is what obligates the reviewer to emit the `TRAJECTORY:` line. You never select, summarize, or diff findings yourself - pattern-match the sentinel line only. Code re-reviews also carry a `## Fix delta` block holding the fix round just integrated: sequential mode, the output of `git diff <HEAD the prior review was dispatched against> HEAD`; wave mode (HEAD unmoved until step 7), the applied fix patch(es) verbatim, never a SHA range. Whole-diff re-reviews never carry the block. Omit it otherwise only when the input is unavailable (a fresh-session resume); the reviewer then treats the task's whole diff as the delta.
 
-**Fix fan-out.** When the triggering review's `Parallel-safe:` line certifies a `disjoint` group of ≥ 2 findings, dispatch that fix round per `dispatching-parallel-agents` "Fix fan-out"; the fan-out counts as **one** fix against this budget, its scoped test gate is the consuming task/wave's `SCOPED_TEST_COMMANDS`, and one re-review of the integrated delta follows.
+**Fix fan-out.** When a fix round is fanned out per `/skill:requesting-code-review` Fix rounds, dispatch per `dispatching-parallel-agents` "Fix fan-out"; the fan-out counts as **one** fix against this budget, its scoped test gate is the consuming task/wave's `SCOPED_TEST_COMMANDS`, and one re-review of the integrated delta follows.
 
 **Behaviour-change reroute.** When the triggering CR report carries `Behaviour-change: yes`, the fix round's re-review is SR first, then CR. The SR dispatch reviews the fix diff against the task's spec anchors as a first review (no `## Previous review report` marker, so no `TRAJECTORY:` line; SR carries no test commands but does carry the task's `**Tests:**` block and `- Test:` paths), but its ordinal continues the task's SR-loop count - a task whose SR loop ended at review 2 gets review 3 here, and an issue-bearing rerouted SR after review 4 escalates. Issues follow the normal sequence: fix, then SR re-review pasting this SR's report. CR round numbering is unchanged. `Behaviour-change: no` re-reviews with CR only. A missing or malformed `Behaviour-change:` line is re-asked once like `Parallel-safe:` (see `dispatching-parallel-agents` "Structural probe"); still missing -> route through SR, never default to `no`. In wave mode the SR re-review targets the task(s) whose files the fix touched.
 
 Every fix re-dispatch (implementer) and code-review re-review carries the consuming task/wave's `SCOPED_TEST_COMMANDS`; spec-reviewer re-reviews carry the `**Tests:**` block and `- Test:` paths, no commands - SR never executes.
 
-**The sequence.** Each review that finds issues is a decision point: read the `TRAJECTORY:` line before dispatching anything (review 1 has no line - on issues, dispatch fix 1). Any clean review ends the loop.
+**The sequence.** Each review that finds issues is a decision point: read the `TRAJECTORY:` line before dispatching anything (review 1 has no line - on issues, dispatch fix 1). Any clean review ends the loop. For code review, *issue-bearing* means verdict `FIX_FIRST` and *clean* means verdict `SHIP`, whatever Minors the report lists; spec review keeps its gaps/acceptance meaning. `REJECT` is neither: stop and report per `stop-note.md`; the loop never enters.
 
 1. **Review 1** (first review - no sentinel). Issues -> dispatch fix 1.
 2. **Review 2** (re-review). Issues -> if `STAGNANT`, escalate now - no fix 2. Otherwise dispatch fix 2.
@@ -170,7 +170,7 @@ Auto-selected at handoff by `writing-plans` (any wave with ≥2 tasks) when the
 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**, the absolute spec path, and the task's `**Spec:**` anchors, plus its `**Tests:**` block and `- Test:` paths as contract — SR reads the anchored ranges itself (never inline excerpts; authority hierarchy in `./spec-reviewer-prompt.md`; anchor-less tasks are task-text-only). Review starts from the diff (its hunks carry `file:line`) and reads each touched file in full, and test execution is never the reviewer's job - in either mode (persona rule; the wave test gate in step 5 runs the wave's `SCOPED_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 ✅, within [Fix-Loop Rounds](#fix-loop-rounds), same as sequential.
 4. **Integrate.** `git -C <worktree> 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 wave's `SCOPED_TEST_COMMANDS` (union of its tasks' `Tests:` commands) on the integrated tree as `(cd "<worktree>" && <command>)` for each command — 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.** CR binds to the wave: exactly one **initial** code-review dispatch per code-touching wave, over the integrated wave diff - never per task within a wave, never batched across waves. Subsequent dispatches within the wave are re-reviews triggered only by findings, per Fix-Loop Rounds. Pass the wave's `SCOPED_TEST_COMMANDS`. Code-quality review on the integrated wave diff; loop fixes to ✅ within [Fix-Loop Rounds](#fix-loop-rounds), same as sequential. Skip for doc-only waves (SR-only per the commit precondition below).
+6. **Quality review.** CR binds to the wave: exactly one **initial** code-review dispatch per code-touching wave, over the integrated wave diff - never per task within a wave, never batched across waves. Subsequent dispatches within the wave are re-reviews triggered only by findings, per Fix-Loop Rounds. Pass the wave's `SCOPED_TEST_COMMANDS`. Code-quality review on the integrated wave diff; when issue-bearing, re-dispatch the implementer per `/skill:requesting-code-review` Fix rounds and re-review, to ✅ within [Fix-Loop Rounds](#fix-loop-rounds), same as sequential. Skip for doc-only waves (SR-only per the commit precondition below).
 7. **Commit and complete the wave.** After the gate passes, commit with `git -C <worktree> add ... && git -C <worktree> commit ...`, then mark all of its existing indices `complete`. 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). 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.
@@ -221,7 +221,7 @@ 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. **Parent full verification.** Run the complete plan-header `**Verification:**` command set foreground in the worktree via `(cd "<worktree>" && <command>)`: tests plus every declared lint, type, format, and build check. A failure must be repaired and the full set rerun successfully before the next step. Before dispatching a verification repair, reopen (`in_progress`) every existing plan-task index whose `Files:` ownership includes its touched files; leave unowned cross-cutting repair work in the verification report. Those indices stay `in_progress` through the successful full rerun **and** step 2's whole-diff review accepting the repair — that acceptance is their completion point, not the passing rerun. Commit any verification-produced tracked changes; use the resulting `HEAD_SHA` in the review task and include the commands/results in its existing `DESCRIPTION`.
-2. **Whole-diff code review.** Only after passing full verification, dispatch one foreground whole-diff `code-reviewer` per `/skill:requesting-code-review` against that committed HEAD, with `SCOPED_TEST_COMMANDS: none`; the reviewer does not repeat the full suite. Address Critical and Moderate findings. Before dispatching a review repair, reopen (`in_progress`) every existing plan-task index whose `Files:` ownership includes its touched files; leave unowned cross-cutting repair work in the review report. Mark each reopened index `complete` only once the repair is re-verified and the re-review accepts it — this is the same completion point step 1's reopened indices wait for, not an extra gate, and the gate order stays full verification -> whole-diff CR -> conformance. Any repair invalidates prior full verification, so rerun the full set successfully before the next gate.
+2. **Whole-diff code review.** Only after passing full verification, dispatch one foreground whole-diff `code-reviewer` per `/skill:requesting-code-review` against that committed HEAD, with `SCOPED_TEST_COMMANDS: none`; the reviewer does not repeat the full suite. Act on the verdict per `/skill:requesting-code-review` Fix rounds; carry the final `SHIP` report's Minor finding lines verbatim into the closure block's `whole-diff minors:` section (`verification-before-completion/reference/conformance-check.md` "Closure / conformance"), or `whole-diff minors: none`. Before dispatching a review repair, reopen (`in_progress`) every existing plan-task index whose `Files:` ownership includes its touched files; leave unowned cross-cutting repair work in the review report. Mark each reopened index `complete` only once the repair is re-verified and the re-review accepts it — this is the same completion point step 1's reopened indices wait for, not an extra gate, and the gate order stays full verification -> whole-diff CR -> conformance. Any repair invalidates prior full verification, so rerun the full set successfully before the next gate.
 3. **Close the loop — conformance check.** The review in step 2 is plan-vs-code (single-step); it inherits any requirement the plan already dropped.
 
    **Happy-path run - first action of this step, only when the plan header carries a `**Happy path:**` line or the diff selects a row.** The overrides file's `## Happy path` table (schema in the README overrides contract) names path-prefixed rows; the plan header's line is the plan-time default.