deepflow 0.1.107 → 0.1.109

package/src/commands/df/plan.md

@@ -7,7 +7,8 @@ description: Compare specs against codebase and past experiments, generate prior
 
 Compare specs against codebase and past experiments. Generate prioritized tasks.
 
-**NEVER:** use EnterPlanMode, use ExitPlanMode — this command IS the planning phase
+**NEVER:** Read implementation source files, edit code, use TaskOutput, use EnterPlanMode, use ExitPlanMode
+**ONLY:** Read specs/*.md, .deepflow/config.yaml, .deepflow/experiments/, PLAN.md, .deepflow/*.md state files, spawn agents, run health checks, update PLAN.md
 
 ## Usage
 ```
@@ -75,26 +76,108 @@ Glob `.deepflow/experiments/{topic}--*`. File naming: `{topic}--{hypothesis}--{s
 
 Implementation tasks BLOCKED until spike validates.
 
-### 3. DETECT PROJECT CONTEXT
+### 3. EXPLORE & IMPACT (PARALLEL AGENTS)
 
-Identify code style, patterns (error handling, API structure), integration points. Include in task descriptions.
+Spawn three parallel `Task(subagent_type="default", model="sonnet")` agents simultaneously. Collect all outputs before proceeding.
 
-### 4. IMPACT ANALYSIS (L3 specs only)
+#### Agent A — Code Style & Conventions
 
-Skip for L0–L2 specs. For each file in a task's `Files:` list, find blast radius.
+```
+## Objective
+Identify code style, patterns, and integration points relevant to the spec under analysis.
+
+## Acceptance Criteria
+- Return a code style summary covering: naming conventions, error handling patterns, API structure, module boundaries
+- List integration points (files/exports) that the spec's target files interact with
+- Flag any implicit patterns not captured in the spec
+
+## Spec and target files
+{spec_file_path}
+{files_list_from_spec}
+
+## Output contract (return EXACTLY this structure — no deviations)
+
+### Code Style Summary
+- Naming: {convention observed}
+- Error handling: {pattern observed}
+- API structure: {pattern observed}
+- Module boundaries: {pattern observed}
+
+### Integration Points
+- {file}: {how it integrates} [callee|caller|peer]
+
+### Implicit Patterns
+- {pattern}: {description}
+```
+
+#### Agent B — Blast Radius (LSP-first)
+
+```
+## Objective
+Perform LSP-first impact analysis for each file in the spec's Files list. Produce a blast-radius map with caller counts and impact reasons.
+
+## Acceptance Criteria
+- PRIMARY: Run LSP `findReferences`/`incomingCalls` on every export being changed in scope
+- FALLBACK: If LSP is unavailable for a file, log exactly `LSP unavailable for {file}: {reason}` then use grep
+- Annotate each impacted file with WHY it is affected
+- Classify duplicate logic files as [active] (consolidate) or [dead] (DELETE candidate)
+- Trace data flow via LSP `outgoingCalls` for consumer mapping
+- Skip impact analysis entirely for spike tasks
+
+## Spec and target files
+{spec_file_path}
+{files_list_from_spec}
+
+## Output contract (return EXACTLY this structure — no deviations)
+
+### Blast Radius per File
+- {file}: {caller_count} callers — {why_impacted}
+  - Callers: {file1}, {file2}
+  - Duplicates: {file} [active|dead]
+  - Consumers (outgoing): {file1}, {file2}
+
+### Files Outside Original Scope
+- {file}: (impact — verify/update) — {reason}
+
+### LSP Fallback Log
+- {file}: LSP unavailable — {reason} (grep used)
+```
+
+#### Agent C — Dead Code & TODOs
+
+```
+## Objective
+Audit the codebase for incomplete work and dead code related to the spec's scope.
 
-**Search (prefer LSP, fallback grep):**
-1. **Callers:** LSP `findReferences`/`incomingCalls` on exports being changed. Annotate WHY impacted. Fallback: grep.
-2. **Duplicates:** Similar logic files. Classify: `[active]` → consolidate, `[dead]` → DELETE.
-3. **Data flow:** LSP `outgoingCalls` to trace consumers.
+## Acceptance Criteria
+- Use the `code-completeness` skill to surface TODOs/FIXMEs/HACKs, stubs, and skipped tests
+- Flag any dead code (unreferenced exports, unused modules) within spec scope
+- Inventory all stubs that must be implemented before tasks can be marked done
 
-Embed as `Impact:` block in each task. Files outside original `Files:` → add with `(impact — verify/update)`. Skip for spikes.
+## Spec and target files
+{spec_file_path}
+{files_list_from_spec}
+
+## Output contract (return EXACTLY this structure — no deviations)
+
+### TODO / FIXME / HACK Inventory
+- {file}:{line}: {tag} — {description}
 
-### 4.5. TARGETED EXPLORATION
+### Stubs & Incomplete Implementations
+- {file}:{symbol}: {reason incomplete}
 
-Follow `templates/explore-agent.md` for spawn rules. 3-5 agents cover post-LSP gaps: conventions, dead code, implicit patterns.
+### Dead Code Flags
+- {file}:{symbol}: [dead] — {evidence}
 
-Use `code-completeness` skill: implementations matching spec, TODOs/FIXMEs/HACKs, stubs, skipped tests.
+### Skipped Tests
+- {file}:{test_name}: [skipped] — {reason if known}
+```
+
+**Merged output contract** (consumed by §4.6 and §5):
+- Code style summary (from Agent A)
+- Blast radius per file with caller counts (from Agent B)
+- Dead code flags (from Agent C)
+- TODO/stub inventory (from Agent C)
 
 ### 4.6. CROSS-TASK FILE CONFLICT DETECTION
 
@@ -203,6 +286,96 @@ Continue processing remaining specs regardless of individual failures. Only succ
 
 **Flow after fan-out:** The consolidator (§5B) reads mini-plans from `.deepflow/plans/` for consolidation (global renumbering, cross-spec conflict detection, prioritization). §5 handles both the single-spec monolithic path and the multi-spec consolidation path.
 
+### 4.8. INTEGRATION TASK DETECTION (MULTI-SPEC)
+
+**When:** >1 plannable spec found in §1. Skip for single-spec plans.
+
+**Purpose:** Specs implemented in isolation often break at integration boundaries — mismatched API contracts, conflicting migrations, incompatible types. This step detects shared interfaces and auto-generates integration tasks to catch these gaps before they cascade into uncontrolled fix spirals.
+
+#### 4.8.1. Detect Shared Interfaces
+
+After §4.7.3 collects mini-plans, spawn a single `Task(subagent_type="default", model="sonnet")` to scan all plannable specs for interface overlap:
+
+```
+You are an integration analyst. Detect shared interfaces across specs AND the existing codebase.
+
+## Spec files (being planned now)
+{list all plannable spec file paths}
+
+## Completed spec files (already implemented)
+{list all specs/done-*.md file paths, or "(none)" if empty}
+
+## Instructions
+
+1. Read each plannable spec file
+2. Read each done-* spec file (for their declared Interfaces/Produces sections)
+3. **Ground-truth check on done-* specs:** For each interface a done-* spec claims to Produce, verify the ACTUAL implementation in the codebase matches the spec declaration:
+   - API routes: grep for the route handler, read the response struct/type to confirm the actual shape
+   - DB tables: read the latest migration files to confirm actual column names and types
+   - Shared types: read the type definition file to confirm actual fields
+   - If the code DIFFERS from the spec declaration, record the CODE's version as the real contract (the spec may be stale after fix cycles)
+4. Extract interfaces from plannable specs (in priority order):
+   a. Explicit `## Interfaces` section (Produces/Consumes declarations)
+   b. `## Dependencies` section (depends_on references)
+   c. Implicit: API routes mentioned in Requirements/ACs, DB tables/migrations in Technical Notes, shared types/packages in Files
+5. Build an interface map: for each interface, list who produces it, who consumes it, and whether the ground-truth matches the spec declaration
+
+## OUTPUT FORMAT — MANDATORY
+
+### Interface Map
+
+- `{interface}` [{type: api|db|type|package}]
+  - Produces: {spec} — declared: `{shape from spec}` | actual: `{shape from code}`
+  - Consumes: {spec2}, {spec3}
+
+### Stale Contracts (spec ≠ code)
+
+- `{interface}`: {done-spec} declares `{spec_shape}` but code has `{actual_shape}` — {what changed and why it matters}
+
+### Contract Risks
+
+- {risk}: {spec_a} produces `{interface}` but {spec_b} consumes it with different assumptions — {detail}
+
+### Migration Conflicts
+
+- {migration_a} ({spec_a}) and {migration_b} ({spec_b}): {conflict description}
+
+If no shared interfaces found, return:
+### Interface Map
+(none detected — specs are independent)
+```
+
+#### 4.8.2. Generate Integration Tasks
+
+**Skip if:** Interface Map returns "(none detected — specs are independent)".
+
+For each group of specs sharing interfaces, generate ONE integration task appended AFTER all spec tasks in the consolidated plan. Integration tasks are always the last wave.
+
+**Integration task format:**
+```markdown
+- [ ] **T{N}** [INTEGRATION]: Verify {spec_a} ↔ {spec_b} contracts
+  - Files: {files at integration boundaries — API handlers, adapters, shared types, migrations}
+  - Integration ACs:
+    - End-to-end flow: {producer} → {consumer} works with real data
+    - Migration idempotency: all migrations run 001→N twice without error
+    - Contract match: {producer API response shape} matches {consumer expected shape}
+    - Type compatibility: shared types compile across all consuming packages
+  - Model: opus
+  - Effort: high
+  - Blocked by: {all implementation task IDs from both specs}
+```
+
+**Rules:**
+- ONE integration task per interface cluster (group of specs connected by shared interfaces)
+- Integration tasks are ALWAYS blocked by ALL implementation tasks of the connected specs
+- Integration ACs are CONCRETE — derived from the actual interfaces detected, not generic
+- **Stale Contracts from §4.8.1 are HIGH PRIORITY ACs** — if a done-spec declares shape X but code has shape Y, the integration task MUST include an AC verifying that the new spec's consumer uses shape Y (the real one), not shape X (the stale one). Include both shapes in the AC for clarity.
+- Contract Risks from §4.8.1 become specific ACs (e.g., "verify endpoint returns byte-exact JSON" if a risk about serialization was detected)
+- Migration Conflicts from §4.8.1 become idempotency ACs
+- Integration tasks use `opus/high` — they require understanding multiple spec contexts
+
+**Pass integration analysis output to §5B consolidator** (append to Opus prompt as `## Integration Analysis` section).
+
 ### 5. COMPARE & PRIORITIZE
 
 **Two paths** — determined by spec count from §1/§4.7:
@@ -211,9 +384,47 @@ Continue processing remaining specs regardless of individual failures. Only succ
 
 **When:** Exactly 1 plannable spec (§4.7 was skipped).
 
-Spawn `Task(subagent_type="reasoner", model="opus")`. Map each requirement to DONE/PARTIAL/MISSING/CONFLICT. Check REQ-AC alignment. Flag spec gaps.
+Spawn `Task(subagent_type="reasoner", model="opus")` passing ONLY:
+- `spec_path` — path to the spec file (e.g., `specs/feature.md`)
+- `agent_summaries[]` — structured output blocks returned by §3 Agents A, B, C (their output contract sections verbatim — no raw source code, no inlined file contents)
+- `experiment_results[]` — paths and conclusion excerpts from `.deepflow/experiments/` matches found in §2 (paths only, no full file content)
+
+**NEVER pass to the reasoner:** raw source code, inlined file contents, or any implementation file text. The reasoner works from paths and summaries only.
+
+The reasoner prompt:
+
+```
+You are the plan reasoner. Analyze this spec and produce a prioritized task plan.
+
+## Spec file path
+{spec_path}
+
+Read the spec using the Read tool on the path above. Do NOT read any implementation files.
+
+## Agent summaries (from §3 parallel agents)
+
+### Code Style & Conventions (Agent A)
+{agent_a_summary — verbatim output contract block}
+
+### Blast Radius (Agent B)
+{agent_b_summary — verbatim output contract block}
+
+### Dead Code & TODOs (Agent C)
+{agent_c_summary — verbatim output contract block}
+
+## Experiment results (paths + conclusions)
+{for each experiment: path and Conclusion section excerpt only}
+
+## Your job
+
+Map each requirement to DONE/PARTIAL/MISSING/CONFLICT. Check REQ-AC alignment. Flag spec gaps.
+Scan ACs for metric patterns `{metric} {operator} {number}[unit]` — flag matches for §6.5 Optimize tasks, flag ambiguous thresholds ("fast", "small") as spec gaps.
+Apply the §5.5 routing matrix to classify model + effort per task.
 
 Priority: Dependencies → Impact → Risk
+```
+
+Then apply §5.5 routing matrix. Continue to §6.
 
 ##### Metric AC Detection
 
@@ -266,7 +477,11 @@ You are the plan prioritizer. The mechanical consolidation (global T-numbering,
 
 {for each plannable spec: spec filename and its Requirements + Acceptance Criteria sections}
 
-## Your job — THREE things only
+## Integration Analysis (from §4.8)
+
+{paste integration analyst output here — Interface Map, Contract Risks, Migration Conflicts}
+
+## Your job — FOUR things only
 
 ### 1. Cross-Spec Prioritization
 Review the task ordering across specs. If a different spec ordering would reduce blocked tasks or improve parallelism, suggest reordering. Otherwise confirm the current ordering is optimal.
@@ -277,7 +492,14 @@ If reordering is needed, output the recommended spec order. The orchestrator wil
 For each spec, map requirements to DONE/PARTIAL/MISSING/CONFLICT. Flag spec gaps.
 Scan ACs for metric patterns `{metric} {operator} {number}[unit]` — flag matches for §6.5 Optimize tasks, flag ambiguous thresholds ("fast", "small") as spec gaps.
 
-### 3. Model + Effort Classification
+### 3. Integration Task Validation
+Review the Integration Analysis. For each Contract Risk and Migration Conflict:
+- Confirm or refine the generated integration task ACs
+- Add missing ACs if you detect interface assumptions not caught by the analyst (e.g., serialization format, column type mismatches, auth flow dependencies)
+- Remove false positives (interfaces that look shared but are actually independent)
+- If no integration tasks were generated but you detect cross-spec coupling, CREATE integration tasks following the §4.8.2 format
+
+### 4. Model + Effort Classification
 Apply routing matrix to each task:
 
 | Task type | Model | Effort |
@@ -307,6 +529,7 @@ Defaults: sonnet / medium.
 |--------|-------|
 | Specs analyzed | {N} |
 | Tasks created | {N} |
+| Integration tasks | {N} |
 | Ready (no blockers) | {N} |
 | Blocked | {N} |
 
@@ -318,6 +541,10 @@ Defaults: sonnet / medium.
 
 {Insert the consolidated tasks from plan-consolidator verbatim, adding ` — model/effort` to each task line per the routing matrix. Do NOT alter T-ids, descriptions, Blocked by, or conflict annotations.}
 
+### integration
+
+{Insert integration tasks from §4.8.2, validated/refined by step 3 above. Each task follows the standard format with [INTEGRATION] marker.}
+
 Example transformation:
   Input:  `- [ ] **T3**: Create pkg/engine/go.mod | Blocked by: T8`
   Output: `- [ ] **T3**: Create pkg/engine/go.mod — haiku/low | Blocked by: T8`
@@ -452,5 +679,6 @@ If any L0–L1 spec: `ℹ L0–L1 specs generate spikes only. Deepen with /df:sp
 - **Learn from failures** — Extract next hypothesis, never repeat approach
 - **Plan only** — Do NOT implement (except quick validation prototypes)
 - **One task = one logical unit** — Atomic, committable
+- **Context budget** — orchestrator reads ONLY specs, config, experiments, PLAN.md, .deepflow/ state; never implementation files
 - Prefer existing utilities over new code; flag spec gaps
 - Always use `Task` tool with explicit `subagent_type` and `model`

package/src/commands/df/verify.md

@@ -25,7 +25,7 @@ context: fork
 
 When invoked with `--diagnostic`:
 
-- Run **L0-L4 only** (skip L5 entirely, even if frontend detected).
+- Run **L0-L4.5 only** (skip L5 entirely, even if frontend detected).
 - Write results to `.deepflow/results/final-test-{spec}.yaml` under a `diagnostics:` key:
   ```yaml
   diagnostics:
@@ -35,7 +35,8 @@ When invoked with `--diagnostic`:
     L1: pass          # or fail
     L2: pass          # or warn (no tool)
     L4: fail          # or pass
-    summary: "L0 ✓ | L1 ✓ | L2 ⚠ | L3 — | L4 ✗"
+    L4.5: pass        # or fail or skip (no deps)
+    summary: "L0 ✓ | L1 ✓ | L2 ⚠ | L3 — | L4 ✗ | L4.5 ✓"
   ```
 - Prefix all report output with `[DIAGNOSTIC]`.
 - **Skip entirely:** Post-Verification merge (§4), fix task creation, spec rename, decision extraction, PLAN.md cleanup (step 6).
@@ -85,10 +86,44 @@ Nothing found → `⚠ No build/test commands detected. L0/L4 skipped. Set quali
 
 No tool → pass with warning. When available: stash changes → run coverage on baseline → stash pop → run coverage on current → compare. Drop → FAIL. Same/improved → pass.
 
-**L3: Integration** — Subsumed by L0 + L4. No separate check.
+**L3: AC coverage verification** — Verify that agent-reported acceptance criteria coverage matches the spec's acceptance criteria section. Parse spec file for `## Acceptance Criteria` section, extract all ACs. For each AC, verify that agent execution explicitly claimed coverage (via agent output or PLAN.md task completion notes). Missing or uncovered ACs → FAIL with list of uncovered ACs. All ACs claimed → pass.
 
 **L4: Tests** — Run AFTER L0 passes. Run even if L1-L2 had issues. Exit 0 → pass. Non-zero → FAIL with last 50 lines + fix task. If `quality.test_retry_on_fail: true`: re-run once; second pass → warn (flaky); second fail → genuine failure.
 
+**L4.5: Cross-Spec Integration** (if integration tasks exist)
+
+**Trigger:** Current spec's PLAN.md section contains `[INTEGRATION]` tasks, OR spec has `depends_on` referencing `done-*` specs.
+
+**Check:** Load dependent specs (`specs/done-*.md` referenced in `depends_on` or connected via integration tasks). For each:
+1. Re-run L0 (build) — already covered by standard L0, skip
+2. Re-run L4 (tests) — already covered by standard L4, skip
+3. **Contract verification (code-first, not spec-first):**
+   - For each `Produces` interface in dependent specs, verify against the ACTUAL CODE, not the spec declaration:
+     - API routes: grep for the handler, read the response struct/type → this is the real contract
+     - DB tables: read the latest migration files → actual column names and types
+     - Shared types: read the type definition → actual fields
+   - If the spec declaration differs from the code, the CODE is the source of truth (specs may be stale after fix cycles)
+   - Then verify that the CURRENT spec's consumers match the code's actual shape
+4. **Stale spec detection** — if a done-* spec's `## Interfaces` section doesn't match the code, emit advisory warning:
+   ```
+   ⚠ Stale interface: done-auth-spec declares POST /login → { access_token, refresh_token }
+     but code returns { token, refresh }. Spec should be updated.
+   ```
+5. **Migration idempotency** — if migrations exist: run `{build_command}` twice (the build already runs migrations in most Go/Node projects). If a dedicated migration command exists in config (`quality.migration_command`), run it twice and verify exit 0 both times.
+
+**Outcome:** Pass if all contracts verified against code. Fail with specific mismatches:
+```
+✗ L4.5: Contract mismatch
+  - done-auth code returns POST /api/v1/auth/login → { token: string }
+    but operator SPA sends { api_key } in body (expected { token })
+  - done-backend code stores rounds.result_json as TEXT
+    but current spec reads it with JSONB operators
+⚠ L4.5: Stale spec (advisory, not blocking)
+  - done-auth-spec declares { access_token } but code returns { token }
+```
+
+Fix task on L4.5 failure: prescriptive — names the exact contract from CODE (not spec), the producer, the consumer, and which side should change (prefer changing consumer to match producer's actual implementation).
+
 **L5: Browser Verification** (if frontend detected)
 
 Algorithm: detect frontend → resolve dev command/port → start server → poll readiness → read assertions from PLAN.md → auto-install Playwright Chromium → evaluate via `locator.ariaSnapshot()` → screenshot → retry once on failure → report.
@@ -148,24 +183,26 @@ All L5 outcomes: `✓` pass | `⚠` passed on retry | `✗` both failed (same) |
 
 ### 3. GENERATE REPORT
 
-**Success:** `doing-upload.md: L0 ✓ | L1 ✓ (5/5 files) | L2 ⚠ (no coverage tool) | L3 — (subsumed) | L4 ✓ (12 tests) | L5 ✓ | 0 quality issues`
+**Success:** `doing-upload.md: L0 ✓ | L1 ✓ (5/5 files) | L2 ⚠ (no coverage tool) | L3 — (subsumed) | L4 ✓ (12 tests) | L4.5 ✓ (3 contracts) | L5 ✓ | 0 quality issues`
 
 **Failure:**
 ```
-doing-upload.md: L0 ✓ | L1 ✗ (3/5 files) | L2 ⚠ | L3 — | L4 ✗ (3 failed) | L5 ✗ (2 assertions failed)
+doing-upload.md: L0 ✓ | L1 ✗ (3/5 files) | L2 ⚠ | L3 — | L4 ✗ (3 failed) | L4.5 ✗ (1 mismatch) | L5 ✗ (2 assertions failed)
 
 Issues:
   ✗ L1: Missing files: src/api/upload.ts, src/services/storage.ts
   ✗ L4: 3 test failures
     FAIL src/upload.test.ts > should validate file type
+  ✗ L4.5: Contract mismatch — done-auth produces { access_token } but operator sends { api_key }
 
 Fix tasks added to PLAN.md:
   T10: Implement missing upload endpoint and storage service
+  T11: Fix operator login to send access_token per auth spec contract
 
 Run /df:execute --continue to fix in the same worktree.
 ```
 
-**Gate conditions (ALL must pass to merge):** L0 build (or no command) | L1 all files in diff | L2 coverage held (or no tool) | L4 tests pass (or no command) | L5 assertions pass (or no frontend/assertions).
+**Gate conditions (ALL must pass to merge):** L0 build (or no command) | L1 all files in diff | L2 coverage held (or no tool) | L4 tests pass (or no command) | L4.5 contracts match (or no dependencies/integration tasks) | L5 assertions pass (or no frontend/assertions).
 
 **All pass →** Post-Verification merge. **Issues found →** Add fix tasks to worktree PLAN.md (IDs continue from last), register via TaskCreate/TaskUpdate, output report + "Run /df:execute --continue". Do NOT create new specs, worktrees, or merge with issues pending.
 
@@ -193,7 +230,8 @@ Objective: ... | Approach: ... | Why it worked: ... | Files: ...
 2. **Merge:** `git checkout main && git merge ${BRANCH} --no-ff -m "feat({spec}): merge verified changes"`. On conflict → keep worktree, output "Resolve manually, run /df:verify --merge-only", exit.
 3. **Cleanup:** `git worktree remove --force ${PATH} && git branch -d ${BRANCH} && rm -f .deepflow/checkpoint.json`
 4. **Rename spec:** `mv specs/doing-${NAME}.md specs/done-${NAME}.md`
-5. **Extract decisions:** Read done spec, extract `[APPROACH]`/`[ASSUMPTION]`/`[PROVISIONAL]` decisions, append to `.deepflow/decisions.md` as `### {date} — {spec}\n- [TAG] decision — rationale`. Delete done spec after successful write; preserve on failure.
-6. **Clean PLAN.md:** Find the `### {spec-name}` section (match on name stem, strip `doing-`/`done-` prefix). Delete from header through the line before the next `### ` header (or EOF). Recalculate Summary table (recount `### ` headers for spec count, `- [ ]`/`- [x]` for task counts). If no spec sections remain, delete PLAN.md entirely. Skip silently if PLAN.md missing or section already gone.
+5. **Cleanup stale plans:** `rm -f .deepflow/plans/doing-${NAME}.md`
+6. **Extract decisions (additive):** Read done spec, extract `[APPROACH]`/`[ASSUMPTION]`/`[PROVISIONAL]`/`[FUTURE]`/`[UPDATE]` decisions, append to `.deepflow/decisions.md` under `### {date} — {spec}` header. If the header already exists (decisions were captured incrementally during execution via §5.5.1), append only NEW decisions not already present (deduplicate by comparing decision text). Delete done spec after successful write; preserve on failure.
+7. **Clean PLAN.md:** Find the `### {spec-name}` section (match on name stem, strip `doing-`/`done-` prefix). Delete from header through the line before the next `### ` header (or EOF). Recalculate Summary table (recount `### ` headers for spec count, `- [ ]`/`- [x]` for task counts). If no spec sections remain, delete PLAN.md entirely. Skip silently if PLAN.md missing or section already gone.
 
 Output: `✓ Merged → main | ✓ Cleaned worktree | ✓ Spec → done | ✓ Decisions extracted | ✓ Cleaned PLAN.md | Workflow complete! Ready: /df:spec <name>`

package/templates/config-template.yaml

@@ -38,6 +38,7 @@ models:
 
 explore:
   max_tokens: 500      # Controls Explore agent response length
+  explore_lsp_timeout_ms: 15000  # Timeout (ms) for the Phase 1 LSP subprocess; on timeout the static template is injected as fallback
 
 commits:
   format: "feat({spec}): {description}"

package/templates/explore-protocol.md.bak

@@ -0,0 +1,69 @@
+# Search Protocol
+
+You MUST follow these phases. Do NOT search sequentially.
+
+## DIVERSIFY
+- Launch 5-8 parallel tool calls in a single message
+- **Prefer LSP** when searching for symbols, types, or function usage:
+  - `workspaceSymbol` — find symbols by name across the project (faster + more precise than grep)
+  - `documentSymbol` — list all symbols in a file (returns line ranges natively)
+  - `findReferences` — find all usages of a symbol
+- **Fallback to Grep/Glob** for string patterns, config values, or when LSP is unavailable
+- Narrow down to 2-5 candidate files
+
+## CONVERGE
+- **Prefer LSP** to validate and extract precise ranges:
+  - `goToDefinition` — jump to source without reading the whole file
+  - `hover` — get type info and docs in one call
+  - `documentSymbol` — get all symbols with line ranges
+- Fallback: `Read` with `offset`/`limit` for only the relevant line range
+- Eliminate false positives, confirm relevance
+
+## EARLY STOP
+- Stop as soon as >= 2 relevant files answer the question
+- Exception: searching for a single unique thing → find just 1
+
+## Return Format
+
+```
+filepath:startLine-endLine -- why relevant
+```
+
+## Good Example (2 turns)
+
+**Turn 1 (DIVERSIFY):**
+```
+- LSP workspaceSymbol: "Config" (find all Config-related symbols)
+- LSP workspaceSymbol: "Database" (find DB-related symbols)
+- Grep: pattern="export.*config", type="ts" (catch non-symbol patterns)
+- Glob: "src/**/*config*" (catch config files by name)
+```
+
+**Turn 2 (CONVERGE):**
+```
+- LSP hover on top matches (get type + docs without reading file)
+- Read: src/config/app.ts offset=1 limit=45 (only the relevant range)
+```
+Result:
+```
+src/config/app.ts:1-45 -- main config export
+src/config/types.ts:10-30 -- Config interface
+```
+
+## Antipattern (5+ turns)
+
+```
+Turn 1: Glob for config files
+Turn 2: Read the first file
+Turn 3: Grep for config patterns
+Turn 4: Read results
+Turn 5: Another Grep search
+```
+
+This wastes tokens. Never do this.
+
+DO NOT: narrate your search process, make recommendations, propose solutions, generate tables.
+
+Fallback: search `node_modules/`/`vendor/` ONLY when not found in app code.
+
+Max response: 500 tokens.

package/templates/plan-template.md

@@ -45,6 +45,17 @@ When no experiments exist to validate an approach, start with a minimal validati
 
 Spike tasks are 1-2 tasks to validate an approach before committing to full implementation.
 
+### integration
+
+Auto-generated when multiple specs share interfaces (APIs, DB tables, types).
+
+- [ ] **T5** [INTEGRATION]: Verify auth ↔ operator contracts — opus/high | Blocked by: T2, T4
+  - Files: internal/auth/login.go, apps/operator/src/auth/AuthProvider.tsx
+  - Integration ACs:
+    - End-to-end: operator login → token → player bootstrap works
+    - Contract: POST /api/v1/auth/login response matches operator SPA expectations
+    - Migrations: 001→005 run twice without error (idempotent)
+
 ---
 
 <!--

package/templates/spec-template.md

@@ -24,6 +24,21 @@
 <!-- Optional. List specs that must be completed before this one. -->
 <!-- - depends_on: doing-other-spec-name -->
 
+## Interfaces
+
+<!-- Optional but RECOMMENDED for multi-spec projects. Declare what this spec produces and consumes.
+     /df:plan uses these to auto-generate integration tasks when specs share contracts. -->
+
+<!-- ### Produces
+- `POST /api/v1/auth/login` → `{ access_token: string, refresh_token: string }`
+- `table: operators` columns: `id, api_key_hash, scopes`
+- `type: SessionState` from `packages/shared/types.ts` -->
+
+<!-- ### Consumes
+- `POST /api/v1/auth/login` from done-auth-spec (expects `{ access_token }`)
+- `table: operators` expects column `api_key_hash`
+- `type: SessionState` from packages/shared -->
+
 ## Out of Scope
 
 - [Explicitly excluded: e.g., "Video upload is NOT included"]