pi-gauntlet 4.8.2 → 4.9.0

package/CHANGELOG.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## v4.9.0 - 2026-08-14
+
+Review fix rounds parallelize when the reviewer certifies disjoint findings.
+
+- `plan_tracker`: new `add` action - appends tasks as `pending`, preserving existing statuses; fix sub-waves extend the tracker instead of re-initializing it (conformance fix rounds no longer wipe the implement phase's completed task list).
+- `dispatching-parallel-agents`: new "Fix fan-out" section - reviewer-certified `disjoint` finding groups fix in one parallel wave (one implementer per finding, verbatim finding blocks, serial integration, one re-review); silent sequential degradation when no certificate is present.
+- Reviewer contracts (`spec-reviewer-prompt`, `code-reviewer` template + persona, `conformance-reviewer`): global finding IDs (`F<n>`/`G<n>`), per-finding `touched-files`/`touched-resources`, and a shared `Parallel-safe:` partition grammar (drift-guarded copies across templates and personas).
+- `subagent-driven-development`, `requesting-code-review`, `verification-before-completion/conformance-check`: fix loops reference the shared fan-out rule; `requesting-code-review` gains a minimal fix loop (2 rounds, then escalate); severity vocabulary unified on Critical/Moderate/Minor.
+
 ## v4.8.2 - 2026-08-14
 
 Tracker-neutral skill wording - Linear is an example, not the canonical vocabulary.

package/agents/code-reviewer.md

@@ -32,12 +32,15 @@ Verdict: SHIP | FIX_FIRST | REJECT
 Confidence: low | medium | high   (based on how much you could verify locally)
 
 Findings:
-  - [Critical] path/to/file.ts:42 — one-sentence problem
+  - [Critical] F1: path/to/file.ts:42 — one-sentence problem
         Fix: one or two sentences.
-  - [Moderate] ...
-  - [Minor] [shrink] path/to/file.ts:30 — manual loop builds dict; `dict(zip(keys, values))`, 1 line.
+        touched-files: path/to/file.ts
+        touched-resources: none
+  - [Moderate] F2: ...
+  - [Minor] F3: [shrink] path/to/file.ts:30 — manual loop builds dict; `dict(zip(keys, values))`, 1 line.
 
 Complexity: net -<N> lines   (omit if nothing to cut)
+Parallel-safe: F1,F3 disjoint; F2 conflicts F1 (both touch auth.ts)
 ```
 
 Severity:
@@ -46,4 +49,27 @@ Severity:
 - **Moderate** — should fix; open for discussion (significant but not strictly blocking).
 - **Minor** — nit, style, preference, suggestion.
 
+Label every finding with a globally unique `F1..Fn` ID (no restart per severity),
+and a `touched-files:`/`touched-resources:` pair (files/resources a fix would
+touch, or the literal `none`). On any issue-bearing review end the findings
+with one partition line over the `Fn` IDs assigned above; when a task requires
+a trailing `TRAJECTORY:` verdict (re-review), that verdict follows it as the
+true final line:
+
+<!-- grammar identical to skills/requesting-code-review/code-reviewer.md — change them together or not at all; writing-plans' plan-time Parallel-safe: line is a deliberately different free-text form, do NOT unify -->
+
+```
+Parallel-safe: <group>[; <group>]*
+  <group> = <comma-separated finding-id list> " disjoint"
+          | <finding-id> " conflicts " <finding-id> " (" <reason> ")"
+```
+
+Example: `Parallel-safe: F1,F3 disjoint; F2 conflicts F1 (both touch auth.ts)`
+
+IDs inside a `disjoint` list are mutually parallel-safe (their fixes can run
+concurrently). Any file OR runtime-resource overlap between two findings' fixes
+forces `conflicts`. Runtime-resource disjointness is estimated over: DB/schema,
+port, fixture, external service, shared temp path. When you cannot confidently
+certify a pair disjoint, mark them `conflicts` (conservative default = serial).
+
 If you ran verification commands, quote them and their output verbatim under a `Verification:` section. If you did not, say so.

package/agents/conformance-reviewer.md

@@ -99,6 +99,8 @@ Empty values use the literal tokens `absent` / `none` / `unknown` — never a bl
 After the gap blocks, emit one `Parallel-safe:` line so the orchestrator does not
 re-derive fix concurrency:
 
+<!-- grammar identical to skills/subagent-driven-development/spec-reviewer-prompt.md and skills/requesting-code-review/code-reviewer.md (modulo G vs F id prefix) — change them together or not at all; writing-plans' plan-time Parallel-safe: line is a deliberately different free-text form, do NOT unify -->
+
 ```
 Parallel-safe: <group>[; <group>]*
   <group> = <comma-separated gap-id list> " disjoint"
@@ -112,9 +114,7 @@ Parallel-safe: G1,G3 disjoint; G2 conflicts G1 (both touch auth.ts); G4 conflict
 ```
 
 Any **file OR runtime-resource** overlap forces the conflicting gaps into separate
-serial waves — identical to planned-execution wave grouping. Runtime-resource
-disjointness is not machine-checkable; estimate it as `writing-plans`' Runtime-resource
-disjointness rule does. When you cannot confidently certify a pair disjoint, mark them
+serial waves — identical to planned-execution wave grouping. Runtime-resource disjointness is not machine-checkable; estimate it over: DB/schema, port, fixture, external service, shared temp path. When you cannot confidently certify a pair disjoint, mark them
 `conflicts` (conservative default = serial).
 
 ### `recommended` selection policy

package/agents/spec-reviewer.md

@@ -25,20 +25,58 @@ You are a spec compliance reviewer. Your job is to verify that an implementation
 ```
 Per-requirement status:
   - [MET]          REQ-1: short requirement text — evidence: file.ts:42
-  - [PARTIAL]      REQ-2: ... — evidence: file.ts:80; missing: ...
-  - [MISSING]      REQ-3: ... — searched: <where>
+  - [PARTIAL]      F1: REQ-2: ... — evidence: file.ts:80; missing: ...
+        touched-files: file.ts
+        touched-resources: none
+  - [MISSING]      F2: REQ-3: ... — searched: <where>
+        touched-files: file.ts, other.ts
+        touched-resources: none
   - [OUT_OF_SCOPE] REQ-4: ... — flagged as non-goal in spec
 
 Scope creep (not in spec, but present):
-  - file.ts:120 — short description
+  - F3: widget.ts:120 — short description
+        touched-files: widget.ts
+        touched-resources: none
 
 Missing from implementation:
-  - REQ-3 — short description
+  - F2: REQ-3 — short description
 
 Verdict: COMPLIANT | NEEDS_REWORK | OUT_OF_SCOPE_CHANGES
 Confidence: low | medium | high
+
+Parallel-safe: F1,F3 disjoint; F2 conflicts F1 (both touch file.ts)
 ```
 
+## Finding IDs and fix-concurrency certification
+
+Label every finding (each `PARTIAL`/`MISSING` requirement, each scope-creep
+item) with a globally unique ID `F1..Fn`, numbered across the whole report
+(no restart per section). Each finding carries:
+
+- `touched-files:` — files a fix would edit (not just the evidence location), comma-separated, or the literal `none`
+- `touched-resources:` — shared runtime resources a fix or its verification touches (DB/schema, port, fixture, external service, shared temp path), or the literal `none`
+
+On any issue-bearing review (any `PARTIAL`, `MISSING`, or scope-creep finding),
+end the findings with one partition line over the `Fn` IDs assigned above; when
+a task requires a trailing `TRAJECTORY:` verdict (re-review), that verdict
+follows it as the true final line:
+
+<!-- grammar identical to skills/subagent-driven-development/spec-reviewer-prompt.md — change them together or not at all; writing-plans' plan-time Parallel-safe: line is a deliberately different free-text form, do NOT unify -->
+
+```
+Parallel-safe: <group>[; <group>]*
+  <group> = <comma-separated finding-id list> " disjoint"
+          | <finding-id> " conflicts " <finding-id> " (" <reason> ")"
+```
+
+Example: `Parallel-safe: F1,F3 disjoint; F2 conflicts F1 (both touch auth.ts)`
+
+IDs inside a `disjoint` list are mutually parallel-safe (their fixes can run
+concurrently). Any file OR runtime-resource overlap between two findings' fixes
+forces `conflicts`. Runtime-resource disjointness is estimated over: DB/schema,
+port, fixture, external service, shared temp path. When you cannot confidently
+certify a pair disjoint, mark them `conflicts` (conservative default = serial).
+
 ## Rules
 
 - You are **read-only**. Never edit files.

package/extensions/plan-tracker.test.ts

@@ -0,0 +1,66 @@
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import registerPlanTracker from "./plan-tracker.ts";
+
+type ToolResult = {
+  content: { type: string; text: string }[];
+  details: { action: string; tasks: { name: string; status: string }[]; error?: string };
+};
+
+function harness(branch: unknown[] = []) {
+  const tools: { name: string; execute: (...args: any[]) => unknown }[] = [];
+  const pi = {
+    on(_event: string, _handler: unknown) {},
+    registerTool(tool: { name: string; execute: (...args: any[]) => unknown }) {
+      tools.push(tool);
+    },
+  };
+  registerPlanTracker(pi as any);
+  const ctx = { hasUI: false, sessionManager: { getBranch: () => branch } };
+  const call = async (params: Record<string, unknown>): Promise<ToolResult> =>
+    (await tools[0].execute("id", params, undefined, undefined, ctx)) as ToolResult;
+  return { call };
+}
+
+test("add appends pending tasks and preserves existing statuses", async () => {
+  const { call } = harness();
+  await call({ action: "init", tasks: ["a", "b", "c"] });
+  await call({ action: "update", index: 0, status: "complete" });
+  const res = await call({ action: "add", tasks: ["d", "e"] });
+  assert.equal(res.details.error, undefined);
+  assert.equal(res.details.action, "add");
+  assert.deepEqual(
+    res.details.tasks.map((t) => [t.name, t.status]),
+    [["a", "complete"], ["b", "pending"], ["c", "pending"], ["d", "pending"], ["e", "pending"]],
+  );
+});
+
+test("add with no active plan creates one", async () => {
+  const { call } = harness();
+  const res = await call({ action: "add", tasks: ["g1"] });
+  assert.equal(res.details.error, undefined);
+  assert.deepEqual(res.details.tasks, [{ name: "g1", status: "pending" }]);
+});
+
+test("add result carries the FULL merged list (reconstruction invariant)", async () => {
+  const { call } = harness();
+  await call({ action: "init", tasks: ["a"] });
+  await call({ action: "update", index: 0, status: "in_progress" });
+  const res = await call({ action: "add", tasks: ["b"] });
+  // reconstructState rebuilds wholesale from the latest details.tasks:
+  // the add result alone must reproduce the whole plan.
+  assert.deepEqual(res.details.tasks, [
+    { name: "a", status: "in_progress" },
+    { name: "b", status: "pending" },
+  ]);
+});
+
+test("add with empty/missing tasks errors and preserves state", async () => {
+  const { call } = harness();
+  await call({ action: "init", tasks: ["a"] });
+  const res = await call({ action: "add", tasks: [] });
+  assert.equal(res.details.error, "tasks required");
+  assert.deepEqual(res.details.tasks, [{ name: "a", status: "pending" }]);
+  const res2 = await call({ action: "add" });
+  assert.equal(res2.details.error, "tasks required");
+});

package/extensions/plan-tracker.ts

@@ -19,18 +19,18 @@ interface Task {
 }
 
 interface PlanTrackerDetails {
-  action: "init" | "update" | "status" | "clear";
+  action: "init" | "add" | "update" | "status" | "clear";
   tasks: Task[];
   error?: string;
 }
 
 const PlanTrackerParams = Type.Object({
-  action: StringEnum(["init", "update", "status", "clear"] as const, {
+  action: StringEnum(["init", "add", "update", "status", "clear"] as const, {
     description: "Action to perform",
   }),
   tasks: Type.Optional(
     Type.Array(Type.String(), {
-      description: "Task names (for init)",
+      description: "Task names (for init and add)",
     }),
   ),
   index: Type.Optional(
@@ -129,7 +129,7 @@ export default function (pi: ExtensionAPI) {
     name: "plan_tracker",
     label: "Plan Tracker",
     description:
-      "Track progress while EXECUTING an implementation plan (the implement phase) or a verify-phase conformance fix wave. Actions: init (set task list), update (change task status), status (show current state), clear (remove plan). Do NOT use for brainstorming, research, or planning checklists: those phases are open-ended and a bounded task list misrepresents them as a fixed N-step process.",
+      "Track progress while EXECUTING an implementation plan (the implement phase) or a verify-phase conformance fix wave. Actions: init (set task list), add (append tasks as pending; existing statuses preserved), update (change task status), status (show current state), clear (remove plan). Do NOT use for brainstorming, research, or planning checklists: those phases are open-ended and a bounded task list misrepresents them as a fixed N-step process.",
     parameters: PlanTrackerParams,
 
     async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
@@ -158,6 +158,30 @@ export default function (pi: ExtensionAPI) {
           };
         }
 
+        case "add": {
+          if (!params.tasks || params.tasks.length === 0) {
+            return {
+              content: [{ type: "text", text: "Error: tasks array required for add" }],
+              details: {
+                action: "add",
+                tasks: tasks.map((t) => ({ ...t })),
+                error: "tasks required",
+              } as PlanTrackerDetails,
+            };
+          }
+          tasks.push(...params.tasks.map((name) => ({ name, status: "pending" as TaskStatus })));
+          updateWidget(ctx);
+          return {
+            content: [
+              {
+                type: "text",
+                text: `Added ${params.tasks.length} tasks (${tasks.length} total).\n${formatStatus(tasks)}`,
+              },
+            ],
+            details: { action: "add", tasks: tasks.map((t) => ({ ...t })) } as PlanTrackerDetails,
+          };
+        }
+
         case "update": {
           if (params.index === undefined || !params.status) {
             return {
@@ -248,7 +272,7 @@ export default function (pi: ExtensionAPI) {
         text += ` ${theme.fg("accent", `[${args.index}]`)}`;
         if (args.status) text += ` → ${theme.fg("dim", args.status)}`;
       }
-      if (args.action === "init" && args.tasks) {
+      if ((args.action === "init" || args.action === "add") && args.tasks) {
         text += ` ${theme.fg("dim", `(${args.tasks.length} tasks)`)}`;
       }
       return new Text(text, 0, 0);
@@ -273,6 +297,12 @@ export default function (pi: ExtensionAPI) {
             0,
             0,
           );
+        case "add":
+          return new Text(
+            theme.fg("success", "✓ ") + theme.fg("muted", `Added tasks (${taskList.length} total)`),
+            0,
+            0,
+          );
         case "update": {
           const complete = taskList.filter((t) => t.status === "complete").length;
           return new Text(

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

@@ -30,6 +30,8 @@ const sources = {
       Boolean: schema,
       Union: schema,
       Null: schema,
+      Array: schema,
+      Integer: schema,
     };
   `,
 };

