planflow-ai 1.3.4 → 1.4.1

package/.claude/resources/core/per-task-verification.md

@@ -0,0 +1,362 @@
+
+# Per-Task Verification
+
+## Purpose
+
+When a plan phase includes tasks with `<verify>` tags, the phase isolation sub-agent runs **targeted verification immediately after each task completes**. If verification fails, a nested debug sub-agent diagnoses the failure and the implementation sub-agent applies repairs. This catches errors at the task level instead of waiting for the final build+test step.
+
+**Core principle**: Verify early, diagnose fast, repair in place.
+
+---
+
+## Architecture
+
+```
+Phase Sub-Agent (isolated)
+    │
+    ├─ Task 1: Implement
+    │   ├─ Complete task implementation
+    │   ├─ Parse <verify> tag → extract command
+    │   ├─ Run verification command
+    │   ├─ ✅ Pass → record result, move to Task 2
+    │   └─ ❌ Fail → enter verification loop:
+    │       │
+    │       ├─ Spawn debug sub-agent (haiku):
+    │       │   Input: error output + task context + file content
+    │       │   Output: JSON diagnosis (root cause, repair actions)
+    │       │
+    │       ├─ Apply repair actions
+    │       ├─ Re-run verification command
+    │       ├─ ✅ Pass → record result (with repair info), move to Task 2
+    │       ├─ ❌ Fail → retry (up to max_verify_retries)
+    │       └─ ❌ Max retries exceeded → record failure, escalate to user
+    │
+    ├─ Task 2: Implement (no <verify> tag → skip verification)
+    │
+    ├─ Task 3: Implement
+    │   ├─ Complete task implementation
+    │   ├─ Parse <verify> tag → extract command
+    │   └─ Run verification → ✅ Pass
+    │
+    └─ Return JSON (includes task_verifications array)
+```
+
+Verification is **internal to the phase sub-agent**. The wave coordinator and main session see only the final JSON return with verification results — they never interact with the verification loop directly.
+
+---
+
+## Verify Tag Syntax
+
+### Declaration in Plans
+
+Tasks in a plan phase can include an optional `<verify>` tag indented under the task:
+
+```markdown
+### Phase 2: API Integration
+
+**Scope**: ...
+**Complexity**: 5/10
+**Dependencies**: Phase 1
+
+- [ ] Create user authentication middleware in `src/middleware/auth.ts`
+  <verify>npx tsc --noEmit src/middleware/auth.ts</verify>
+- [ ] Add rate limiting to API routes
+  <verify>npx jest src/middleware/__tests__/rate-limit.test.ts --no-coverage</verify>
+- [ ] Update configuration constants
+```
+
+### Parsing Rules
+
+1. **Tag format**: `<verify>COMMAND</verify>` on a single line, indented under a task
+2. **One verify per task**: Only the first `<verify>` tag under a task is used; additional tags are ignored
+3. **Command content**: The text between tags is executed as a shell command by the sub-agent
+4. **No verify = no verification**: Tasks without `<verify>` tags skip verification entirely (backward compatible)
+5. **Whitespace**: Leading/trailing whitespace inside the tag is trimmed
+6. **Nesting**: The `<verify>` tag must be indented under its parent task (2+ spaces or 1+ tab)
+
+### Recommended Verification Commands
+
+| Task Type | Verify Command | Purpose |
+|-----------|---------------|---------|
+| File creation (TypeScript) | `npx tsc --noEmit <file>` | Type-check the new file |
+| Test writing | `npx jest <test-file> --no-coverage` | Run the specific test |
+| Schema/type changes | `npx tsc --noEmit <type-file>` | Verify type consistency |
+| Config changes | *(no verify)* | Manual review preferred |
+| Documentation | *(no verify)* | No automated check available |
+
+**Constraint**: Verification commands must be **targeted** (single file or small scope). Never use full builds (`npm run build`) or full test suites (`npm test`) as verify commands — those run in the final Step 7.
+
+---
+
+## Debug Sub-Agent
+
+### When to Spawn
+
+A debug sub-agent is spawned when a verification command returns a **non-zero exit code**. The sub-agent diagnoses the failure and suggests repair actions.
+
+### Prompt Template
+
+```markdown
+# Debug Diagnosis
+
+## Failed Verification
+**Task**: {task description}
+**Command**: {verify command}
+**Exit Code**: {exit code}
+
+## Error Output
+```
+{stderr + stdout from the failed command, truncated to 200 lines}
+```
+
+## Task Context
+**File**: {primary file being modified}
+**Phase**: {phase name}
+**What was implemented**: {brief description of what the task did}
+
+## File Content
+```
+{content of the primary file, truncated to 300 lines}
+```
+
+## Instructions
+Analyze the error output and diagnose the root cause. Return a JSON object with your diagnosis and suggested repair actions. Do NOT fix the code — only diagnose.
+
+Return ONLY a JSON object (no markdown fences):
+{see Debug Return Schema below}
+```
+
+### Debug Return Schema
+
+```json
+{
+  "root_cause": "Missing import for AuthMiddleware type used on line 15",
+  "category": "import_missing",
+  "repair_actions": [
+    "Add import { AuthMiddleware } from '../types/auth' to src/middleware/auth.ts"
+  ],
+  "confidence": "high",
+  "file_to_fix": "src/middleware/auth.ts"
+}
+```
+
+### Field Descriptions
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `root_cause` | string | Yes | Human-readable description of what went wrong |
+| `category` | string | Yes | Error category: `import_missing`, `type_error`, `syntax_error`, `runtime_error`, `test_failure`, `config_error`, `other` |
+| `repair_actions` | string[] | Yes | Ordered list of specific actions to fix the issue |
+| `confidence` | `"high" \| "medium" \| "low"` | Yes | How confident the diagnosis is |
+| `file_to_fix` | string | Yes | Primary file that needs modification |
+
+### Sub-Agent Configuration
+
+- **Model**: Always uses haiku (fast tier) — diagnosis is a focused, low-complexity task
+- **Mode**: `"auto"`
+- **Read-only**: The debug sub-agent does NOT modify files — it only returns a diagnosis. The implementation sub-agent applies the repairs.
+
+---
+
+## Verification Loop
+
+### Flow
+
+```
+1. Complete task implementation
+2. Parse <verify> tag → extract command
+3. Run command
+4. If exit code == 0 → PASS (record result, continue)
+5. If exit code != 0:
+   a. Increment retry counter
+   b. If retry counter > max_verify_retries → ESCALATE (record failure)
+   c. Spawn debug sub-agent with error context
+   d. Receive JSON diagnosis
+   e. Apply repair actions from diagnosis
+   f. Re-run verification command → go to step 4
+```
+
+### Retry Behavior
+
+- **Retry counter**: Starts at 0, increments on each failed verification attempt
+- **First attempt**: The initial verification run does NOT count as a retry
+- **Max retries**: Controlled by `max_verify_retries` in `.flowconfig` (default: 2)
+- **Example with default**: Initial attempt + 2 retries = 3 total verification runs maximum
+
+### Escalation on Max Retries
+
+When max retries are exceeded, the sub-agent:
+
+1. Records the verification failure in the `task_verifications` array
+2. Includes the last debug diagnosis in the failure record
+3. Continues to the next task (does NOT abort the phase)
+4. Sets overall phase `status` to `"partial"` if any task verification failed
+
+The coordinator presents the failure to the user with the accumulated diagnosis:
+
+```markdown
+⚠️ Task verification failed after 2 retries:
+
+**Task**: Create user authentication middleware in `src/middleware/auth.ts`
+**Command**: `npx tsc --noEmit src/middleware/auth.ts`
+**Last diagnosis**: Missing type export from @auth/core — dependency may need updating
+**Category**: import_missing
+
+Options:
+1. Continue with remaining phases (issue noted)
+2. Stop and fix manually
+```
+
+---
+
+## Task Verifications Return Field
+
+### Schema Extension
+
+The phase isolation JSON return format is extended with an optional `task_verifications` array:
+
+```json
+{
+  "status": "success",
+  "phase": "Phase 2: API Integration",
+  "summary": "Implemented auth middleware and rate limiting. One task required type import repair.",
+  "files_created": ["src/middleware/auth.ts"],
+  "files_modified": ["src/api/routes.ts"],
+  "decisions": [],
+  "deviations": [],
+  "errors": [],
+  "patterns_captured": [],
+  "task_verifications": [
+    {
+      "task": "Create user authentication middleware",
+      "verify_command": "npx tsc --noEmit src/middleware/auth.ts",
+      "status": "pass",
+      "attempts": 2,
+      "repairs_applied": [
+        "Added missing import for AuthMiddleware type"
+      ]
+    },
+    {
+      "task": "Add rate limiting to API routes",
+      "verify_command": "npx jest src/middleware/__tests__/rate-limit.test.ts --no-coverage",
+      "status": "pass",
+      "attempts": 1,
+      "repairs_applied": []
+    }
+  ]
+}
+```
+
+### Task Verification Entry Fields
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `task` | string | Yes | Short description of the task (from plan) |
+| `verify_command` | string | Yes | The verification command that was run |
+| `status` | `"pass" \| "fail"` | Yes | Final verification outcome |
+| `attempts` | number | Yes | Total verification attempts (1 = passed first try) |
+| `repairs_applied` | string[] | Yes | List of repairs applied during retries (empty if passed first try) |
+| `last_diagnosis` | object | No | Last debug sub-agent diagnosis (only present when `status: "fail"`) |
+
+### When `task_verifications` is Omitted
+
+- If a phase has **no tasks with `<verify>` tags**, the `task_verifications` field is omitted entirely from the JSON return
+- This maintains backward compatibility — existing phase isolation returns are unchanged
+
+---
+
+## Configuration
+
+### `.flowconfig` Setting
+
+```yaml
+max_verify_retries: 2    # Max repair attempts per task verification (default: 2, range: 1-5)
+```
+
+- **Default**: `2` (initial attempt + 2 retries = 3 total runs)
+- **Range**: `1` to `5`
+- **Values below 1 or above 5**: Clamped to the valid range with a warning
+
+### Toggle via `/flow`
+
+```
+/flow max_verify_retries=3
+```
+
+### No Feature Toggle
+
+Per-task verification has no on/off toggle. It activates automatically when tasks include `<verify>` tags. Plans without `<verify>` tags behave exactly as before — fully backward compatible.
+
+---
+
+## Error Handling
+
+### Verification Command Errors
+
+| Scenario | Behavior |
+|----------|----------|
+| Command not found | Treat as verification failure, spawn debug sub-agent |
+| Command timeout (>30s) | Kill process, treat as failure, include timeout in error output |
+| Command produces no output | Treat exit code as sole indicator (0 = pass, non-zero = fail) |
+| Command produces large output | Truncate to 200 lines before passing to debug sub-agent |
+
+### Debug Sub-Agent Errors
+
+| Scenario | Behavior |
+|----------|----------|
+| Invalid JSON return | Skip this retry, count as failed attempt |
+| Sub-agent timeout | Skip this retry, count as failed attempt |
+| Empty repair_actions | Skip repair, re-run verification (may pass if issue was transient) |
+
+### Phase-Level Impact
+
+| Verification Outcome | Phase Status |
+|----------------------|-------------|
+| All verifications pass | `"success"` (no change) |
+| Some verifications fail (max retries exceeded) | `"partial"` |
+| Task implementation itself fails | `"failure"` (existing behavior, unrelated to verification) |
+
+---
+
+## Interaction with Wave Mode
+
+Per-task verification is **entirely internal** to each phase sub-agent. The wave coordinator:
+
+- Does NOT know about individual task verifications during execution
+- Receives `task_verifications` in the JSON return after the sub-agent completes
+- Displays verification stats in the wave completion summary
+- Does NOT retry phases based on verification failures (that is internal to the sub-agent)
+
+```
+Wave 1: Phase 1 (2 tasks verified: 2 pass), Phase 2 (3 tasks verified: 2 pass, 1 fail after 2 retries)
+```
+
+Wave execution treats a phase with failed verifications as `"partial"` — the same way it handles any partial result. The user decides whether to continue.
+
+---
+
+## Rules
+
+1. **Verify is optional** — tasks without `<verify>` tags skip verification entirely
+2. **Targeted commands only** — never use full builds or full test suites as verify commands
+3. **Debug sub-agent is read-only** — it diagnoses but never modifies files
+4. **Implementation sub-agent repairs** — only the phase sub-agent applies fixes
+5. **Continue on failure** — failed verification does NOT abort the phase; it records the failure and continues to the next task
+6. **Max retries are hard** — once exceeded, escalate to user; never increase retries dynamically
+7. **First attempt is not a retry** — the initial verification run is attempt 1, retries start at attempt 2
+8. **Truncate large output** — cap error output at 200 lines and file content at 300 lines for debug sub-agent
+9. **Backward compatible** — phases without any `<verify>` tags produce no `task_verifications` field
+10. **Wave-transparent** — wave coordinator sees only final results; verification loops are internal to phase sub-agents
+
+---
+
+## Related Files
+
+| File | Purpose |
+|------|---------|
+| `.claude/resources/core/phase-isolation.md` | Sub-agent context template and JSON return format (extended by this feature) |
+| `.claude/resources/core/wave-execution.md` | Wave coordinator behavior (verification is internal to sub-agents) |
+| `.claude/resources/core/model-routing.md` | Model tier selection (debug sub-agent always uses haiku) |
+| `.claude/resources/skills/execute-plan-skill.md` | Execute-plan skill with verification result display |
+| `.claude/resources/skills/create-plan-skill.md` | Auto-generation of `<verify>` sections in plans |
+| `.claude/resources/patterns/plans-templates.md` | Plan template with `<verify>` tag syntax |

