planflow-ai 1.4.1 → 1.4.4

package/.claude/commands/review-pr.md

@@ -120,60 +120,17 @@ review-pr https://github.com/org/repo/pull/123
 review-pr https://dev.azure.com/org/project/_git/repo/pullrequest/456
 ```
 
----
+## Context Loading
+
+This command uses the **brain index** for context retrieval. Before executing, query the project brain for relevant documentation:
+
+**Queries**:
+- `planflow-ai state-query "PR review workflow" --scope resources`
+- `planflow-ai state-query "adaptive depth" --scope resources`
+- `planflow-ai state-query "severity ranking" --scope resources`
+- `planflow-ai state-query "PR authentication" --scope resources`
 
-## Context Optimization
-
-This command uses hierarchical context loading to reduce context consumption. Instead of loading full files, load indexes first and expand specific sections on-demand.
-
-### Recommended Loading Order
-
-1. **Always load first**: This command file (`commands/review-pr.md`)
-2. **Load indexes**: Load `_index.md` files for relevant folders
-3. **Expand on-demand**: Use reference codes to load specific sections when needed
-
-### Index Files for PR Review
-
-| Index | When to Load |
-|-------|--------------|
-| `resources/skills/_index.md` | To understand review workflow |
-| `resources/tools/_index.md` | For authentication tool |
-| `resources/patterns/_index.md` | For review patterns |
-| `resources/core/_index.md` | For allowed/forbidden patterns |
-
-### Reference Codes for PR Review
-
-| Code | Description | When to Expand |
-|------|-------------|----------------|
-| SKL-PR-1 | Purpose and restrictions | Understanding allowed actions |
-| SKL-PR-2 | Authenticate for PR access | Setting up authentication |
-| SKL-PR-3 | Fetch PR info + determine depth | Getting PR data and review mode |
-| SKL-PR-5 | Analyze + verify + re-rank | Processing findings |
-| SKL-PR-6 | Generate review document | Creating the output file |
-| SKL-PR-7 | Output template | Review document structure |
-| SKL-PR-8 | Fix complexity scoring | Severity and complexity details |
-| SKL-PR-9 | Link format (GitHub/Azure DevOps) | Platform-specific link formats |
-| TLS-AUTH-1 | Auth tool configuration | Setting up authentication |
-| TLS-AUTH-2 | Authentication workflow | Authenticating to platform |
-| PTN-PR-1 | PR review patterns | Creating review output |
-| COR-AP-1 | Allowed patterns overview | Checking pattern compliance |
-| COR-FP-1 | Forbidden patterns overview | Identifying anti-patterns |
-| COR-MA-1 | Multi-agent subagent definitions | Deep mode parallel review setup |
-| COR-MA-2 | Coordinator dedup and merge | Deep mode result processing |
-| COR-SR-1 | Severity re-ranking algorithm | Ordering findings by impact |
-| COR-SR-2 | Finding grouping rules | Grouping related findings |
-| COR-AD-1 | Adaptive depth size detection | Determining review mode |
-| COR-AD-2 | Lightweight review mode | Changeset < 50 lines |
-| COR-AD-3 | Deep review mode | Changeset 500+ lines |
-
-### Expansion Instructions
-
-When executing this command:
-
-1. **Start with indexes**: Read `resources/skills/_index.md` and `resources/tools/_index.md`
-2. **Expand auth first**: Load TLS-AUTH-* codes for authentication
-3. **Then expand review patterns**: Load PTN-PR-* codes for review structure
-4. **Don't expand everything**: Only load patterns relevant to the PR being reviewed
+The brain returns ranked chunks from indexed markdown files. Use the top results to inform execution.
 
 ---
 
@@ -181,10 +138,6 @@ When executing this command:
 
 | Resource                       | Purpose                                |
 | ------------------------------ | -------------------------------------- |
-| `resources/skills/_index.md`      | Index of skills with reference codes   |
-| `resources/tools/_index.md`       | Index of tools with reference codes    |
-| `resources/patterns/_index.md`    | Index of patterns with reference codes |
-| `resources/core/_index.md`        | Index of core rules with reference codes |
 | `review-pr-skill.md`          | Skill that executes the review         |
 | `auth-pr-tool.md`             | Authentication tool for PR platforms   |
 | `review-pr-patterns.md`       | Review patterns and guidelines         |

package/.claude/commands/setup.md

@@ -648,59 +648,15 @@ flow/
    - Component structure
    - Error handling approach
 
----
+## Context Loading
+
+This command uses the **brain index** for context retrieval. Before executing, query the project brain for relevant documentation:
+
+**Queries**:
+- `planflow-ai state-query "project setup" --scope resources`
+- `planflow-ai state-query "pattern generation" --scope resources`
 
-## Context Optimization
-
-This command uses hierarchical context loading to reduce context consumption. Instead of loading full files, load indexes first and expand specific sections on-demand.
-
-### Recommended Loading Order
-
-1. **Always load first**: This command file (`commands/setup.md`)
-2. **Load indexes**: Load `_index.md` files for relevant folders
-3. **Expand on-demand**: Use reference codes to load specific sections when needed
-
-### Index Files for Setup
-
-| Index | When to Load |
-|-------|--------------|
-| `resources/skills/_index.md` | To understand setup workflow |
-| `resources/tools/_index.md` | For interactive questions tool |
-| `resources/core/_index.md` | For pattern references |
-| `resources/languages/_index.md` | For language-specific patterns |
-
-### Reference Codes for Setup
-
-| Code | Description | When to Expand |
-|------|-------------|----------------|
-| SKL-SETUP-1 | Purpose and critical approach | Understanding setup goals |
-| SKL-SETUP-2 | Scan project structure | Scanning files and directories |
-| SKL-SETUP-3 | Deep dependency analysis | Analyzing package dependencies |
-| SKL-SETUP-4 | Deep code analysis | Sampling files and extracting patterns |
-| SKL-SETUP-7 | Ask confirming questions | Presenting questions via Plan mode |
-| SKL-SETUP-8 | Generate pattern files | Creating framework/library pattern files |
-| SKL-SETUP-9 | Update core pattern files | Updating allowed/forbidden patterns |
-| SKL-SETUP-11 | Create analysis document | Generating project analysis doc |
-| SKL-SETUP-12 | Index documentation | Indexing project docs with reference codes |
-| SKL-SETUP-13 | Create flow folder | Setting up flow/ directory structure |
-| SKL-SETUP-14 | Present summary | Final setup summary output |
-| TLS-IQ-1 | Interactive questions overview | Before asking questions |
-| TLS-IQ-2 | Switch to Plan mode | Starting question session |
-| TLS-IQ-3 | Ask questions format | Asking confirmation questions |
-| COR-AP-1 | Allowed patterns structure | Updating allowed patterns |
-| COR-FP-1 | Forbidden patterns structure | Updating forbidden patterns |
-| LNG-TS-1 | TypeScript patterns | If TS project detected |
-| LNG-PY-1 | Python patterns | If Python project detected |
-
-### Expansion Instructions
-
-When executing this command:
-
-1. **Start with indexes**: Read `resources/skills/_index.md` and `resources/tools/_index.md`
-2. **Expand for detection phase**: Load minimal context during code analysis
-3. **Expand for questions**: Load TLS-IQ-* before asking confirmation questions
-4. **Expand for generation**: Load relevant language patterns when generating files
-5. **Don't expand everything**: Only load patterns relevant to detected stack
+The brain returns ranked chunks from indexed markdown files. Use the top results to inform execution.
 
 ---
 
@@ -708,10 +664,6 @@ When executing this command:
 
 | Resource                       | Purpose                                |
 | ------------------------------ | -------------------------------------- |
-| `resources/skills/_index.md`      | Index of skills with reference codes   |
-| `resources/tools/_index.md`       | Index of tools with reference codes    |
-| `resources/core/_index.md`        | Index of core rules with reference codes |
-| `resources/languages/_index.md`   | Index of language patterns with reference codes |
 | `setup-skill.md`              | Detailed execution logic               |
 | `interactive-questions-tool.md` | Questions UI for confirmations       |
 | `allowed-patterns.md`         | Core allowed patterns                  |

package/.claude/commands/write-tests.md

@@ -199,47 +199,16 @@ All metrics (Lines, Branches, Functions, Statements) meet the target.
 3. Invoke write-tests skill
 4. Present final coverage summary
 
----
-
-## Context Optimization
-
-This command uses hierarchical context loading to reduce context consumption. Instead of loading full files, load indexes first and expand specific sections on-demand.
-
-### Recommended Loading Order
-
-1. **Always load first**: This command file (`commands/write-tests.md`)
-2. **Load indexes**: Load `_index.md` files for relevant folders
-3. **Expand on-demand**: Use reference codes to load specific sections when needed
-
-### Index Files for Writing Tests
-
-| Index | When to Load |
-|-------|--------------|
-| `resources/skills/_index.md` | To understand test writing workflow |
-| `resources/patterns/_index.md` | For testing patterns |
-| `resources/tools/_index.md` | For testing tool commands |
-
-### Reference Codes for Writing Tests
-
-| Code | Description | When to Expand |
-|------|-------------|----------------|
-| SKL-TEST-1 | Write tests skill workflow | Understanding full process |
-| PTN-JEST-1 | Jest test structure | Writing Jest tests |
-| PTN-JEST-2 | Jest mocking patterns | When mocking is needed |
-| PTN-PYTEST-1 | Pytest test structure | Writing Pytest tests |
-| PTN-PYTEST-2 | Pytest fixtures | When fixtures are needed |
-| TLS-JEST-1 | Jest commands | Running Jest tests |
-| TLS-PYTEST-1 | Pytest commands | Running Pytest tests |
+## Context Loading
 
-### Expansion Instructions
+This command uses the **brain index** for context retrieval. Before executing, query the project brain for relevant documentation:
 
-When executing this command:
+**Queries**:
+- `planflow-ai state-query "test writing" --scope resources`
+- `planflow-ai state-query "jest patterns" --scope resources`
+- `planflow-ai state-query "pytest patterns" --scope resources`
 
-1. **Start with indexes**: Read `resources/skills/_index.md` and `resources/patterns/_index.md`
-2. **Detect framework first**: Determine Jest or Pytest before expanding patterns
-3. **Expand framework-specific**: Only load PTN-JEST-* or PTN-PYTEST-*, not both
-4. **Expand tool commands**: Load TLS-JEST-* or TLS-PYTEST-* for running tests
-5. **Don't expand everything**: Only load patterns relevant to detected framework
+The brain returns ranked chunks from indexed markdown files. Use the top results to inform execution.
 
 ---
 
@@ -247,9 +216,6 @@ When executing this command:
 
 | Resource                  | Purpose                         |
 | ------------------------- | ------------------------------- |
-| `resources/skills/_index.md` | Index of skills with reference codes |
-| `resources/patterns/_index.md` | Index of patterns with reference codes |
-| `resources/tools/_index.md`  | Index of tools with reference codes |
 | `write-tests-skill.md`   | Skill that writes the tests     |
 | `jest-patterns.md`       | Jest testing patterns           |
 | `pytest-patterns.md`     | Pytest testing patterns         |

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

@@ -108,6 +108,20 @@ Read these files before implementing:
 {Only if UI phase — include design tokens from discovery doc}
 {Otherwise omit this section entirely}
 
+## Shared Context from Sibling Phases
+
+{Only included for multi-phase waves. Omitted for single-phase waves and sequential execution.}
+
+The following contracts, decisions, and progress updates were emitted by other phases running in parallel with yours. Use these to inform your implementation:
+
+{Injected context entries as formatted text}
+
+**Instructions**:
+- Before each task, review shared context entries for relevant contracts or decisions
+- If a sibling phase defined an API endpoint you consume, match its signature exactly
+- If a sibling phase made an architectural decision, follow it for consistency
+- If you define a new API endpoint, type interface, or make an architectural decision, include it in your `context_entries` return array
+
 ## Commit Instructions
 {Only include this section when `commit: true` in `.flowconfig`}
 
@@ -157,6 +171,21 @@ When spawning sub-agents within a wave, the context template is **identical** to
 
 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.
 
+**Exception**: When shared context is available from sibling phases (via `.wave-context.jsonl`), the coordinator injects a "Shared Context from Sibling Phases" section into the context template. See below for details.
+
+### Shared Context Injection
+
+**When shared context is injected**:
+- Multi-phase waves only (2+ phases in the same wave)
+- Coordinator reads `.wave-context.jsonl` before spawning each sub-agent
+- Entries from OTHER phases in the wave are injected (not the agent's own)
+- Single-phase waves and sequential mode: section is omitted entirely
+
+**When to emit context entries**:
+- After implementing a task that creates or modifies an API endpoint, type interface, function signature, or makes an architectural decision
+- Include in the `context_entries` array of your JSON return
+- Format as ContextEntry objects (see `shared-context.md` COR-SC-2 for schema)
+
 ---
 
 ## Return Format Schema
@@ -221,6 +250,20 @@ The sub-agent must return a JSON object with this structure:
       "files_created": ["src/middleware/rate-limit.ts"],
       "files_modified": ["src/api/routes.ts"]
     }
+  ],
+  "context_entries": [
+    {
+      "agent": "phase-N",
+      "type": "contract",
+      "timestamp": "ISO8601",
+      "data": { "name": "GET /users", "kind": "endpoint", "signature": "GET /users → { id, name, email }", "fields": ["id", "name", "email"] }
+    },
+    {
+      "agent": "phase-N",
+      "type": "decision",
+      "timestamp": "ISO8601",
+      "data": { "choice": "Using Redis for session caching", "reason": "Low latency requirement" }
+    }
   ]
 }
 ```