package/package.json

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

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

@@ -104,6 +104,20 @@ When agents return:
 
 **If some agents failed:** Integrate successful agents first (commit their work). Then retry the failed agent with fresh context that includes the integrated changes.
 
+## Fix fan-out
+
+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.
+
+**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.
+
+**Degradation:** missing, malformed, or ID-less `Parallel-safe:` line, or no `disjoint` group with ≥ 2 IDs → fully sequential fixes. Degradation is silent — it costs parallelism, never correctness.
+
+**After the fix wave:** integrate patches serially per "Review and Integrate" above (mis-partition is self-healing: integrate the successes, re-run the conflicting finding sequentially on integrated HEAD); run the consuming loop's scoped test gate on the integrated tree; then one re-review of the integrated fix delta, per the consuming loop's own rules. The fan-out counts as one fix round against the consuming loop's budget — it grants no extra rounds.
+
+**Progress:** `plan_tracker({ action: "add" })` one task per fixed finding, named mechanically — `"<prefix>fix F<n>: <finding's first line verbatim>"`, where `<prefix>` is `"W<k>-"` inside an execution wave and empty elsewhere. Fix tasks always extend the tracker, never re-init. Mark `in_progress` at dispatch, `complete` at integration.
+
 ## Agent Prompt Structure
 
 Good agent prompts are:

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