package/.claude/resources/core/phase-isolation.md

@@ -7,10 +7,16 @@ When `phase_isolation: true` in `flow/.flowconfig` (default), each `/execute-pla
 
 **Core principle**: Clean context in, structured summary out.
 
+### Per-Task Verification
+
+Phase sub-agents support **per-task verification** when plan tasks include `<verify>` tags. After completing each task, the sub-agent runs the verification command and, on failure, spawns a debug sub-agent (haiku) for diagnosis and repair. See `.claude/resources/core/per-task-verification.md` for the complete verification system, debug sub-agent prompt template, JSON schemas, and configuration.
+
 ---
 
 ## Architecture
 
+### Sequential Mode (default)
+
 ```
 Coordinator (main session)
     │
@@ -35,6 +41,40 @@ Coordinator (main session)
     └─ Next phase...
 ```
 
+### Wave Mode (when `wave_execution: true`)
+
+```
+Coordinator (main session)
+    │
+    ├─ For each Wave:
+    │   │
+    │   ├─ Approve each phase sequentially in Plan Mode
+    │   │
+    │   ├─ Prepare isolated context for EACH phase in the wave
+    │   │
+    │   ├─ Spawn MULTIPLE Agent sub-agents IN PARALLEL:
+    │   │   ├─► Agent: Phase A  (model: [tier_A], prompt: phase_A_context)
+    │   │   ├─► Agent: Phase B  (model: [tier_B], prompt: phase_B_context)
+    │   │   └─► Agent: Phase C  (model: [tier_C], prompt: phase_C_context)
+    │   │
+    │   ├─ Wait for ALL sub-agents to complete
+    │   │
+    │   ├─ Collect JSON returns from all sub-agents
+    │   │
+    │   ├─ Post-wave processing (sequential, in phase order):
+    │   │   ├─ Detect file conflicts (files_modified overlap)
+    │   │   ├─ Process each phase result
+    │   │   ├─ Update plan file (mark tasks [x])
+    │   │   ├─ Accumulate files_modified list
+    │   │   ├─ Buffer patterns from all phases
+    │   │   ├─ Git commit sequentially (Phase A, then B, then C)
+    │   │   └─ Handle failures (present to user)
+    │   │
+    │   └─ Next Wave...
+    │
+    └─ Completion summary with wave execution stats
+```
+
 Planning and user approval always happen in the **main session** (full context). Only the **implementation step** is isolated.
 
 ---
@@ -68,11 +108,37 @@ Read these files before implementing:
 {Only if UI phase — include design tokens from discovery doc}
 {Otherwise omit this section entirely}
 
+## Commit Instructions
+{Only include this section when `commit: true` in `.flowconfig`}
+
+### Sequential Mode (wave_execution: false)
+- After each task completes and verification passes (if applicable):
+  1. Stage changed files: `git add -A`
+  2. Create atomic commit: `git commit -m "feat(phase-N.task-M): <truncated description> — <feature>"`
+     - Use format: feat(phase-{phase_number}.task-{task_number_in_phase}): <description> — <feature>
+     - Truncate description to 50 chars (use ellipsis if truncated)
+     - Task numbers are 1-indexed within each phase
+  3. Continue to next task
+- Return `tasks_completed` array in JSON with files_created/files_modified per task
+- Do NOT create a final phase commit (coordinator will not create one either)
+
+### Wave Mode (wave_execution: true)
+- Do NOT create any commits during task implementation
+- The coordinator will commit your changes after this wave completes
+- Return `tasks_completed` array with per-task file lists (see Return Format below)
+- Coordinator will iterate tasks and commit: feat(phase-N.task-M): ... per task
+
 ## Instructions
 1. Read the plan file to understand the full feature context
 2. Implement all tasks listed above
 3. Follow the project patterns from the files listed
-4. Return a JSON summary in the exact format below — do NOT return markdown
+4. After completing each task, check if it has a `<verify>` tag indented beneath it:
+   - If yes: run the verification command inside the tag
+   - If the command exits 0: record a pass result and continue to the next task
+   - If the command exits non-zero: spawn a debug sub-agent (haiku, mode: "auto") with the error output, task context, and file content. Apply the repair actions from the diagnosis and re-run the verification command (up to `max_verify_retries` attempts, default 2). See `.claude/resources/core/per-task-verification.md` for the debug sub-agent prompt template and return schema.
+   - If max retries exceeded: record a fail result and continue to the next task (do NOT abort)
+   - If no `<verify>` tag: skip verification for that task
+5. Return a JSON summary in the exact format below — do NOT return markdown
 
 ## Return Format
 Return ONLY a JSON object (no markdown fences, no explanation):
@@ -83,6 +149,14 @@ Return ONLY a JSON object (no markdown fences, no explanation):
 
 The prompt should be **under 2K tokens** (excluding files the sub-agent reads itself via the Read tool). Keep it focused — the sub-agent will read project files as needed during implementation.
 
+### Wave Mode Context Additions
+
+When spawning sub-agents within a wave, the context template is **identical** to sequential mode with one key difference:
+
+- **`Files Modified in Previous Phases`**: Include files from ALL completed waves (Wave 1 through Wave N-1), not just the immediately preceding phase. This gives each sub-agent awareness of everything that changed before the current wave.
+
+Sub-agents within the same wave do NOT receive information about each other — no cross-phase awareness. Each sub-agent operates as if it is the only phase running.
+
 ---
 
 ## Return Format Schema
@@ -115,6 +189,38 @@ The sub-agent must return a JSON object with this structure:
       "description": "All Zod schemas live next to their type definitions",
       "confidence": "high"
     }
+  ],
+  "task_verifications": [
+    {
+      "task": "Create user authentication middleware",
+      "verify_command": "npx tsc --noEmit src/middleware/auth.ts",
+      "status": "pass",
+      "attempts": 2,
+      "repairs_applied": [
+        "Added missing import for AuthMiddleware type"
+      ]
+    },
+    {
+      "task": "Add rate limiting to API routes",
+      "verify_command": "npx jest src/middleware/__tests__/rate-limit.test.ts --no-coverage",
+      "status": "pass",
+      "attempts": 1,
+      "repairs_applied": []
+    }
+  ],
+  "tasks_completed": [
+    {
+      "task_number": 1,
+      "task_name": "Create user authentication middleware",
+      "files_created": ["src/middleware/auth.ts"],
+      "files_modified": []
+    },
+    {
+      "task_number": 2,
+      "task_name": "Add rate limiting to API routes",
+      "files_created": ["src/middleware/rate-limit.ts"],
+      "files_modified": ["src/api/routes.ts"]
+    }
   ]
 }
 ```
