deepflow 0.1.110 → 0.1.112

package/src/commands/df/execute.md

@@ -40,44 +40,55 @@ Each task = one background agent. **NEVER use TaskOutput** (100KB+ transcripts e
 `--continue` → load `.deepflow/checkpoint.json`, verify worktree exists (else error "Use --fresh"), skip completed. `--fresh` → delete checkpoint. Checkpoint exists → prompt "Resume? (y/n)".
 Shell: `` !`cat .deepflow/checkpoint.json 2>/dev/null || echo 'NOT_FOUND'` `` / `` !`git diff --quiet && echo 'CLEAN' || echo 'DIRTY'` ``
 
-### 1.5. CREATE WORKTREE
+### 1.5. CREATE WORKTREES (per spec)
 
-Require clean HEAD. Derive SPEC_NAME from `specs/doing-*.md`. Create `.deepflow/worktrees/{spec}` on branch `df/{spec}`. Reuse if exists; `--fresh` deletes first. If `worktree.sparse_paths` non-empty: `git worktree add --no-checkout`, `sparse-checkout set {paths}`, checkout.
+Require clean HEAD. Discover **all** specs in execution scope:
+```
+DOING_SPECS=!`ls specs/doing-*.md 2>/dev/null | sed 's|specs/doing-||;s|\.md$||' | tr '\n' ' ' || echo 'NOT_FOUND'`
+```
+
+For **each** `{spec}` in `DOING_SPECS`, create `.deepflow/worktrees/{spec}` on branch `df/{spec}`. Reuse if exists; `--fresh` deletes first. If `worktree.sparse_paths` non-empty: `git worktree add --no-checkout`, `sparse-checkout set {paths}`, checkout.
+
+Build an in-memory map `SPEC_WORKTREES = {spec → {path, branch}}`. This map drives per-task routing in §5 and §5.5 and is persisted in `.deepflow/checkpoint.json` under `spec_worktrees`. Tasks from spec A run in worktree A; tasks from spec B run in worktree B. No cross-spec commits share a branch.
+
+Then run §1.5.1, §1.6, and §1.7 **per worktree** before any wave spawns.
 
-### 1.5.1. SYMLINK DEPENDENCIES
+### 1.5.1. SYMLINK DEPENDENCIES (per worktree)
 
-After worktree creation, symlink `node_modules` from the main repo so TypeScript/LSP/build can resolve dependencies without a full install:
+After each worktree is created, symlink `node_modules` from the main repo so TypeScript/LSP/build can resolve dependencies without a full install:
 ```bash
-node "${HOME}/.claude/bin/worktree-deps.js" --source "$(git rev-parse --show-toplevel)" --worktree "${WORKTREE_PATH}"
+node "${HOME}/.claude/bin/worktree-deps.js" --source "$(git rev-parse --show-toplevel)" --worktree "${SPEC_WORKTREES[spec].path}"
 ```
 The script finds `node_modules` at root and inside monorepo directories (`packages/`, `apps/`, etc.) and creates symlinks in the worktree. Outputs JSON: `{"linked": N, "total": M}`. Errors are non-fatal — log and continue.
 
-### 1.6. RATCHET SNAPSHOT
+### 1.6. RATCHET SNAPSHOT (per worktree)
 
-Snapshot pre-existing test files — only these count for ratchet (agent-created excluded):
+For each spec worktree, snapshot pre-existing test files — only these count for ratchet (agent-created excluded):
 ```bash
-git -C ${WORKTREE_PATH} ls-files | grep -E '\.(test|spec)\.[^/]+$|^test_|_test\.[^/]+$|^tests/|__tests__/' > .deepflow/auto-snapshot.txt
+git -C ${SPEC_WORKTREES[spec].path} ls-files | grep -E '\.(test|spec)\.[^/]+$|^test_|_test\.[^/]+$|^tests/|__tests__/' > .deepflow/auto-snapshot-{spec}.txt
 ```
 
+Each spec has its own snapshot file. Ratchet checks in §5.5 pass the snapshot file matching the task's spec.
+
 ### 1.7. NO-TESTS BOOTSTRAP
 
 <!-- AC-1: zero test files triggers bootstrap before wave 1 -->
 <!-- AC-2: bootstrap success re-snapshots auto-snapshot.txt; subsequent tasks use updated snapshot -->
 <!-- AC-3: bootstrap failure with default model retries with Opus; double failure halts with specific message -->
 
-**Gate:** After §1.6 snapshot, check `auto-snapshot.txt`:
+**Gate (per spec):** After §1.6 snapshot, check each spec's snapshot file independently:
 ```bash
-SNAPSHOT_COUNT=$(wc -l < .deepflow/auto-snapshot.txt | tr -d ' ')
+SNAPSHOT_COUNT=$(wc -l < .deepflow/auto-snapshot-{spec}.txt | tr -d ' ')
 ```
-If `SNAPSHOT_COUNT` is `0` (zero test files found), MUST spawn bootstrap agent before wave 1. No implementation tasks may start until bootstrap completes successfully.
+If `SNAPSHOT_COUNT` is `0` for a given spec (zero test files found), MUST spawn a bootstrap agent for **that spec** before any implementation task from that spec runs. Other specs with non-empty snapshots proceed normally.
 
-**Bootstrap flow:**
-1. Spawn `Agent(model="{default_model}", ...)` with Bootstrap prompt (§6). End turn, wait for notification.
-2. **On success (TASK_STATUS:pass):** Re-snapshot immediately:
+**Bootstrap flow (per empty-snapshot spec):**
+1. Spawn `Agent(model="{default_model}", ...)` with Bootstrap prompt (§6), `Working directory: ${SPEC_WORKTREES[spec].path}`. End turn, wait for notification.
+2. **On success (TASK_STATUS:pass):** Re-snapshot immediately for that spec:
    ```bash
-   git -C ${WORKTREE_PATH} ls-files | grep -E '\.(test|spec)\.[^/]+$|^test_|_test\.[^/]+$|^tests/|__tests__/' > .deepflow/auto-snapshot.txt
+   git -C ${SPEC_WORKTREES[spec].path} ls-files | grep -E '\.(test|spec)\.[^/]+$|^test_|_test\.[^/]+$|^tests/|__tests__/' > .deepflow/auto-snapshot-{spec}.txt
    ```
-   All subsequent tasks use this updated snapshot as their ratchet baseline. Proceed to wave 1.
+   All subsequent tasks for that spec use this updated snapshot as their ratchet baseline. Proceed to wave 1.
 3. **On failure (TASK_STATUS:fail) with default model:** Retry ONCE with `Agent(model="opus", ...)` using the same Bootstrap prompt.
    - Opus success → re-snapshot (same command above) → proceed to wave 1.
    - Opus failure → halt with message: `"Bootstrap failed with both default and Opus — manual intervention required"`. Do not proceed.
@@ -137,17 +148,34 @@ Context ≥50% → checkpoint and exit. Before spawning: `TaskUpdate(status: "in
 
 **Token tracking start:** Store `start_percentage` (from context.json) and `start_timestamp` (ISO 8601) keyed by task_id. Omit if unavailable.
 
-**NEVER use `isolation: "worktree"`.** Deepflow manages a shared worktree so wave 2 sees wave 1 commits. **Spawn ALL ready tasks in ONE message** except file conflicts.
+**Intra-wave isolation:** Each task in a wave runs with `isolation: "worktree"` — tasks from the same spec share that spec's worktree branch so wave 2 sees wave 1 commits; tasks from different specs run in different worktrees and never interleave. **Spawn ALL ready tasks in ONE message** except file conflicts.
+
+**Per-spec routing (CRITICAL):** Each task in `WAVE_JSON` carries a `spec` field (from `bin/wave-runner.js`). When building the agent prompt (§6), you MUST set `Working directory: ${SPEC_WORKTREES[task.spec].path}` — the worktree for that task's spec, NOT the first spec in the map. Cross-spec contamination (spawning a task from spec B into spec A's worktree) corrupts branch history and breaks `/df:verify`. If `task.spec` is absent from the JSON, fall back to deriving it from the task's mini-plan file `.deepflow/plans/doing-{specName}.md`; if still unresolvable, defer the task and log `"⚠ T{N} deferred — cannot resolve spec"`.
+
+**File conflicts (1 file = 1 writer):** Check `Files:` from wave-runner JSON output or from mini-plan detail files (`.deepflow/plans/doing-{specName}.md`). File-conflict rule applies **only within the same spec** — two tasks from different specs touching files with identical paths are actually in different worktrees and cannot collide. Overlap within a spec → spawn lowest-numbered only; rest stay pending. Log: `"⏳ T{N} deferred — file conflict with T{M} on {filename}"`
+
+**≥2 [SPIKE] tasks same problem →** Parallel Spike Probes (§5.7). **[OPTIMIZE] tasks →** Optimize Cycle (§5.9), one at a time. **[INTEGRATION] tasks** (`task.isIntegration === true` in WAVE_JSON) **→** use the Integration Task prompt template (§6 Integration Task), not the Standard Task template. Integration tasks always land in the final wave via `Blocked by:` — wave-runner guarantees this, so they execute after all producer/consumer implementation tasks have committed. Route them to the **consumer spec's** worktree via `SPEC_WORKTREES[task.spec].path` (plan.md §4.8.2 places the integration task under the consumer's section header, so `task.spec` is already the consumer).
 
-**File conflicts (1 file = 1 writer):** Check `Files:` from wave-runner JSON output or from mini-plan detail files (`.deepflow/plans/doing-{specName}.md`). Overlap → spawn lowest-numbered only; rest stay pending. Log: `"⏳ T{N} deferred — file conflict with T{M} on {filename}"`
+### 5.1. INTRA-WAVE CHERRY-PICK MERGE
 
-**≥2 [SPIKE] tasks same problem →** Parallel Spike Probes (§5.7). **[OPTIMIZE] tasks →** Optimize Cycle (§5.9), one at a time.
+After ALL wave-N agents complete, cherry-pick each wave-N commit back to the main branch BEFORE wave N+1 begins. This ensures wave N+1 agents see all wave-N changes regardless of which worktree they run in.
+
+**Wave gate:** Wave N+1 MUST NOT start until all wave-N cherry-picks complete.
+
+**Ordering:** Apply cherry-picks in ascending task-number order (e.g., T1 before T2 before T3) for determinism.
+
+**Steps (per wave completion):**
+1. Collect all task commits from wave N (from ratchet PASS records).
+2. Sort commits by ascending task-number order.
+3. For each commit, spawn haiku context-fork (§5.8): `git cherry-pick {sha}`. Receive one-line summary.
+4. On conflict: log `"⚠ cherry-pick conflict: {sha} — {file}"`, abort cherry-pick, mark task as needing manual resolution.
+5. Only after all wave-N cherry-picks finish → proceed to spawn wave N+1 agents.
 
 ### 5.5. RATCHET CHECK
 
-Run `node "${HOME}/.claude/bin/ratchet.js"` in the worktree directory after each agent completes:
+Run `node bin/ratchet.js` in the **task's spec worktree** after each agent completes, using that spec's snapshot file:
 ```bash
-node "${HOME}/.claude/bin/ratchet.js" --worktree ${WORKTREE_PATH} --snapshot .deepflow/auto-snapshot.txt --task T{N}
+node bin/ratchet.js --worktree ${SPEC_WORKTREES[task.spec].path} --snapshot .deepflow/auto-snapshot-{task.spec}.txt --task T{N}
 ```
 
 The script handles all health checks internally and outputs structured JSON:
@@ -174,7 +202,7 @@ The script handles all health checks internally and outputs structured JSON:
   ```
   (Fall back to text mode if `--json` is unavailable: `node "${HOME}/.claude/bin/wave-runner.js" --plan PLAN.md --recalc --failed T{N}`)
   Report: `"✗ T{n}: reverted"`.
-- **Exit 2 (SALVAGEABLE):** Spawn `Agent(model="sonnet")` to fix lint/typecheck issues. Re-run `node "${HOME}/.claude/bin/ratchet.js"`. If still non-zero → revert both commits, set status pending.
+- **Exit 2 (SALVAGEABLE):** Spawn `Agent(model="sonnet")` to fix lint/typecheck issues. Re-run `node bin/ratchet.js`. If still non-zero → revert both commits, set status pending.
 
 #### 5.5.1. AC COVERAGE CHECK (after ratchet pass)
 
@@ -194,18 +222,19 @@ where `{spec_path}` is the path to `specs/doing-{spec_name}.md` and `{agent_outp
 
 Parse the agent's response for `DECISIONS:` line. If present:
 1. Split by ` | ` to get individual decisions
-2. Each decision has format `[TAG] description — rationale` where TAG ∈ {APPROACH, PROVISIONAL, ASSUMPTION, FUTURE, UPDATE}
-3. Append to `.deepflow/decisions.md` under `### {date} — {spec_name}` header (create header if first decision for this spec today, reuse if exists)
-4. Format: `- [TAG] description — rationale`
+2. If any entry does not start with `[TAG]` where TAG ∈ {APPROACH, PROVISIONAL, ASSUMPTION, FUTURE, UPDATE}, emit SALVAGEABLE and skip writing that entry to decisions.md (valid entries still get written).
+3. Each decision has format `[TAG] description — rationale` where TAG ∈ {APPROACH, PROVISIONAL, ASSUMPTION, FUTURE, UPDATE}
+4. Append to `.deepflow/decisions.md` under `### {date} — {spec_name}` header (create header if first decision for this spec today, reuse if exists)
+5. Format: `- [TAG] description — rationale`
 
-If no `DECISIONS:` line in agent output → skip silently (mechanical tasks don't produce decisions).
+If no `DECISIONS:` line in agent output and the task effort is not `low` → emit SALVAGEABLE (non-trivial tasks without a decision line may indicate the agent skipped documenting architectural choices). For tasks with effort `low`, skip silently (mechanical tasks don't produce decisions).
 
 **This runs on every ratchet pass, not just at verify time.** Decisions are captured incrementally as tasks complete, so they're never lost even if verify fails or merge is manual.
 
 **Edit scope validation:** `git diff HEAD~1 --name-only` vs allowed globs. Violation → revert, report.
 **Impact completeness:** diff vs Impact callers/duplicates. Gap → advisory warning (no revert).
 
-**Metric gate (Optimize only):** Run `eval "${metric_command}"` with cwd=`${WORKTREE_PATH}` (never `cd && eval`). Parse float (non-numeric → revert). Compare using `direction`+`min_improvement_threshold`. Both ratchet AND metric must pass → keep. Ratchet pass + metric stagnant → revert. Secondary metrics: regression > `regression_threshold` (5%) → WARNING in auto-report.md (no revert).
+**Metric gate (Optimize only):** Run `eval "${metric_command}"` with cwd=`${SPEC_WORKTREES[task.spec].path}` (never `cd && eval`). Parse float (non-numeric → revert). Compare using `direction`+`min_improvement_threshold`. Both ratchet AND metric must pass → keep. Ratchet pass + metric stagnant → revert. Secondary metrics: regression > `regression_threshold` (5%) → WARNING in auto-report.md (no revert).
 
 **Token tracking result (on pass):** Read `end_percentage`. Sum token fields from `.deepflow/token-history.jsonl` between start/end timestamps (awk ISO 8601 compare). Write to `.deepflow/results/T{N}.yaml`:
 ```yaml
@@ -219,6 +248,20 @@ tokens:
 ```
 Omit if context.json/token-history.jsonl/awk unavailable. Never fail ratchet for tracking errors.
 
+### 5.6. WAVE TEST AGENT
+
+Trigger: task type is [TEST] or orchestrator spawns a dedicated test-writing agent for a wave.
+
+Before spawning the test agent, collect context:
+```bash
+SNAPSHOT_FILES=!`cat .deepflow/auto-snapshot.txt 2>/dev/null || echo ''`
+EXISTING_TEST_NAMES=!`grep -h -E "^\s*(it|test|describe)\(" ${SNAPSHOT_FILES} 2>/dev/null | sed "s/^[[:space:]]*//" || echo ''`
+```
+
+Pass `SNAPSHOT_FILES` and `EXISTING_TEST_NAMES` into the agent prompt so it can avoid duplication.
+
+**Implementation diff:** The wave test agent reads the implementation diff itself using the `Read` tool or `git diff` — do NOT capture or pass the raw diff to the wave test prompt inline. Injecting large diffs inflates context and causes rot.
+
 ### 5.7. PARALLEL SPIKE PROBES
 
 Trigger: ≥2 [SPIKE] tasks with same blocker or identical hypothesis.
@@ -255,7 +298,7 @@ Git operations that produce large output (diff, stash, cherry-pick conflict outp
 **Pattern:**
 ```
 Spawn Agent(model="haiku", run_in_background=false):
-  Working directory: {WORKTREE_PATH}
+  Working directory: ${SPEC_WORKTREES[task.spec].path}
   Run: {git command}
   Return exactly ONE line: "{operation}: {N lines changed / N files / outcome}"
   Do NOT output the raw diff or full command output.
@@ -330,7 +373,9 @@ REPEAT:
 
 ### 6. PER-TASK (agent prompt)
 
-**Common preamble (all):** `Working directory: {worktree_absolute_path}. All file ops use this path. Commit format: {type}({spec}): {desc}`
+**Common preamble (all):** `Working directory: ${SPEC_WORKTREES[task.spec].path}. All file ops use this path. Commit format: {type}({spec}): {desc}`
+
+Resolve `task.spec` from the `WAVE_JSON` entry for this task (fallback: scan `.deepflow/plans/doing-*.md` for the task's block). Never hand an agent a worktree path that belongs to a different spec.
 
 **Task detail loading (before building agent prompt):** Check for `.deepflow/plans/doing-{task_id}.md` (shell injection):
 ```
@@ -357,6 +402,17 @@ Steps (only when `Files:` list is non-empty):
 
 <!-- AC-6: Backward-compatible no-op — when neither Domain Model section exists in the spec nor Existing Types extraction yields content (EXISTING_TYPES is empty string), the Standard Task prompt contains no extra context blocks and is identical to the pre-injection baseline. Zero prompt overhead, zero tool calls for tasks that lack these context sources. -->
 
+**Template selection (deterministic, from WAVE_JSON):**
+
+| Flag                  | Template                           |
+|-----------------------|------------------------------------|
+| `isIntegration: true` | Integration Task (below)           |
+| `isSpike: true`       | Spike                              |
+| `isOptimize: true`    | Optimize Task                      |
+| (none)                | Standard Task                      |
+
+Read these fields from `WAVE_JSON` entries. Do NOT re-parse the task description for tags — the flags are authoritative. If `isIntegration` is true, skip Standard Task entirely and jump to Integration Task (below).
+
 **Standard Task** (`Agent(model="{Model}", ...)`):
 ```
 --- START ---
@@ -373,7 +429,7 @@ Success criteria: {ACs from spec relevant to this task}
 {If spec contains ## Domain Model section:
 --- CONTEXT: Domain Model ---
 {Domain Model section content from doing-*.md, extracted via shell injection:
-  DOMAIN_MODEL=!`sed -n '/^## Domain Model$/,/^## [^D]/p' specs/doing-{spec_name}.md | head -n -1 2>/dev/null || echo 'NOT_FOUND'`
+  DOMAIN_MODEL=!`sed -n '/^## Domain Model$/,/^## /p' specs/doing-{spec_name}.md | head -n -1 2>/dev/null || echo 'NOT_FOUND'`
 }
 }
 {If EXISTING_TYPES is non-empty:
@@ -395,7 +451,7 @@ AC-2:skip:reason here (if applicable)
 AC_COVERAGE_END
 ```
 Format: one line per AC with either `AC-N:done` or `AC-N:skip:reason`. Omit this block if the spec has no acceptance criteria.
-DECISIONS: If you made non-obvious choices, append to the LAST LINE BEFORE TASK_STATUS:
+DECISIONS: If you made non-obvious choices, cite with [APPROACH]. Append to the LAST LINE BEFORE TASK_STATUS:
 DECISIONS: [TAG] {decision} — {rationale} | [TAG] {decision2} — {rationale2}
 Tags:
   [APPROACH] — chose X over Y (architectural/design choice)
@@ -404,6 +460,7 @@ Tags:
   [FUTURE] — deferred X because Y; revisit when Z
   [UPDATE] — changed prior decision from X to Y because Z
 Skip for trivial/mechanical changes.
+Files: List every file you modified or created, one per line, in the format `Files: path/to/file.ts, path/to/other.ts`. This is required so the orchestrator can detect file conflicts across concurrent tasks.
 Last line of your response MUST be: TASK_STATUS:pass (if successful) or TASK_STATUS:fail (if failed) or TASK_STATUS:revert (if reverted)
 ```
 
@@ -416,6 +473,7 @@ Integration ACs: {list from PLAN.md}
 Specs involved: {spec file paths}
 Interface Map: {from integration task detail}
 Contract Risks: {from integration task detail}
+LSP documentSymbol on Impact files → Read with offset/limit on relevant ranges only (never read full files)
 --- END ---
 RULES:
 - Fix the CONSUMER to match the PRODUCER's declared interface. Never weaken the producer.
@@ -438,7 +496,28 @@ Last line: TASK_STATUS:pass or TASK_STATUS:fail
 
 **Bootstrap:** `BOOTSTRAP: Write tests for edit_scope files. Do NOT change implementation. Commit as test({spec}): bootstrap. Last line: TASK_STATUS:pass or TASK_STATUS:fail`
 
-**Spike:** `{task_id} [SPIKE]: {hypothesis}. Files+Spec. {reverted warnings}. Minimal spike. Commit as spike({spec}): {desc}. If you discovered constraints, rejected approaches, or made assumptions, report: DECISIONS: [TAG] {finding} — {why it matters} (use PROVISIONAL for "works but needs revisit", ASSUMPTION for "assumed X; if wrong Y breaks", APPROACH for definitive choices). Last line: TASK_STATUS:pass or TASK_STATUS:fail`
+**Wave Test** (`Agent(model="sonnet")`):
+```
+--- START ---
+{task_id} [TEST]: Write tests for {spec_name}. Files+Spec.
+Pre-existing test files:
+{SNAPSHOT_FILES}
+
+Existing test function names (do NOT duplicate these):
+{EXISTING_TEST_NAMES}
+--- MIDDLE ---
+Spec: {spec_path}
+Edit scope: {edit_scope}
+--- END ---
+RULES:
+- Use the `Read` tool (or `git diff HEAD~1`) to inspect what the implementation changed before writing tests.
+- Do not duplicate tests that already exist in the pre-existing test files listed above.
+- Do not modify pre-existing test files — write new test files only.
+- Commit as test({spec}): {description}.
+Last line of your response MUST be: TASK_STATUS:pass (if successful) or TASK_STATUS:fail (if failed)
+```
+
+**Spike**: `{task_id} [SPIKE]: {hypothesis}. Files+Spec. {reverted warnings}. Minimal spike. Commit as spike({spec}): {desc}. If you discovered constraints, rejected approaches, or made assumptions, report: DECISIONS: [TAG] {finding} — {why it matters} (use PROVISIONAL for "works but needs revisit", ASSUMPTION for "assumed X; if wrong Y breaks", APPROACH for definitive choices). Last line: TASK_STATUS:pass or TASK_STATUS:fail`
 
 **Optimize Task** (`Agent(model="opus")`):
 ```
@@ -448,6 +527,7 @@ Current: {val} (baseline: {b}, best: {best}). Target: {t} ({dir}). Metric: {cmd}
 CONSTRAINT: ONE atomic change.
 --- MIDDLE ---
 Last 5 cycles + failed hypotheses + Impact/deps.
+LSP documentSymbol on Impact files → Read with offset/limit on relevant ranges only (never read full files)
 --- END ---
 {Learnings}. ONE change + commit. No metric run, no multiple changes.
 Last line of your response MUST be: TASK_STATUS:pass or TASK_STATUS:fail or TASK_STATUS:revert
@@ -463,6 +543,7 @@ Current/Target. Role instruction:
   ingenua: "Ignore prior. Fresh approach."
 --- MIDDLE ---
 Full history + all failed hypotheses.
+LSP documentSymbol on Impact files → Read with offset/limit on relevant ranges only (never read full files)
 --- END ---
 ONE atomic change. Commit. STOP.
 Last line of your response MUST be: TASK_STATUS:pass or TASK_STATUS:fail or TASK_STATUS:revert
@@ -498,7 +579,18 @@ Skills: `atomic-commits`, `browse-fetch`. Agents: Implementation (`general-purpo
 | sonnet/medium | `Agent(model="sonnet")` | `Direct and efficient. Explain only non-obvious logic.` |
 | opus/high | `Agent(model="opus")` | _(none)_ |
 
-**Checkpoint:** `.deepflow/checkpoint.json`: `{"completed_tasks":["T1"],"current_wave":2,"worktree_path":"...","worktree_branch":"df/..."}`
+**Checkpoint:** `.deepflow/checkpoint.json`:
+```json
+{
+  "completed_tasks": ["T1"],
+  "current_wave": 2,
+  "spec_worktrees": {
+    "upload":   {"path": ".deepflow/worktrees/upload",   "branch": "df/upload"},
+    "auth":     {"path": ".deepflow/worktrees/auth",     "branch": "df/auth"}
+  }
+}
+```
+One entry per `doing-*` spec in scope. `--continue` rehydrates this map before wave scheduling.
 
 ## Failure Handling
 

package/src/commands/df/plan.md

@@ -230,7 +230,7 @@ You are a spec planner. Your job is to independently analyze a spec and produce
 2. **Compute spec layer** — determine L0–L3 based on sections present (see layer rules below)
 3. **Check experiments** — glob `.deepflow/experiments/{topic}--*` for past spikes
 4. **Explore the codebase** — detect code style, patterns, integration points relevant to this spec
-5. **Impact analysis** (L3 only) — LSP-first blast radius for files in scope
+5. **Impact analysis** (L3 only) — LSP documentSymbol on impact files → Read with offset/limit on relevant ranges only (never read full files)
 6. **Targeted exploration** — follow `templates/explore-agent.md` spawn rules for post-LSP gaps
 7. **Generate tasks** — produce a mini-plan following the output format below
 
@@ -349,11 +349,17 @@ If no shared interfaces found, return:
 
 **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.
+For each group of specs sharing interfaces, generate ONE integration task per interface cluster.
+
+**Placement (CRITICAL for worktree routing):** Integration tasks must be placed under the **consumer spec's** `### {consumer-spec-name}` section in the consolidated PLAN.md, NOT at the end of the file and NOT under their own header. `bin/wave-runner.js` assigns `task.spec` from the nearest preceding `### ` header, and `/df:execute` uses that field to route the task to the correct per-spec worktree (`SPEC_WORKTREES[task.spec].path`). If an integration task lands under a header that is not a real spec (e.g. `### Integration`), execute will fail to resolve a worktree and defer the task.
+
+**Consumer selection:** The "consumer" is the spec that reads/calls the interface (e.g. frontend consumes API produced by backend → frontend is consumer). The fix-the-consumer rule in execute.md §6 Integration Task template means the integration agent will modify consumer-side code, which matches the consumer's worktree. If a cluster has multiple consumers, emit one integration task per consumer under each consumer's section.
+
+The `[INTEGRATION]` tag is parsed deterministically by `bin/wave-runner.js` and surfaced as `isIntegration: true` in its JSON output; execute.md §6 uses that flag (not the task description) to pick the Integration Task prompt.
 
 **Integration task format:**
 ```markdown
-- [ ] **T{N}** [INTEGRATION]: Verify {spec_a} ↔ {spec_b} contracts
+- [ ] **T{N}** [INTEGRATION]: Verify {producer_spec} ↔ {consumer_spec} contracts
   - Files: {files at integration boundaries — API handlers, adapters, shared types, migrations}
   - Integration ACs:
     - End-to-end flow: {producer} → {consumer} works with real data
@@ -396,10 +402,9 @@ 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.
+## Spec content
+<!-- {spec_content} — injected by orchestrator before spawning; do NOT use Read tool on the spec -->
+{spec_content}
 
 ## Agent summaries (from §3 parallel agents)
 

package/src/commands/df/spec.md

@@ -55,6 +55,7 @@ Spawn reasoner agent (`subagent_type: "reasoner"`, `model: "opus"`). The reasone
 - Flags conflicts with existing code
 - Verifies every REQ-N has a corresponding AC; flags uncovered requirements
 - Flags vague/untestable requirements (e.g., "should be fast" without a metric)
+- If Explore agents found type definitions or interfaces relevant to this spec, include a ## Domain Model section with Key Types (signatures only) and Ubiquitous Language (domain terms). Omit if no relevant types found.
 
 ### 4. GENERATE SPEC
 

package/src/commands/df/verify.md

@@ -221,6 +221,8 @@ Objective: ... | Approach: ... | Why it worked: ... | Files: ...
 - Don't auto-fix — add fix tasks to PLAN.md, then `/df:execute --continue`
 - Capture learnings for significant approaches
 - **Terse output** — Output ONLY the compact report format (section 3)
+- **No LSP diagnostics** — Use ONLY build/test command exit codes and output for L0/L4. Do NOT use the LSP tool to collect TypeScript diagnostics — worktree environments have incomplete `node_modules` symlinks that produce false-positive module-resolution errors (2307, 2875). If the build command exits 0, L0 passes — do not second-guess it with LSP.
+- **No narration of false positives** — Never output diagnostics and then explain they are false positives. If you know they are false positives, suppress them entirely. Wasted output tokens cost money.
 
 ## Post-Verification: Worktree Merge & Cleanup
 

package/src/skills/repo-inspect/SKILL.md

@@ -0,0 +1,205 @@
+---
+name: repo-inspect
+description: Produces structured JSON intelligence for a remote GitHub repo — fetches metadata and file tree via gh api, reads key files via WebFetch. No local clone. Use when evaluating an unfamiliar repo before planning integration work.
+context: fork
+allowed-tools: [Bash, WebFetch]
+---
+
+# Repo-Inspect
+
+Inspect a GitHub repository and emit a single JSON object describing its architecture. No clones, no tmpdir, no local filesystem writes.
+
+**Input:** `{owner}/{repo}` or a full GitHub URL (e.g., `https://github.com/owner/repo`).
+**Output:** Raw JSON only — no markdown, no commentary.
+
+---
+
+## Protocol
+
+### Step 0 — Parse Input
+
+Strip `https://github.com/` prefix if present. Extract `{owner}` and `{repo}` from the remaining `owner/repo` string.
+
+### Step 1 — Fetch Repo Metadata (1 Bash call)
+
+```bash
+gh api repos/{owner}/{repo}
+```
+
+Extract: `description`, `language`, `topics`, `default_branch`, `stargazers_count`, `forks_count`.
+
+On error (non-zero exit or JSON with `message` field indicating 404/403):
+```json
+{"error": "api_failed", "message": "<gh api error text>"}
+```
+Stop and return this error JSON immediately.
+
+### Step 2 — Fetch Full File Tree (1 Bash call)
+
+```bash
+gh api "repos/{owner}/{repo}/git/trees/{default_branch}?recursive=1"
+```
+
+Parse `tree[]` array. Each item has: `path`, `type` (`blob`|`tree`), `size`.
+
+If tree is truncated (`truncated: true`), note it but proceed — the tree API returns up to ~100K entries which covers virtually all repos.
+
+### Step 3 — Language Detection
+
+Scan tree paths for manifest files in priority order:
+
+| Manifest | Language |
+|---|---|
+| `Cargo.toml` | Rust |
+| `package.json` | JavaScript/TypeScript |
+| `pyproject.toml` or `setup.py` or `requirements.txt` | Python |
+| `go.mod` | Go |
+| `pom.xml` or `build.gradle` | Java |
+| `mix.exs` | Elixir |
+| `Gemfile` | Ruby |
+| `build.zig` | Zig |
+| `CMakeLists.txt` | C/C++ |
+
+Use the **first match** (highest priority). If no manifest found, fall back to `language` field from Step 1 metadata.
+
+Record: `detected_language`, `manifest_path` (path of matched manifest, or null).
+
+### Step 4 — File Selection (3–6 files)
+
+Build a prioritized list of files to fetch. Select 3–6 total:
+
+1. **README** — find `README.md` or `README.rst` or `README` in tree root (depth 0). Always include if present.
+2. **Manifest** — the manifest file detected in Step 3. Always include if present.
+3. **Primary entry point** — search tree for (in order): `src/main.*`, `src/lib.*`, `src/index.*`, `index.*`, `app.*`, `main.*`. Pick the first match at the shallowest depth.
+4. **Supplemental files** — from remaining blobs: prefer shallowest paths, then largest `size`. Pick source files (`.rs`, `.ts`, `.js`, `.py`, `.go`, `.java`, `.ex`, `.rb`, `.zig`, `.c`, `.cpp`, `.h`). Fill up to 6 total.
+
+For monorepos (detected when tree contains `packages/*/`, `crates/*/`, `apps/*/` directories, or manifest workspace field): select 1-2 representative sub-package manifests/entry points instead of generic supplemental files.
+
+### Step 5 — Fetch File Contents (3–6 WebFetch calls)
+
+For each selected file path, fetch:
+
+```
+https://raw.githubusercontent.com/{owner}/{repo}/{default_branch}/{path}
+```
+
+Use WebFetch. If a fetch fails (404 or network error), skip that file and note it. Do not retry.
+
+Collect: list of `{path, content}` pairs for all successfully fetched files.
+
+### Step 6 — Extract Intelligence from Fetched Content
+
+From manifest content (if fetched):
+
+- **dependency_count**: Count entries in `[dependencies]` (Cargo.toml), `dependencies` + `devDependencies` keys (package.json), `[tool.poetry.dependencies]` (pyproject.toml), `require` directives (go.mod/Gemfile), `<dependency>` tags (pom.xml). Use 0 if manifest not fetched.
+- **test_framework**: Check dev-dependencies for known test frameworks:
+  - JS/TS: `jest`, `vitest`, `mocha`, `jasmine`, `tap`, `ava`
+  - Python: `pytest`, `unittest` (stdlib), `nose`
+  - Rust: built-in (`#[test]`), `rstest`, `proptest`
+  - Go: built-in (`testing` package)
+  - Java: `junit`, `testng`
+  - Ruby: `rspec`, `minitest`
+  - Elixir: built-in (`ExUnit`)
+  Also check tree for `test/`, `tests/`, `spec/`, `__tests__/` directories as corroboration.
+- **monorepo**: true if tree contains at least 2 of `packages/`, `crates/`, `apps/`, `libs/` top-level dirs, OR if manifest has workspace/workspaces field.
+
+From README content (if fetched):
+- Extract the first non-heading paragraph as a candidate for `purpose`. Trim to ≤ 200 chars.
+
+Fallback for `purpose`: use repo `description` from Step 1 metadata.
+
+### Step 7 — Derive key_modules
+
+From the tree blob paths, identify directories containing 2+ source files (files with extensions `.rs`, `.ts`, `.js`, `.tsx`, `.jsx`, `.py`, `.go`, `.java`, `.ex`, `.rb`, `.zig`, `.c`, `.cpp`, `.h`, `.swift`, `.kt`).
+
+Algorithm:
+1. For each blob, extract parent directory path.
+2. Count source files per directory.
+3. Keep directories with count >= 2.
+4. Sort by file count descending, then by path depth ascending (shallower = more significant).
+5. Take up to 10 modules.
+6. Strip common prefixes (e.g., if all modules share `src/`, keep `src/` as a module too).
+
+Return directory names (last path segment) for the `key_modules` array. If fewer than 3 candidate directories exist, include directories with 1 source file to reach 3, or return what's available.
+
+### Step 8 — Derive concepts_applicable
+
+Based on language, test framework, monorepo status, and key module names, suggest applicable engineering concepts. Examples:
+
+- Monorepo → `"workspace-management"`, `"cross-package-testing"`
+- Rust → `"ownership-model"`, `"cargo-workspace"` (if monorepo)
+- TypeScript → `"type-safety"`, `"module-resolution"`
+- Has `auth` module → `"authentication-patterns"`
+- Has `db` or `models` module → `"data-modeling"`
+- Has `api` or `routes` module → `"rest-api-design"`
+- Has tests → `"tdd"` or `"bdd"` (if rspec/jasmine)
+
+Limit to 3–7 concepts. These are suggestions for the caller — not exhaustive.
+
+### Step 9 — Confidence Score
+
+Set `confidence` based on data quality:
+
+| Condition | Confidence |
+|---|---|
+| README + manifest + entry point all fetched | `high` |
+| README or manifest fetched, but not both | `medium` |
+| Neither README nor manifest fetched | `low` |
+
+### Step 10 — Emit JSON Output
+
+Output **exactly one JSON object** with no surrounding text, no markdown code fences, no comments:
+
+```json
+{
+  "repo": "{owner}/{repo}",
+  "purpose": "<first non-heading README paragraph or repo description, ≤200 chars>",
+  "architecture": {
+    "language": "<detected language>",
+    "entry_points": ["<relative paths of main/lib/index files>"],
+    "key_modules": ["<directory names with 2+ source files>"],
+    "dependencies_count": 0,
+    "test_framework": "<framework name or 'unknown'>"
+  },
+  "concepts_applicable": ["<concept1>", "<concept2>"],
+  "files_inspected": ["<path1>", "<path2>"],
+  "confidence": "high|medium|low"
+}
+```
+
+**Critical:** The very last thing you output must be this JSON object and nothing else. Do not wrap in code blocks. Do not add explanation.
+
+---
+
+## Error Handling
+
+| Scenario | Action |
+|---|---|
+| `gh api` returns non-zero exit for metadata | Return `{"error": "api_failed", "message": "<stderr>"}` and stop |
+| `gh api` returns 404 JSON | Return `{"error": "api_failed", "message": "Repository not found or not accessible"}` |
+| Tree fetch fails | Return `{"error": "tree_failed", "message": "<stderr>"}` and stop |
+| All WebFetch calls fail | Set confidence to "low", proceed with tree-only analysis |
+| Single WebFetch fails | Skip file, continue |
+
+---
+
+## Efficiency Budget
+
+- `gh api` calls: exactly 2 (metadata + tree)
+- WebFetch calls: 3–6 (selected files)
+- Analysis steps: ~5 (no extra Bash calls needed)
+- **Total tool calls: ≤ 20**
+- **Wall time: ≤ 60s**
+- **Tokens: ≤ 30K**
+
+Do not make extra `gh api` calls. Do not fetch files not in the selection list. The tree endpoint returns all paths in one call — no Glob, no Read, no additional listing needed.
+
+---
+
+## Rules
+
+- Never write to local filesystem (no `> file`, no `mktemp`, no `git clone`).
+- Never use Read, Glob, or Grep tools — this skill operates on remote data only.
+- Output raw JSON only — the caller parses it, not reads it as prose.
+- Private repos work automatically via `gh auth` stored token.
+- Strip `context: fork` means this skill's token usage doesn't pollute the caller's context.

package/templates/config-template.yaml

@@ -96,6 +96,9 @@ quality:
   # Timeout in seconds to wait for the dev server to become ready (default: 30)
   browser_timeout: 30
 
+  # Minimum quality score threshold for harness verification (0.0-1.0, default: 0.6)
+  harness_min_score: 0.6
+
 # Ratchet configuration for /df:verify health gate
 # Ratchet snapshots baseline metrics (tests passing, coverage, type checks) before execution
 # and ensures subsequent runs don't regress. These overrides control which commands ratchet monitors.

package/templates/spec-template.md

@@ -43,6 +43,23 @@
 
 - [Explicitly excluded: e.g., "Video upload is NOT included"]
 
+## Domain Model
+
+<!-- Optional. Define the core entities and vocabulary. -->
+
+### Key Types
+
+```typescript
+// Core domain types and entities
+```
+
+### Ubiquitous Language
+
+- **Term**: Definition
+- **Term**: Definition
+
+_Note: Keep to max 15 terms for clarity._
+
 ## Acceptance Criteria
 
 - [ ] [Testable criterion: e.g., "User can upload jpg/png/webp files"]