@@ -52,10 +52,12 @@ subagent({ agent: "code-reviewer", task: "... filled template ..." })
 
 **3. Act on feedback:**
 - Fix Critical issues immediately
-- Fix Important issues before proceeding
+- Fix Moderate issues before proceeding
 - Note Minor issues for later
 - Push back if reviewer is wrong (with reasoning)
 
+**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. After integration and the project's test command, re-dispatch the reviewer once on the integrated delta. If Critical or Moderate findings remain, run one more fix round and one more re-review; still failing → escalate to the user. Minor findings never trigger the fan-out.
+
 ## Example
 
 ```
@@ -76,7 +78,7 @@ HEAD_SHA=$(git rev-parse HEAD)
 [Subagent returns]:
   Strengths: Clean architecture, real tests
   Issues:
-    Important: Missing progress indicators
+    Moderate: Missing progress indicators
     Minor: Magic number (100) for reporting interval
   Assessment: Ready to proceed
 
@@ -100,7 +102,7 @@ You: [Fix progress indicators]
 **Never:**
 - Skip review because "it's simple"
 - Ignore Critical issues
-- Proceed with unfixed Important issues
+- Proceed with unfixed Moderate issues
 - Argue with valid technical feedback
 
 **If reviewer wrong:**

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

@@ -21,7 +21,7 @@ You are reviewing code changes for production readiness.
 
 Before writing the report:
 
-- **Not everything is Critical.** Reserve Critical for bugs, data loss, security, broken functionality. A missing helper method is Important. A naming preference is Minor.
+- **Not everything is Critical.** Reserve Critical for bugs, data loss, security, broken functionality. A missing helper method is Moderate. A naming preference is Minor.
 - **Lead with strengths.** Accurate praise earns the implementer's trust on the critique that follows. Generic praise ("good code") undermines it.
 - **If you wouldn't block a PR over it, it's not Critical.** Be honest with yourself about severity before assigning it.
 - **Plan deviations get their own treatment.** If the implementation diverged from the spec/plan — added scope, removed scope, changed an interface — call it out under a dedicated "Plan Deviations" heading, not buried in Critical or Minor.
@@ -90,17 +90,20 @@ git diff {BASE_SHA}..{HEAD_SHA}
 #### Critical (Must Fix)
 [Bugs, security issues, data loss risks, broken functionality]
 
-#### Important (Should Fix)
+#### Moderate (Should Fix)
 [Architecture problems, missing features, poor error handling, test gaps]
 
 #### Minor (Nice to Have)
 [Code style, optimization opportunities, documentation improvements]
 
 **For each issue:**
+- `Fn` label - globally unique, numbered across the whole report (no restart per severity section)
 - File:line reference
 - What's wrong
 - Why it matters
 - How to fix (if not obvious)
+- `touched-files:` - files a fix would edit (not just the evidence location), comma-separated, or the literal `none`
+- `touched-resources:` - shared runtime resources a fix or its verification touches (DB/schema, port, fixture, external service, shared temp path), or the literal `none`
 
 ### Recommendations
 [Improvements for code quality, architecture, or process]
@@ -111,6 +114,27 @@ git diff {BASE_SHA}..{HEAD_SHA}
 
 **Reasoning:** [Technical assessment in 1-2 sentences]
 
+### Fix-concurrency certification
+
+On any issue-bearing review, end the report with one partition line over the
+`Fn` IDs assigned above:
+
+<!-- grammar identical to agents/conformance-reviewer.md (modulo G vs F id prefix) — change them together or not at all; writing-plans' plan-time Parallel-safe: line is a deliberately different free-text form, do NOT unify -->
+
+```
+Parallel-safe: <group>[; <group>]*
+  <group> = <comma-separated finding-id list> " disjoint"
+          | <finding-id> " conflicts " <finding-id> " (" <reason> ")"
+```
+
+Example: `Parallel-safe: F1,F3 disjoint; F2 conflicts F1 (both touch auth.ts)`
+
+IDs inside a `disjoint` list are mutually parallel-safe (their fixes can run
+concurrently). Any file OR runtime-resource overlap between two findings' fixes
+forces `conflicts`. Runtime-resource disjointness is estimated over: DB/schema,
+port, fixture, external service, shared temp path. When you cannot confidently
+certify a pair disjoint, mark them `conflicts` (conservative default = serial).
+
 ## Critical Rules
 
 **DO:**
@@ -137,22 +161,28 @@ git diff {BASE_SHA}..{HEAD_SHA}
 
 ### Issues
 
-#### Important
-1. **Missing help text in CLI wrapper**
+#### Moderate
+F1. **Missing help text in CLI wrapper**
    - File: index-conversations:1-31
    - Issue: No --help flag, users won't discover --concurrency
    - Fix: Add --help case with usage examples
+   - touched-files: index-conversations.ts
+   - touched-resources: none
 
-2. **Date validation missing**
+F2. **Date validation missing**
    - File: search.ts:25-27
    - Issue: Invalid dates silently return no results
    - Fix: Validate ISO format, throw error with example
+   - touched-files: search.ts
+   - touched-resources: none
 
 #### Minor
-1. **Progress indicators**
+F3. **Progress indicators**
    - File: indexer.ts:130
    - Issue: No "X of Y" counter for long operations
    - Impact: Users don't know how long to wait
+   - touched-files: indexer.ts
+   - touched-resources: none
 
 ### Recommendations
 - Add progress reporting for user experience
@@ -162,5 +192,7 @@ git diff {BASE_SHA}..{HEAD_SHA}
 
 **Ready to merge: With fixes**
 
-**Reasoning:** Core implementation is solid with good architecture and tests. Important issues (help text, date validation) are easily fixed and don't affect core functionality.
+**Reasoning:** Core implementation is solid with good architecture and tests. Moderate issues (help text, date validation) are easily fixed and don't affect core functionality.
+
+Parallel-safe: F1,F2,F3 disjoint
 ```

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