@@ -132,6 +238,8 @@ The sub-agent must return a JSON object with this structure:
 | `deviations` | string[] | No | Tasks skipped or changed from plan |
 | `errors` | string[] | No | Errors encountered (even if resolved) |
 | `patterns_captured` | object[] | No | Patterns observed during implementation |
+| `task_verifications` | object[] | No | Array of per-task verification results. Only present when at least one task had a `<verify>` tag. Each entry contains: `task` (string), `verify_command` (string), `status` (`"pass" \| "fail"`), `attempts` (number), `repairs_applied` (string[]), and optionally `last_diagnosis` (object, only when status is `"fail"`). See `.claude/resources/core/per-task-verification.md` for full schema. |
+| `tasks_completed` | object[] | No | Array of per-task file tracking for atomic commits. Each entry: `task_number` (number, 1-indexed within phase), `task_name` (string), `files_created` (string[]), `files_modified` (string[]). Present when any tasks ran. Used by coordinator for per-task commit messages. See `.claude/resources/core/atomic-commits.md` for full schema. |
 
 ### Failure Return Example
 
@@ -163,9 +271,15 @@ After receiving the sub-agent's JSON summary, the coordinator:
 1. **Update plan file**: Mark all phase tasks as `[x]`
 2. **Accumulate file list**: Merge `files_created` and `files_modified` into running list
 3. **Buffer patterns**: Append `patterns_captured` entries to `flow/resources/pending-patterns.md`