@@ -240,6 +283,7 @@ The sub-agent must return a JSON object with this structure:
 | `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. |
+| `context_entries` | object[] | No | Array of context entries emitted by this phase for sibling phases. Each entry: `agent` (string, e.g. "phase-3"), `type` (`"contract" \| "decision" \| "progress"`), `timestamp` (ISO8601 string), `data` (object with type-specific fields). Only relevant in multi-phase waves. See `.claude/resources/core/shared-context.md` COR-SC-2 for full schema. |
 
 ### Failure Return Example
 
@@ -392,7 +436,7 @@ Phase isolation is the **foundation** for wave execution — wave mode spawns mu
 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
+8. **No cross-wave awareness** — sub-agents in the same wave know nothing about each other unless shared context entries are injected from `.wave-context.jsonl`
 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
@@ -407,4 +451,5 @@ Phase isolation is the **foundation** for wave execution — wave mode spawns mu
 | `.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/core/shared-context.md` | Shared context schema, JSONL format, and coordinator injection rules |
 | `.claude/resources/skills/execute-plan-skill.md` | Execute-plan skill with wave integration (Steps 2b, 3, 4) |

package/.claude/resources/core/shared-context.md

@@ -0,0 +1,110 @@
+# Shared Context System
+
+## COR-SC-1: Purpose
+
+Inter-agent communication during parallel wave execution via a shared JSONL context file. When multiple phases run in parallel (wave execution), each sub-agent may produce contracts, decisions, or progress updates that sibling agents need. The shared context file acts as the coordination bus.
+
+## COR-SC-2: Context Entry Types
+
+Each entry in the context file is a JSON object with these fields:
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `agent` | string | Phase identifier (e.g., `"phase-3"`) |
+| `type` | `'contract' \| 'decision' \| 'progress'` | Entry category |
+| `timestamp` | string | ISO-8601 timestamp |
+| `data` | object | Type-specific payload (see below) |
+
+### Contract Entries (`type: 'contract'`)
+
+Declare API shapes, interfaces, function signatures, or type definitions that other phases may depend on.
+
+```json
+{
+  "agent": "phase-2",
+  "type": "contract",
+  "timestamp": "2026-03-24T10:00:00.000Z",
+  "data": {
+    "name": "UserService.getById",
+    "kind": "function",
+    "signature": "(id: string) => Promise<User>",
+    "fields": ["id", "name", "email"]
+  }
+}
+```
+
+`data` fields for contracts:
+- `name` (required): Unique identifier for the contract
+- `kind` (required): One of `endpoint`, `interface`, `function`, `type`
+- `signature` (required): The type signature or shape
+- `fields` (optional): Array of field/property names
+
+### Decision Entries (`type: 'decision'`)
+
+Record architecture or implementation choices made during execution.
+
+```json
+{
+  "agent": "phase-3",
+  "type": "decision",
+  "timestamp": "2026-03-24T10:01:00.000Z",
+  "data": {
+    "choice": "Use Redis for session storage",
+    "reason": "Faster than DB lookups for frequent reads"
+  }
+}
+```
+
+### Progress Entries (`type: 'progress'`)
+
+Report task completion status within a phase.
+
+```json
+{
+  "agent": "phase-2",
+  "type": "progress",
+  "timestamp": "2026-03-24T10:02:00.000Z",
+  "data": {
+    "task": 1,
+    "status": "complete",
+    "summary": "Created UserService with CRUD operations"
+  }
+}
+```
+
+## COR-SC-3: File Format and Lifecycle
+
+**File**: `.wave-context.jsonl` inside the `flow/` directory. Append-only JSONL — one JSON object per line.
+
+**Lifecycle**:
+
+1. **Created** — at the start of each wave, an empty `.wave-context.jsonl` is created
+2. **Injected** — before spawning sub-agents (Step 4b), existing entries are read and passed as context
+3. **Appended** — sub-agents append entries during execution via atomic write (read, append, write-to-temp, rename)
+4. **Collected** — after sub-agents return (Step 4c), all entries are read and checked for conflicts
+5. **Cleared** — between waves, the file is deleted to start fresh for the next wave
+6. **Deleted** — after plan execution completes, the file is removed
+
+## COR-SC-4: Contract Conflict Detection
+
+A conflict exists when two or more entries share the same `name` but have different `signature` or `fields` values.
+
+**Detection rules**:
+- Filter entries to `type === 'contract'`
+- Group by `data.name`
+- For each group with 2+ entries: compare `signature` and `fields` (order-insensitive for fields)
+- If any pair within a group differs: flag as conflict
+
+**Resolution**: Present both conflicting versions to the user with the originating agent names. The user decides which version to keep or how to reconcile.
+
+## COR-SC-5: Integration Points and Backward Compatibility
+
+**Integration points**:
+- **Step 4b (inject)**: Read `.wave-context.jsonl`, pass entries array to sub-agent prompt
+- **Step 4c (collect)**: Parse `context_entries` from sub-agent return JSON, append to file, run conflict detection
+
+**Backward compatibility**:
+- Single-phase waves: context injection is skipped (no sibling data to share)
+- Sequential mode (`wave_execution: false`): shared context system is not used
+- `context_entries` field is optional in sub-agent return JSON — absence means no entries to contribute
+- Existing plans without wave execution are completely unaffected

package/.claude/resources/core/wave-execution.md

@@ -24,19 +24,24 @@ Coordinator (main session)
     │   │
     │   ├─ Sequential: Approve each phase in Plan Mode
     │   │
+    │   ├─ Create shared context file (flow/.wave-context.jsonl)
+    │   │
     │   ├─ Parallel: Spawn Agent sub-agents for all wave phases
     │   │   ├─► Agent: Phase A  (model: [tier from model routing])
     │   │   ├─► Agent: Phase B  (model: [tier from model routing])
     │   │   └─► Agent: Phase C  (model: [tier from model routing])
+    │   │   (agents read/append to .wave-context.jsonl during execution)
     │   │
     │   ├─ Collect JSON returns from all sub-agents
     │   │
     │   ├─ Post-wave processing:
     │   │   ├─ Detect file conflicts (files_modified overlap)
+    │   │   ├─ Detect contract conflicts (same name, different signatures)
     │   │   ├─ Accumulate files_modified list
     │   │   ├─ Buffer patterns from all phases
     │   │   ├─ Git commit per-task (iterate tasks within each phase, in phase order)
-    │   │   └─ Handle failures (present to user)
+    │   │   ├─ Handle failures (present to user)
+    │   │   └─ Delete .wave-context.jsonl (clean slate for next wave)
     │   │
     │   └─ Next Wave...
     │
@@ -47,6 +52,56 @@ Planning and user approval always happen **sequentially** in the main session. O
 
 ---
 
+## Shared Context
+
+### Overview
+
+During wave execution, parallel phases share a context file (`flow/.wave-context.jsonl`) that enables real-time coordination. Agents share API contracts, architectural decisions, and progress status via append-only JSONL entries. Before each task, sub-agents receive shared context from sibling phases, preventing broken contracts and duplicate decisions.
+
+### Lifecycle
+
+1. **Wave start**: Coordinator creates `flow/.wave-context.jsonl` (empty file) before spawning sub-agents
+2. **During execution**: Sub-agents append entries as they make decisions, define contracts, or complete tasks
+3. **Before each task**: Sub-agents read the shared context file to pick up entries from sibling phases
+4. **Wave end**: Coordinator reads the final context file for post-wave conflict detection
+5. **Cleanup**: Context file is deleted after the wave completes (each wave gets a fresh file)
+
+### Entry Format
+
+Each line in `.wave-context.jsonl` is a JSON object with one of three types:
+
+```jsonl
+{"type":"contract","phase":2,"task":1,"name":"UserAPI","signature":{"endpoint":"/api/users","method":"GET","response":"User[]"},"timestamp":"2024-01-15T10:30:00Z"}
+{"type":"decision","phase":1,"task":2,"name":"auth-strategy","value":"JWT with refresh tokens","reason":"Aligns with existing session management","timestamp":"2024-01-15T10:31:00Z"}
+{"type":"progress","phase":3,"task":1,"status":"complete","files_modified":["src/utils/helpers.ts"],"timestamp":"2024-01-15T10:32:00Z"}
+```
+
+| Type | Purpose | Key Fields |
+|------|---------|------------|
+| `contract` | API shapes, interfaces, shared types | `name`, `signature` |
+| `decision` | Architecture choices, technology selections | `name`, `value`, `reason` |
+| `progress` | Task completion status, files touched | `status`, `files_modified` |
+
+### Sub-Agent Context Injection
+
+When spawning each sub-agent, the coordinator includes in the context template:
+
+```
+## Shared Context (from sibling phases)
+
+[Contents of flow/.wave-context.jsonl, if any entries exist]
+
+RULES:
+- Read shared context before starting each task
+- Append contract/decision/progress entries as you work
+- If a sibling defined a contract, use that exact signature
+- If a sibling made an architecture decision, follow it
+```
+
+For the first task in a wave, the context file may be empty. As phases progress, entries accumulate and inform subsequent tasks.
+
+---
+
 ## Dependency Analysis
 
 ### Dependency Declaration Syntax
@@ -229,6 +284,25 @@ For each pair of phases (A, B) in the wave:
 
 File conflict does NOT affect non-conflicting phases — their results are preserved.
 
+### Contract Conflict Detection
+
+After collecting all wave results, parse `flow/.wave-context.jsonl` and check for **contract conflicts**:
+
+```
+For each pair of "contract" entries with the same name:
+  if entry_A.signature != entry_B.signature:
+    → Contract conflict detected
+```
+
+**On contract conflict**:
+1. Present the conflicting contract definitions — show the name, the two signatures, and which phases defined them
+2. Offer options:
+   - **(1) Pick one**: User selects which phase's contract to use; the other phase must be re-run with the chosen contract injected
+   - **(2) Re-run conflicting phases sequentially**: Re-execute only the conflicting phases in order, so the second phase sees the first's contract
+   - **(3) Stop execution**: Halt for manual resolution
+
+Contract conflicts are checked **after** file conflicts. Both may exist simultaneously — present all conflicts before asking for resolution.
+
 ### Failure Handling
 
 | Scenario | Behavior |
@@ -312,6 +386,9 @@ When phases are aggregated (combined complexity ≤ 6), aggregated phases are tr
 9. **Reuse phase-isolation format** — sub-agent prompts and JSON returns follow phase-isolation.md exactly
 10. **Wave analysis is fast** — dependency parsing and topological sort add negligible overhead
 11. **Verification is internal to sub-agents** — per-task verification loops run entirely inside each phase sub-agent. The wave coordinator does not interact with verification; it only processes the final `task_verifications` field from the JSON return. See `.claude/resources/core/per-task-verification.md` for the complete verification system.
+12. **Shared context per wave** — each wave creates a fresh `.wave-context.jsonl` file, deleted after post-wave processing
+13. **Contract conflicts require user intervention** — never silently resolve conflicting contract signatures between parallel phases
+14. **Append-only context** — sub-agents only append to `.wave-context.jsonl`, never edit or delete existing entries
 
 ---
 
@@ -323,6 +400,7 @@ When phases are aggregated (combined complexity ≤ 6), aggregated phases are tr
 | `.claude/resources/core/discovery-sub-agents.md` | Parallel spawning pattern (3 agents → collect → merge) |
 | `.claude/resources/core/review-multi-agent.md` | Parallel agents with deduplication |
 | `.claude/resources/core/model-routing.md` | Model tier selection per phase complexity |
+| `.claude/resources/core/shared-context.md` | Shared context file format, entry types, and coordination rules |
 | `.claude/resources/core/complexity-scoring.md` | Complexity scores and aggregation rules |
 | `.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 (Steps 2b, 3, 4 modified for waves) |