@@ -69,6 +69,8 @@ One rule governs both review loops - spec-compliance and code-quality - in seque
 
 **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.
 
+**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 plan-declared commands, and one re-review of the integrated delta follows.
+
 **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.
 
 1. **Review 1** (first review - no sentinel). Issues -> dispatch fix 1.
@@ -215,7 +217,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. **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. **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.
+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 naming and lifecycle per conformance-check.md's fix loop / the Fix fan-out Progress rule); 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.
 
@@ -235,6 +237,7 @@ For the fan-out + worktree + patch-integration + conflict mechanics, see `dispat
 - 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)
+- Dispatching fixes sequentially on a clean HEAD despite a ≥ 2-ID `disjoint` group in the review's `Parallel-safe:` line
 - 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/subagent-driven-development/code-quality-reviewer-prompt.md

@@ -24,6 +24,8 @@ Dispatch a subagent with the code-reviewer template:
 
 **Code reviewer returns:** Strengths, Issues (Critical/Moderate/Minor), Assessment
 
+Emit finding IDs and the `Parallel-safe:` line per that contract.
+
 ## Re-review: trajectory verdict
 
 Include the following in the reviewer's task text on every re-review, after
@@ -31,7 +33,8 @@ the prior review report pasted verbatim under a
 `## Previous review report (re-review trigger)` heading:
 
 If your task contains a "Previous review report (re-review trigger)" section