-4. **Git commit**: If `commit: true`, run `git add -A && git commit -m "Phase N: {name} — {feature}"`
+4. **Git commit (per-task)**: If `commit: true` and `tasks_completed` is present:
+   - **Sequential mode**: Sub-agent already created per-task commits — verify they exist, do NOT create phase commit
+   - **Wave mode**: Coordinator iterates `tasks_completed` in task_number order and creates per-task commits:
+     - For each task: `git add -A && git commit -m "feat(phase-N.task-M): <truncated task_name> — <feature>"`
+     - Truncate `task_name` to 50 chars if needed
+   - **Fallback**: If `tasks_completed` is absent (legacy sub-agent), fall back to single phase commit: `git add -A && git commit -m "Phase N: {name} — {feature}"`
 5. **Log decisions**: Include `decisions` in phase completion message
-6. **Proceed**: Move to next phase
+6. **Display verification results**: If `task_verifications` is present, show pass/fail counts and any repairs applied
+7. **Proceed**: Move to next phase
 
 ### On Failure (`status: "failure"`)
 
@@ -178,7 +292,49 @@ After receiving the sub-agent's JSON summary, the coordinator:
 
 1. **Present summary**: Show what was completed and what wasn't
 2. **Show deviations**: List `deviations` explaining what was skipped
