deepflow 0.1.109 → 0.1.111

package/bin/wave-runner.js

@@ -83,9 +83,11 @@ function parsePlan(text) {
     }
 
     // Match pending task header: - [ ] **T{N}**...
-    const taskMatch = line.match(/^\s*-\s+\[\s+\]\s+\*\*T(\d+)\*\*(?:\s+\[[^\]]*\])?[:\s]*(.*)/);
+    // Captures optional [TAG] as group 2 (e.g. INTEGRATION, SPIKE, OPTIMIZE)
+    const taskMatch = line.match(/^\s*-\s+\[\s+\]\s+\*\*T(\d+)\*\*(?:\s+\[([^\]]*)\])?[:\s]*(.*)/);
     if (taskMatch) {
-      const rest = taskMatch[2].trim();
+      const rawTag = taskMatch[2] ? taskMatch[2].trim().toUpperCase() : null;
+      const rest = taskMatch[3].trim();
 
       // Extract inline blocked-by (from " | Blocked by: T1, T2")
       let inlineBlockedBy = [];
@@ -118,6 +120,7 @@ function parsePlan(text) {
         files: null,
         effort: inlineEffort,
         spec: currentSpec,
+        tag: rawTag,
       };
       tasks.push(current);
       continue;
@@ -275,13 +278,14 @@ function buildWaves(tasks, stuckIds) {
 
 /**
  * Format waves as a JSON array of task objects, each with a `wave` field.
- * Fields: id, description, model, files, effort, blockedBy, spec, wave
+ * Fields: id, description, model, files, effort, blockedBy, spec, tag, isIntegration, isSpike, isOptimize, wave
  */
 function formatWavesJson(waves) {
   const result = [];
   for (let i = 0; i < waves.length; i++) {
     const waveNum = i + 1;
     for (const t of waves[i]) {
+      const tag = t.tag || null;
       result.push({
         id: t.id,
         description: t.description || null,
@@ -290,6 +294,10 @@ function formatWavesJson(waves) {
         effort: t.effort || null,
         blockedBy: t.blockedBy,
         spec: t.spec || null,
+        tag: tag,
+        isIntegration: tag === 'INTEGRATION',
+        isSpike: tag === 'SPIKE',
+        isOptimize: tag === 'OPTIMIZE',
         wave: waveNum,
       });
     }

package/bin/worktree-deps.js

@@ -41,38 +41,44 @@ function parseArgs() {
 
 function findNodeModules(root) {
   const results = [];
-
-  // Root node_modules
-  const rootNM = path.join(root, 'node_modules');
-  if (fs.existsSync(rootNM)) {
-    results.push('node_modules');
+  const seen = new Set();
+
+  function addIfNM(relDir) {
+    if (seen.has(relDir)) return;
+    const abs = path.join(root, relDir, 'node_modules');
+    if (fs.existsSync(abs)) {
+      seen.add(relDir);
+      results.push(relDir === '.' ? 'node_modules' : path.join(relDir, 'node_modules'));
+    }
   }
 
-  // Scan common monorepo directory patterns for nested node_modules
-  const monorepoPatterns = ['packages', 'apps', 'libs', 'services', 'modules', 'plugins'];
-
-  for (const dir of monorepoPatterns) {
-    const dirPath = path.join(root, dir);
-    if (!fs.existsSync(dirPath) || !fs.statSync(dirPath).isDirectory()) continue;
-
+  // Root node_modules
+  addIfNM('.');
+
+  // Walk every top-level directory up to 2 levels deep looking for node_modules.
+  // This covers both flat layouts (go/frontend, web/admin) and monorepo layouts
+  // (packages/foo, apps/bar) without hardcoding directory names.
+  function walk(relDir, depth) {
+    if (depth > 2) return;
+    const abs = path.join(root, relDir);
     let entries;
     try {
-      entries = fs.readdirSync(dirPath);
+      entries = fs.readdirSync(abs, { withFileTypes: true });
     } catch (_) {
-      continue;
+      return;
     }
-
     for (const entry of entries) {
-      const entryPath = path.join(dirPath, entry);
-      if (!fs.statSync(entryPath).isDirectory()) continue;
-
-      const nm = path.join(entryPath, 'node_modules');
-      if (fs.existsSync(nm)) {
-        results.push(path.join(dir, entry, 'node_modules'));
-      }
+      if (!entry.isDirectory()) continue;
+      if (entry.name.startsWith('.')) continue;
+      if (entry.name === 'node_modules') continue;
+      const childRel = relDir === '.' ? entry.name : path.join(relDir, entry.name);
+      addIfNM(childRel);
+      walk(childRel, depth + 1);
     }
   }
 
+  walk('.', 1);
+
   return results;
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "deepflow",
-  "version": "0.1.109",
+  "version": "0.1.111",
   "description": "Doing reveals what thinking can't predict — spec-driven iterative development for Claude Code",
   "keywords": [
     "claude",
@@ -42,8 +42,5 @@
   },
   "dependencies": {
     "playwright": "^1.58.2"
-  },
-  "devDependencies": {
-    "typescript": "^6.0.2"
   }
 }

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.
 
-### 1.5.1. SYMLINK DEPENDENCIES
+Then run §1.5.1, §1.6, and §1.7 **per worktree** before any wave spawns.
 
-After worktree creation, symlink `node_modules` from the main repo so TypeScript/LSP/build can resolve dependencies without a full install:
+### 1.5.1. SYMLINK DEPENDENCIES (per worktree)
+
+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,19 @@ 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.
+**NEVER use `isolation: "worktree"`.** Deepflow manages one worktree **per spec** (§1.5). Tasks from the same spec commit to the same branch so wave 2 sees wave 1 commits; tasks from different specs commit to different branches and never interleave. **Spawn ALL ready tasks in ONE message** except file conflicts.
 
-**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}"`
+**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"`.
 
-**≥2 [SPIKE] tasks same problem →** Parallel Spike Probes (§5.7). **[OPTIMIZE] tasks →** Optimize Cycle (§5.9), one at a time.
+**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).
 
 ### 5.5. RATCHET CHECK
 
-Run `node "${HOME}/.claude/bin/ratchet.js"` in the worktree directory after each agent completes:
+Run `node "${HOME}/.claude/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 "${HOME}/.claude/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:
@@ -205,7 +218,7 @@ If no `DECISIONS:` line in agent output → skip silently (mechanical tasks don'
 **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
@@ -255,7 +268,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 +343,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 +372,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 ---
@@ -498,7 +524,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

@@ -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

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