-and you found issues, end your report with exactly one line:
+and you found issues, append exactly one more line after `Parallel-safe:` — this
+line, not `Parallel-safe:`, is the true final line of the report:
 
 TRAJECTORY: CONVERGING (<n_prev> -> <n_now>, max severity <X>)
 TRAJECTORY: DIVERGING

package/skills/subagent-driven-development/spec-reviewer-prompt.md

@@ -62,10 +62,38 @@ Dispatch a subagent with this prompt:
 
     **Verify by reading code, not by trusting report.**
 
+    ### Finding IDs and fix-concurrency certification
+
+    Label every finding with a globally unique ID `F1..Fn`, numbered across the whole
+    report (no restart per severity section). Each finding carries:
+
+    - `touched-files:` — files a fix would edit (not just the evidence location), comma-separated, or the literal `none`
+    - `touched-resources:` — shared runtime resources a fix or its verification touches (DB/schema, port, fixture, external service, shared temp path), or the literal `none`
+
+    On any issue-bearing review, end the findings with one partition line (this is the
+    final line of the report unless a re-review trajectory verdict is also required — see below):
+
+    <!-- grammar identical to agents/conformance-reviewer.md (modulo G vs F id prefix) — change them together or not at all; writing-plans' plan-time Parallel-safe: line is a deliberately different free-text form, do NOT unify -->
+
+    ```
+    Parallel-safe: <group>[; <group>]*
+      <group> = <comma-separated finding-id list> " disjoint"
+              | <finding-id> " conflicts " <finding-id> " (" <reason> ")"
+    ```
+
+    Example: `Parallel-safe: F1,F3 disjoint; F2 conflicts F1 (both touch auth.ts)`
+
+    IDs inside a `disjoint` list are mutually parallel-safe (their fixes can run
+    concurrently). Any file OR runtime-resource overlap between two findings' fixes
+    forces `conflicts`. Runtime-resource disjointness is estimated over: DB/schema,
+    port, fixture, external service, shared temp path. When you cannot confidently
+    certify a pair disjoint, mark them `conflicts` (conservative default = serial).
+
     ## Re-review: trajectory verdict
 
     If your task contains a "Previous review report (re-review trigger)" section