-3. **Ask user**: "Phase partially complete. Continue to next phase or retry remaining tasks?"
+3. **Display verification failures**: If `task_verifications` contains failed entries, show task name, last diagnosis, and repair attempts
+4. **Ask user**: "Phase partially complete. Continue to next phase or retry remaining tasks?"
+
+---
+
+## Wave Coordinator Processing
+
+When multiple sub-agents return simultaneously from a wave, the coordinator handles them differently from sequential mode. See `.claude/resources/core/wave-execution.md` for the full wave system and `.claude/resources/skills/execute-plan-skill.md` Step 4c for the detailed processing flow.
+
+**Per-task commits in wave mode**: After collecting all JSON returns from a wave, the coordinator commits per-task (not per-phase). For each phase in phase-number order, iterate `tasks_completed` and create atomic commits: `feat(phase-N.task-M): <desc> — <feature>`. See `.claude/resources/core/atomic-commits.md` for the complete commit format and coordinator processing rules.
+
+### Collecting Multiple JSON Returns
+
+After all sub-agents in a wave complete, the coordinator collects all JSON returns before processing any of them. This allows file conflict detection before committing.
+
+### Processing Order
+
+Results are always processed **sequentially in phase number order**, regardless of which sub-agent finished first. This ensures:
+- Deterministic commit history (Phase A committed before Phase B)
+- Predictable plan file updates
+- Consistent file accumulation order
+
+### File Conflict Detection
+
+After collecting all wave results, check for `files_modified` overlap between phases:
+
+```
+For each pair of phases (A, B) in the wave:
+  overlap = A.files_modified ∩ B.files_modified
+  if overlap is not empty:
+    → File conflict detected
+```
+
+**On conflict**: Present to user with options (accept as-is, re-run conflicting phases sequentially, or stop). Never silently resolve conflicts.
+
+### Wave Failure Isolation
+
+A failed phase in a wave does NOT affect other phases in the same wave:
+- Successful phases are processed normally (plan updates, file accumulation, git commits)
+- Failed phases are presented to the user after all successful phases are processed
+- The user chooses per failed phase: retry, skip, or stop
+
+This differs from sequential mode where a failure immediately pauses execution. In wave mode, all parallel phases complete independently before any failure handling.
 
 ---
 
