deepflow 0.1.97 → 0.1.99

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "deepflow",
-  "version": "0.1.97",
+  "version": "0.1.99",
   "description": "Doing reveals what thinking can't predict — spec-driven iterative development for Claude Code",
   "keywords": [
     "claude",

package/src/commands/df/execute.md

@@ -10,7 +10,7 @@ description: Execute tasks from PLAN.md with agent spawning, ratchet health chec
 You are a coordinator. Spawn agents, run ratchet checks, update PLAN.md. Never implement code yourself.
 
 **NEVER:** Read source files, edit code, use TaskOutput, use EnterPlanMode, use ExitPlanMode
-**ONLY:** Read PLAN.md, read specs/doing-*.md, spawn background agents, run ratchet health checks, update PLAN.md, write `.deepflow/decisions.md`
+**ONLY:** Read PLAN.md, read specs/doing-*.md, read `.deepflow/plans/doing-*.md` for task detail, spawn background agents, run ratchet health checks, update PLAN.md, write `.deepflow/decisions.md`
 
 ## Core Loop (Notification-Driven)
 
@@ -79,6 +79,12 @@ If `SNAPSHOT_COUNT` is `0` (zero test files found), MUST spawn bootstrap agent b
 
 Load PLAN.md (required), specs/doing-*.md, .deepflow/config.yaml. Missing → "No PLAN.md found. Run /df:plan first."
 
+**Per-task detail files** (shell injection — load once after PLAN.md):
+```
+PLAN_TASK_FILES=!`ls .deepflow/plans/doing-*.md 2>/dev/null | tr '\n' ' ' || echo 'NOT_FOUND'`
+```
+When `PLAN_TASK_FILES` is not `NOT_FOUND`, each file `.deepflow/plans/doing-{task_id}.md` contains the full task detail block (Steps, ACs, Impact) for that task. Load a task's detail file on demand when building its agent prompt (§6), falling back to the PLAN.md inline block if the file is absent.
+
 ### 2.5. REGISTER NATIVE TASKS
 
 For each `[ ]` task: `TaskCreate(subject: "{task_id}: {description}", activeForm: "{gerund}", description: full block)`. Store task_id → native ID. Set deps via `TaskUpdate(addBlockedBy: [...])`. `--continue` → only remaining `[ ]` items.
@@ -89,17 +95,34 @@ Warn if unplanned `specs/*.md` (excluding doing-/done-) exist (non-blocking).
 
 **Wave computation (shell injection — do NOT compute manually):**
 ```
+WAVE_JSON=!`node bin/wave-runner.js --json --plan PLAN.md 2>/dev/null || echo 'WAVE_ERROR'`
+```
+`WAVE_JSON` is structured JSON (produced by T1's `--json` flag). Parse it to determine the current wave and scheduling decisions:
+```json
+{
+  "waves": [
+    {"wave": 1, "tasks": [{"id": "T1", "description": "...", "files": ["..."], "isolation": "worktree"}, ...]},
+    {"wave": 2, "tasks": [...]}
+  ],
+  "blocked": [{"id": "T3", "blockedBy": ["T2"]}],
+  "done": ["T0"]
+}
+```
+Use `waves[0].tasks` as the ready set for the current wave. Use `isolation` field from each task entry (if present) to determine `isolation:` mode when spawning agents. Use `blocked` to identify tasks not yet ready.
+
+**Fallback (text mode):** If `WAVE_JSON` is `WAVE_ERROR` or cannot be parsed as JSON, fall back to text mode:
+```
 WAVE_PLAN=!`node bin/wave-runner.js --plan PLAN.md 2>/dev/null || echo 'WAVE_ERROR'`
 ```
-Parse the output to determine the current wave. Output format:
+Text output format:
 ```
 Wave 1: T1 — description, T4 — description
 Wave 2: T2 — description
 ...
 ```
-If output is `WAVE_ERROR` or `(no pending tasks)`, fall back to TaskList where status: "pending" AND blockedBy: empty for wave 1.
+In text fallback: if output is `WAVE_ERROR` or `(no pending tasks)`, fall back to TaskList where status: "pending" AND blockedBy: empty for wave 1.
 
-Ready = tasks listed in Wave 1 of the wave-runner output (cross-referenced with TaskList status: "pending").
+Ready = tasks listed in Wave 1 (cross-referenced with TaskList status: "pending").
 
 ### 5. SPAWN AGENTS
 
@@ -167,10 +190,11 @@ The script handles all health checks internally and outputs structured JSON:
 - **Exit 0 (PASS):** Commit stands. Proceed to §5.6 wave test agent.
 - **Exit 1 (FAIL):** Script already reverted. Set `TaskUpdate(status: "pending")`. Recompute remaining waves:
   ```
-  WAVE_PLAN=!`node bin/wave-runner.js --plan PLAN.md --recalc --failed T{N} 2>/dev/null || echo 'WAVE_ERROR'`
+  WAVE_JSON=!`node bin/wave-runner.js --json --plan PLAN.md --recalc --failed T{N} 2>/dev/null || echo 'WAVE_ERROR'`
   ```
+  (Fall back to text mode if `--json` is unavailable: `node bin/wave-runner.js --plan PLAN.md --recalc --failed T{N}`)
   Report: `"✗ T{n}: reverted"`.
-- **Exit 2 (SALVAGEABLE):** Spawn `Agent(model="haiku")` to fix lint/typecheck issues. Re-run `node 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.
 
 **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).
@@ -329,6 +353,12 @@ REPEAT:
 
 **Common preamble (all):** `Working directory: {worktree_absolute_path}. All file ops use this path. Commit format: {type}({spec}): {desc}`
 
+**Task detail loading (before building agent prompt):** Check for `.deepflow/plans/doing-{task_id}.md` (shell injection):
+```
+TASK_DETAIL=!`cat .deepflow/plans/doing-{task_id}.md 2>/dev/null || echo 'NOT_FOUND'`
+```
+If `TASK_DETAIL` is not `NOT_FOUND`, use it as the full Middle section (Steps, ACs, Impact) in the agent prompt, overriding the inline PLAN.md block. If `NOT_FOUND`, fall back to the inline PLAN.md task block.
+
 **Standard Task** (`Agent(model="{Model}", ...)`):
 ```
 --- START ---
@@ -343,6 +373,7 @@ spike_results:
 }
 Success criteria: {ACs from spec relevant to this task}
 --- MIDDLE (omit for low effort; omit deps for medium) ---
+{TASK_DETAIL if available, else inline block:}
 Impact: Callers: {file} ({why}) | Duplicates: [active→consolidate] [dead→DELETE] | Data flow: {consumers}
 Prior tasks: {dep_id}: {summary}
 Steps: 1. chub search/get for APIs 2. LSP findReferences, add unlisted callers 3. Read all Impact files 4. Implement 5. Commit
@@ -501,7 +532,7 @@ Skills: `atomic-commits`, `browse-fetch`. Agents: Implementation (`general-purpo
 
 | Fields | Agent | Preamble |
 |--------|-------|----------|
-| haiku/low | `Agent(model="haiku")` | `Maximally efficient: skip explanations, minimize tool calls, straight to implementation.` |
+| sonnet/low | `Agent(model="sonnet")` | `Maximally efficient: skip explanations, minimize tool calls, straight to implementation.` |
 | sonnet/medium | `Agent(model="sonnet")` | `Direct and efficient. Explain only non-obvious logic.` |
 | opus/high | `Agent(model="opus")` | _(none)_ |
 

package/src/commands/df/plan.md

@@ -127,51 +127,69 @@ Count plannable specs (no `doing-`/`done-` prefix, passed `validateSpec`).
   Re-run /df:plan to process remaining specs.
   ```
 
-#### 4.7.2. Spawn Sub-Agents
+#### 4.7.2. Spawn Sub-Agents (Thin Dispatcher)
 
 For each plannable spec (up to 5), spawn a **parallel non-background** `Task(subagent_type="default", model="sonnet")` call. All calls are independent — spawn them simultaneously.
 
-Each sub-agent prompt MUST include:
-
-1. **Layer-gating rules** (from §1.5): The spec's computed layer and which task types are allowed
-2. **Experiment check results** (from §2): Past experiments for this spec's topic — `--passed.md`, `--failed.md`, `--active.md` status and extracted next-hypothesis
-3. **Project context** (from §3): Code style, patterns, integration points detected for this project
-4. **Impact analysis instructions** (from §4, L3 specs only): LSP-first blast radius search for each file in the task's `Files:` list
-5. **Targeted exploration instructions** (from §4.5): Follow `templates/explore-agent.md` spawn rules
-6. **The spec content**: Full text of that spec file
-7. **Format enforcement clause**:
-   ```
-   OUTPUT FORMAT — MANDATORY (no deviations):
-   Return ONLY a markdown task list. Use local T-numbering starting at T1.
-   Each task MUST follow this exact format:
-
-   ### {spec-name}
-
-   - [ ] **T{N}**: {Task description}
-     - Files: {comma-separated file paths}
-     - Blocked by: none | T{N}[, T{M}...]
-
-   Optional fields (add when applicable):
-     - Model: haiku | sonnet | opus
-     - Effort: low | medium | high
-     - Impact: {blast radius details, L3 only}
-     - Optimize: {metric block, for metric ACs only}
-
-   Rules:
-   - "Blocked by: none" is required (not "N/A", not empty)
-   - T-numbers are local to this spec (T1, T2, T3...)
-   - One task = one atomic commit
-   - Spike tasks use: **T{N}** [SPIKE]: {description}
-   - L0-L1 specs: ONLY spike tasks allowed
-   - L2+ specs: spikes + implementation tasks allowed
-   - L3 specs: include Impact: blocks from impact analysis
-   ```
-
-#### 4.7.3. Collect Mini-Plans
+**The master orchestrator is a thin dispatcher.** Each sub-agent receives ONLY the spec file path — no pre-computed context, no spec content, no impact analysis, no experiment results.
+
+Each sub-agent prompt:
+
+```
+You are a spec planner. Your job is to independently analyze a spec and produce a mini-plan.
+
+## Spec file
+{spec_file_path}
+
+## Instructions
+
+1. **Read the spec** — use Read tool on the spec file path above
+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
+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
+
+## Layer-gating rules
+| Layer | Sections present | Allowed task types |
+|-------|------------------|--------------------|
+| L0 | Objective | Spikes only |
+| L1 | + Requirements | Spikes only (better targeted) |
+| L2 | + Acceptance Criteria | Spikes + Implementation |
+| L3 | + Constraints, Out of Scope, Technical Notes | Spikes + Implementation + Impact analysis + Optimize |
+
+## OUTPUT FORMAT — MANDATORY (no deviations)
+Return ONLY a markdown task list. Use local T-numbering starting at T1.
+Each task MUST follow this exact format:
+
+### {spec-name}
+
+- [ ] **T{N}**: {Task description}
+  - Files: {comma-separated file paths}
+  - Blocked by: none | T{N}[, T{M}...]
+
+Optional fields (add when applicable):
+  - Model: haiku | sonnet | opus
+  - Effort: low | medium | high
+  - Impact: {blast radius details, L3 only}
+  - Optimize: {metric block, for metric ACs only}
+
+Rules:
+- "Blocked by: none" is required (not "N/A", not empty)
+- T-numbers are local to this spec (T1, T2, T3...)
+- One task = one atomic commit
+- Spike tasks use: **T{N}** [SPIKE]: {description}
+- L0-L1 specs: ONLY spike tasks allowed
+- L2+ specs: spikes + implementation tasks allowed
+- L3 specs: include Impact: blocks from impact analysis
+```
+
+#### 4.7.3. Collect & Persist Mini-Plans
 
 Each sub-agent returns a mini-plan string (markdown). Collect all return values.
 
-**Graceful degradation (AC-11):** For each sub-agent result, check for failure conditions:
+**Graceful degradation (AC-10):** For each sub-agent result, check for failure conditions:
 - Sub-agent threw an error or returned a non-string value → log warning, skip spec
 - Output is empty (whitespace only) → log warning, skip spec
 - Output contains no task items (no `- [ ] **T` pattern) → log warning (unparseable), skip spec
@@ -183,11 +201,12 @@ Warning format:
 
 Continue processing remaining specs regardless of individual failures. Only successfully parsed mini-plans are stored.
 
-- Store results as an array of `{ specName, miniPlan }` objects (successfully parsed only) for consolidation by §5.
+**Persist to disk (REQ-3):** For each successful mini-plan, write to `.deepflow/plans/doing-{specName}.md`. Create `.deepflow/plans/` directory if it doesn't exist.
+
 - If ALL sub-agents fail: report error, abort plan generation.
-- If at least 1 succeeds: continue to §5 with successful mini-plans only.
+- If at least 1 succeeds: continue to §5 with successful mini-plans on disk.
 
-**Flow after fan-out:** The collected mini-plans are passed to §5 for consolidation (global renumbering, cross-spec conflict detection, prioritization). §5 handles both the single-spec monolithic path and the multi-spec consolidation path.
+**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.
 
 ### 5. COMPARE & PRIORITIZE
 
@@ -213,54 +232,55 @@ Then apply §5.5 routing matrix. Continue to §6.
 
 #### 5B. MULTI-SPEC CONSOLIDATOR (FAN-OUT PATH)
 
-**When:** >1 plannable spec (§4.7 produced mini-plans).
+**When:** >1 plannable spec (§4.7 produced mini-plans in `.deepflow/plans/`).
 
 **This is the ONLY Opus invocation in the fan-out path** (REQ-12). Sub-agents in §4.7 use Sonnet.
 
-Spawn a single `Task(subagent_type="reasoner", model="opus")` with the following prompt:
+**Input:** Mini-plan files in `.deepflow/plans/doing-*.md`. The consolidator must NOT modify these files (REQ-5).
+
+**Architecture:** Mechanical work (T-id renumbering, file-conflict detection) is delegated to `bin/plan-consolidator.js`. Opus handles ONLY cross-spec prioritization and summary narrative.
+
+##### Step 1: Run plan-consolidator (mechanical — no LLM)
+
+Shell-inject the consolidator output:
+
+`` !`node bin/plan-consolidator.js --plans-dir .deepflow/plans/ 2>/dev/null` ``
+
+This produces the `## Tasks` section with:
+- Globally sequential T-ids (no gaps, no duplicates) — AC-4
+- Remapped `Blocked by` references (local → global)
+- `[file-conflict: {filename}]` annotations on cross-spec file overlaps
+- Mini-plan files left byte-identical (read-only) — AC-5
+
+If the consolidator output is empty or contains `(no mini-plan files found` → abort, report error.
+
+##### Step 2: Opus prioritization & summary (single invocation)
+
+Spawn a single `Task(subagent_type="reasoner", model="opus")` with the consolidated tasks from Step 1:
 
 ```
-You are the plan consolidator. You receive mini-plans from multiple spec-planning agents.
-Your job is to merge them into a single globally-numbered PLAN.md.
+You are the plan prioritizer. The mechanical consolidation (global T-numbering, file-conflict detection) is already done. Do NOT renumber tasks or modify T-ids.
 
-## Input mini-plans
+## Consolidated tasks (from plan-consolidator)
 
-{for each entry in miniPlans array:}
-### {specName}
-{miniPlan content}
-{end for}
+{paste consolidator stdout here}
 
-## Instructions
+## Spec files
 
-### Step 1: Spec Priority Ordering
-Sort specs for global numbering. Use this priority:
-1. Specs with no cross-spec file overlaps first (independent work)
-2. Specs with overlaps ordered by dependency direction (depended-on first)
-3. Alphabetical as tiebreaker
-
-### Step 2: Global T-Number Assignment
-Assign sequential global T-numbers (T1, T2, ..., TN) with NO gaps and NO duplicates.
-- Process specs in priority order from Step 1
-- Within each spec, preserve the local task ordering
-- Translate all intra-spec `Blocked by: T{local}` references to global T-IDs
-
-### Step 3: Cross-Spec File Conflict Detection
-Build a map: `file → [global task IDs]`.
-For each file appearing in >1 task across different specs:
-- Add `Blocked by` from the later task → the earlier task
-- Append `[file-conflict: {filename}]` annotation to the Blocked by line
-- Skip if a dependency already exists (direct or transitive)
-- Chain only: T5→T3, not T5→T1+T3 (block on nearest earlier task for that file)
-
-### Step 4: Requirement Mapping
-For each spec, map requirements to DONE/PARTIAL/MISSING/CONFLICT. Flag spec gaps.
+{for each plannable spec: spec filename and its Requirements + Acceptance Criteria sections}
 
-### Step 5: Metric AC Detection
-Scan ACs for pattern `{metric} {operator} {number}[unit]`.
-- Match → flag as metric AC (for §6.5 Optimize task generation)
-- Ambiguous ("fast", "small") → flag as spec gap
+## Your job — THREE things only
 
-### Step 6: Model + Effort Classification
+### 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.
+
+If reordering is needed, output the recommended spec order. The orchestrator will reorder the mini-plan files in `.deepflow/plans/` (alphabetical prefix rename) and re-run the consolidator.
+
+### 2. Requirement Mapping & Spec Gaps
+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
 Apply routing matrix to each task:
 
 | Task type | Model | Effort |
@@ -282,8 +302,7 @@ Apply routing matrix to each task:
 
 Defaults: sonnet / medium.
 
-### Step 7: Output
-Return the consolidated plan in this exact format:
+## OUTPUT FORMAT — MANDATORY
 
 ## Summary
 
@@ -300,41 +319,20 @@ Return the consolidated plan in this exact format:
 
 ## Tasks
 
-### doing-{spec-name-1}
-
-- [ ] **T1**: {Task description}
-  - Files: {files}
-  - Model: {model}
-  - Effort: {effort}
-  - Blocked by: none
-
-- [ ] **T2**: {Task description}
-  - Files: {files}
-  - Model: {model}
-  - Effort: {effort}
-  - Blocked by: T1
-
-### doing-{spec-name-2}
-
-- [ ] **T3**: {Task description}
-  - Files: {files}
-  - Model: {model}
-  - Effort: {effort}
-  - Blocked by: none
+{Insert the consolidated tasks from plan-consolidator verbatim, adding ONLY `Model:` and `Effort:` lines to each task. Do NOT alter T-ids, descriptions, Files, Blocked by, or conflict annotations.}
 
 Rules:
-- T-numbers MUST be globally sequential (T1...TN), no gaps, no duplicates
-- Group tasks under `### doing-{spec-name}` headers
-- Preserve all optional fields from mini-plans (Impact:, Optimize:, etc.)
-- [file-conflict: {filename}] annotations are REQUIRED for cross-spec file overlaps
-- "Blocked by: none" is required (not "N/A", not empty)
+- Do NOT renumber T-ids — they are already globally sequential from plan-consolidator
+- Do NOT modify Blocked by lines or conflict annotations — they are mechanical outputs
+- ONLY add Model: and Effort: lines per the routing matrix
+- Preserve all existing fields (Impact:, Optimize:, tags, etc.)
 - Spike tasks keep their [SPIKE] or [OPTIMIZE] markers
 ```
 
 **Post-consolidation:**
-- The orchestrator receives the consolidator's output as structured PLAN.md content
-- Mini-plans are ephemeral — they exist only as sub-agent return values, never written to disk (REQ-7)
-- §8 cleanup and §9 output/rename run after this step in the orchestrator (REQ-13)
+- The orchestrator receives the Opus output as structured PLAN.md content
+- Mini-plans persist in `.deepflow/plans/doing-{name}.md` for reuse by `/df:execute` (REQ-3, REQ-7)
+- §8 cleanup and §9 output/rename run after this step in the orchestrator
 
 ### 5.5. CLASSIFY MODEL + EFFORT PER TASK
 
@@ -344,12 +342,12 @@ Rules:
 
 | Task type | Model | Effort |
 |-----------|-------|--------|
-| Bootstrap (scaffold, config, rename) | `haiku` | `low` |
+| Bootstrap (scaffold, config, rename) | `sonnet` | `low` |
 | browse-fetch (doc retrieval) | `haiku` | `low` |
-| Single-file simple addition | `haiku` | `high` |
+| Single-file simple addition | `sonnet` | `medium` |
 | Multi-file with clear specs | `sonnet` | `medium` |
-| Bug fix (clear repro) | `sonnet` | `medium` |
-| Bug fix (unclear cause) | `sonnet` | `high` |
+| Bug fix (clear repro) | `opus` | `medium` |
+| Bug fix (unclear cause) | `opus` | `high` |
 | Spike / validation | `sonnet` | `high` |
 | Optimize (metric AC) | `opus` | `high` |
 | Feature work (well-specced) | `sonnet` | `medium` |

package/src/commands/df/verify.md

@@ -196,4 +196,4 @@ Objective: ... | Approach: ... | Why it worked: ... | Files: ...
 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.
 
-Output: `✓ Merged → main | ✓ Cleaned worktree | ✓ Spec complete | ✓ Cleaned PLAN.md | Workflow complete! Ready: /df:spec <name>`
+Output: `✓ Merged → main | ✓ Cleaned worktree | ✓ Spec → done | ✓ Decisions extracted | ✓ Cleaned PLAN.md | Workflow complete! Ready: /df:spec <name>`