-    and you found issues, end your report with exactly one line:
+    and you found issues, append exactly one more line after `Parallel-safe:` — this
+    line, not `Parallel-safe:`, is the true final line of the report:
 
     TRAJECTORY: CONVERGING (<n_prev> -> <n_now>)
     TRAJECTORY: DIVERGING

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

@@ -142,19 +142,21 @@ prerequisites hold.
 
 Per round:
 
-1. **`plan_tracker` init** with the round's gaps as tasks. Wave-prefix tasks
-   when the reviewer's `Parallel-safe:` line marks a `conflicts` pair (file OR
-   `touched-resources` overlap) — that pair runs in separate serial waves;
-   `disjoint` gaps share one wave. Lifecycle per gap: `pending` →
-   `in_progress` → `complete`. This re-init **replaces** the implement phase's
-   completed task list in the singleton widget — state-safe, since
-   `phase-tracker.ts` `applyPlanActivity` only auto-completes `implement`
-   while it is `in_progress`; the widget now shows fix-wave progress during
+1. **`plan_tracker` add** — append the round's gaps as tasks (`Gn: <gap origin
+   clause verbatim, truncated>`; carry the gap's requirement text mechanically,
+   no orchestrator-authored summaries); never `init`, which would wipe the
+   implement phase's completed task list. Lifecycle per gap: `pending` →
+   `in_progress` → `complete`. The widget now shows fix-wave progress during
    verify.
-2. **Per gap** (task → `in_progress`): dispatch `implementer` (fresh context,
-   `worktree: true`, `cwd` = the conformance worktree, `touched-files` from the
-   gap block as an explicit ownership boundary) → dispatch `spec-reviewer` on
-   the gap-block reference contract below → task → `complete`.
+2. **Fix dispatch** — per `dispatching-parallel-agents` "Fix fan-out": a `disjoint`
+   group of ≥ 2 gaps (per the report's `Parallel-safe:` line) fixes in one parallel
+   dispatch — one `implementer` per gap (fresh context, `worktree: true`, `cwd` =
+   the conformance worktree, task = the gap block verbatim with `touched-files` as
+   the ownership boundary); `conflicts` pairs serialize. Gaps outside any ≥ 2-ID
+   `disjoint` group run sequentially as before. Then dispatch `spec-reviewer` per
+   gap on the gap-block reference contract below. Task lifecycle: mark `in_progress` at
+   dispatch; `complete` is deferred until the gap's patch is successfully
+   integrated in step 3 below.
 3. **Integrate** serially via `git apply` onto the worktree HEAD, one gap's
    patch at a time. Failure handling is inherited verbatim from
    `dispatching-parallel-agents` "Review and Integrate": textual conflict →