@@ -186,6 +342,8 @@ After receiving the sub-agent's JSON summary, the coordinator:
 
 When phases are aggregated (combined complexity ≤ 6), they run as **one sub-agent call** with all tasks from all aggregated phases. The context template lists all phases and tasks together. The return uses the highest phase number as the `phase` field.
 
+In wave mode, aggregated phases within the same wave are treated as a **single unit** — they share one wave slot, one dependency set (union of all aggregated phases' dependencies), and one sub-agent call.
+
 ---
 
 ## Configuration
@@ -210,6 +368,19 @@ Phase isolation **enhances** model routing — it doesn't replace it:
 | `model_routing: false` + `phase_isolation: true` | Sub-agent spawned with session model, clean context |
 | `model_routing: false` + `phase_isolation: false` | Inline execution, no sub-agents (original behavior) |
 
+### Interaction with Wave Execution
+
+Phase isolation is the **foundation** for wave execution — wave mode spawns multiple isolated sub-agents per wave instead of one at a time:
+
+| Setting | Behavior |
+|---------|----------|
+| `wave_execution: true` + `phase_isolation: true` | Multiple sub-agents per wave, each with clean context (optimal) |
+| `wave_execution: true` + `phase_isolation: false` | Multiple sub-agents per wave, but sharing session context (may cause interference) |
+| `wave_execution: false` + `phase_isolation: true` | One sub-agent at a time, clean context (existing behavior) |
+| `wave_execution: false` + `phase_isolation: false` | Inline execution, no sub-agents (original behavior) |
+
+**Recommendation**: `wave_execution: true` works best with `phase_isolation: true`. Without phase isolation, parallel sub-agents may interfere with each other's context.
+
 ---
 
 ## Rules
@@ -220,3 +391,20 @@ Phase isolation **enhances** model routing — it doesn't replace it:
 4. **Coordinator validates** — check status field before proceeding
 5. **Never auto-retry** — on failure, present to user and ask
 6. **Pass paths, not content** — give file paths, sub-agent reads them
+7. **Each phase gets own sub-agent** — even in wave mode, phases are never merged into one sub-agent (except for aggregated phases per complexity rules)
+8. **No cross-wave awareness** — sub-agents in the same wave know nothing about each other
+9. **Deterministic processing** — wave results are always processed in phase number order
+10. **Collect before commit** — in wave mode, all JSON returns are collected before any commits happen
+11. **Verification is internal** — per-task verification loops run inside the phase sub-agent; the coordinator sees only the final `task_verifications` results
+
+---
+
+## Related Files
+
+| File | Purpose |
+|------|---------|
+| `.claude/resources/core/wave-execution.md` | Full wave-based parallel execution system |
+| `.claude/resources/core/model-routing.md` | Model tier selection per phase complexity |
+| `.claude/resources/core/discovery-sub-agents.md` | Parallel spawning pattern reference |
+| `.claude/resources/core/per-task-verification.md` | Per-task verification system, debug sub-agent, and repair loops |
+| `.claude/resources/skills/execute-plan-skill.md` | Execute-plan skill with wave integration (Steps 2b, 3, 4) |

package/.claude/resources/core/session-scratchpad.md

@@ -103,3 +103,4 @@ After compaction, the model should re-read `flow/.scratchpad.md` to restore any
 3. **Self-manage size** — promote or discard when approaching 50 lines
 4. **Promote before ending** — always scan for promotable items before session ends
 5. **Not a task list** — use `flow/tasklist.md` for tasks, scratchpad is for observations
+6. **Different from STATE.md** — `flow/STATE.md` tracks structured execution position (current skill, phase, status) for session resumability. The scratchpad tracks informal observations, insights, and open questions. They coexist and serve different purposes: STATE.md is machine-readable execution state, scratchpad is human-readable notes.