@brunosps00/dev-workflow 0.8.1 → 0.9.0

package/scaffold/skills/dw-execute-phase/references/plan-verification.md

@@ -0,0 +1,156 @@
+# Plan verification — the 6-dimension goal-backward analysis
+
+The `dw-plan-checker` agent verifies that a `tasks.md` will achieve the PRD goal BEFORE execution starts. This document details each dimension's checks, examples, and pass/fail criteria.
+
+## Why pre-execution verification
+
+Mid-execution discovery of plan flaws is expensive: context burned, partial commits to revert, deviation logs to resolve. Pre-execution verification catches the same flaws at zero implementation cost. The trade-off: 1-2 minutes of plan-checker time vs. potentially 30+ minutes of mid-execution rework.
+
+## The 6 dimensions
+
+### 1. Requirement Coverage
+
+**Goal:** every PRD requirement (RF-XX) has at least one task addressing it.
+
+**Steps:**
+1. Extract numbered requirements from `prd.md`. Pattern: `### RF-NN` or `**RF-NN:**` or numbered list under "Functional Requirements".
+2. Build `Set<RF>` of expected requirements.
+3. Scan `tasks.md` and `<NN>_task.md` files for `Closes RF-XX` / `RF: RF-XX` / `Requirement: RF-XX` markers.
+4. Compute `uncovered = expected - addressed`.
+
+**Pass:** `uncovered` is empty.
+**Revise:** uncovered non-empty AND fixable by adding tasks.
+**Block:** PRD has no numbered requirements (`expected` is empty) — verifying intent is impossible.
+
+**Common failures:**
+- Planner forgot a non-obvious requirement (e.g., audit logging) buried in PRD prose
+- Compound requirement ("user can sign up AND verify email") only addressed for one half
+- Requirement covered indirectly but no task explicitly marks the closure
+
+### 2. Task Completeness
+
+**Goal:** each task has all four parts: files, action, verification, done criteria.
+
+**Steps:**
+For each task in `tasks.md`:
+- Open `<NN>_task.md` (or inline section)
+- Check for required sections:
+  - `## Files` (or `Files to create/modify:`) — explicit paths
+  - `## Action` (or `Implement:`) — what to do, concrete
+  - `## Verification` (or `Verify:`) — how to know it worked (linter, tests, build, manual)
+  - `## Done` (or `Done when:`) — criteria for marking `[x]`
+
+**Pass:** all four sections present in every task.
+**Revise:** ≥1 task missing one section.
+
+**Common failures:**
+- "Files: TBD" or "Files: see techspec" — too vague
+- No verification → executor can't decide when to commit
+- Done criteria absent → executor commits but can't mark `[x]` confidently
+
+### 3. Dependency Soundness
+
+**Goal:** `Depends on:` graph is acyclic, references valid, waves are reasonable.
+
+**Steps:**
+1. Parse every task's `Depends on:` field (none / comma-separated task numbers).
+2. Build directed graph (node = task, edge = depends-on relation).
+3. Topological sort:
+   - Cycle → BLOCK with the cycle path
+   - Reference to non-existent task number → REVISE with the dangling ref
+4. Compute wave widths. Any wave > 8 tasks → REVISE (split with synthetic barrier).
+
+**Pass:** topological sort succeeds, all refs valid, waves ≤ 8 wide.
+
+**Common failures:**
+- Bidirectional dependency (`02 depends on 03; 03 depends on 02`) — likely planner confusion; needs re-think
+- Typo in `Depends on: 02` when the task is actually numbered `2.5` or `03`
+- 10 independent test files all in wave 1 → split into smaller waves
+
+### 4. Artifact Wiring
+
+**Goal:** every artifact produced by a task is consumed by a downstream task OR is a leaf deliverable referenced in PRD's user stories.
+
+**Steps:**
+1. For each task, identify what it PRODUCES:
+   - New files (from `Files: + src/foo.ts`)
+   - New exports (from `Implement: export function bar()`)
+   - New endpoints (from `Action: add POST /api/baz`)
+2. For each downstream task (later in topo order), identify what it CONSUMES:
+   - Imports (from `Files: src/quux.ts (modify) — imports bar`)
+   - References (from `Action: call /api/baz`)
+3. Cross-reference: every produced artifact should be either consumed downstream OR explicitly mentioned in PRD as a user-facing deliverable.
+
+**Pass:** zero orphan artifacts.
+**Revise:** ≥1 artifact created without consumer or PRD reference — likely incomplete plan.
+
+**Common failures:**
+- Task creates a service but no task wires it into the router
+- Task creates a migration file but no task runs it (`prisma migrate deploy`)
+- Task creates a config but no task reads it
+
+### 5. Context Budget
+
+**Goal:** the phase fits in a practical execution window.
+
+**Steps:**
+1. Count tasks. Practical limit: 12 tasks per phase before quality degrades.
+2. Estimate aggregate file changes: sum of files mentioned in `Files:` across all tasks. Limit: 30 files per phase.
+3. Check parallelism setup: are wave-1 tasks running in parallel? (frontmatter `parallel: true` or default).
+
+**Pass:** ≤12 tasks, ≤30 aggregate files, wave 1 has parallel execution if multi-task.
+
+**Revise:** > 12 tasks → suggest splitting into 2 phases. > 30 files → reduce scope or split.
+
+**Common failures:**
+- Mega-phase with 20 tasks because the planner couldn't decompose
+- Single-task waves where parallelism was forgotten
+
+### 6. Constraint Compliance
+
+**Goal:** tasks honor locked decisions and project conventions.
+
+**Steps:**
+1. Read `.dw/rules/index.md` and `.dw/rules/<module>.md` for relevant modules.
+2. Read `CONTEXT.md` if exists; extract `## Decisions` (LOCKED) section.
+3. Read `./CLAUDE.md` for project hard constraints.
+4. For each task, check if its `Action` or `Files` violate:
+   - A locked decision
+   - A project rule (forbidden pattern, mandated tool)
+   - A CLAUDE.md directive
+
+**Pass:** zero violations.
+**Block:** ≥1 hard violation. The plan must change before execution.
+
+**Common failures:**
+- Locked decision says "framework: Fastify" but task says "use Express"
+- Project rules forbid raw SQL; task uses `pg.query()` directly
+- CLAUDE.md says "no env files committed"; task adds `.env.production`
+
+## Verdict resolution
+
+After running all 6 dimensions:
+
+| Outcome | Verdict |
+|---------|---------|
+| All 6 PASS | PASS — proceed to execution |
+| Any REVISE, no BLOCK | REVISE — re-plan |
+| Any BLOCK | BLOCK — surface to user, no auto-replan |
+
+`PASS` is the only state that allows `/dw-execute-phase` to proceed.
+
+## Bounded revision loop
+
+The plan-checker is part of a bounded quality loop:
+
+1. `/dw-create-tasks` produces v1 of `tasks.md`
+2. `/dw-plan-checker` runs → REVISE
+3. `/dw-create-tasks --revise` produces v2 (consumes plan-checker's issues as input)
+4. `/dw-plan-checker` runs → PASS or REVISE again
+5. After 3 revisions without reaching PASS → escalate to user (something fundamental is wrong)
+
+The escalation cap prevents infinite loops where the planner can't satisfy the verifier. At 3 strikes, the user sees the diff between PRD and the failing tasks.md and decides next step.
+
+## Time budget
+
+Plan-checker target: 1-2 minutes. The 6 dimensions are mostly file reads and grep operations; no heavy analysis. If plan-checker exceeds 5 minutes, it's a sign the agent is over-thinking — bias toward issuing REVISE for ambiguous cases rather than analyzing them deeply.

package/scaffold/skills/dw-execute-phase/references/wave-coordination.md

@@ -0,0 +1,102 @@
+# Wave coordination — how the executor parallelizes tasks
+
+Tasks within a phase have dependencies. Some can run in parallel; others must wait. The executor groups tasks into **waves** and runs each wave as parallel subagent dispatches, with sequential ordering between waves.
+
+## Wave computation
+
+Input: `tasks.md` with each task carrying a `Depends on:` field (none, or comma-separated task numbers).
+
+Algorithm: topological sort.
+
+1. Build dependency graph: node per task, edge from each `Depends on:` to the dependent task.
+2. Cycle check: if a cycle exists → abort with `EXEC-FAILED: dependency cycle`.
+3. Wave assignment:
+   - Wave 1 = tasks with zero dependencies
+   - Wave N = tasks whose all dependencies are in waves 1..N-1
+4. Output: ordered list of waves, each wave a list of task numbers.
+
+## Example
+
+```
+tasks.md:
+- 01 Create user schema       Depends on: none
+- 02 Create user model        Depends on: 01
+- 03 Create order schema      Depends on: none
+- 04 Wire auth middleware     Depends on: 02
+- 05 Add login endpoint       Depends on: 04
+- 06 Add order endpoint       Depends on: 02, 03
+- 07 Wire validation rules    Depends on: 04, 06
+
+Computed waves:
+Wave 1: [01, 03]            (no deps; can run in parallel)
+Wave 2: [02]                (depends on 01)
+Wave 3: [04, 06]            (depend on wave 2)
+Wave 4: [05, 07]            (depend on wave 3)
+```
+
+## Parallel execution within a wave
+
+Within a wave, the executor dispatches tasks in parallel via subagent calls (one subagent per task). Each subagent:
+
+1. Reads its `<NN>_task.md`
+2. Implements
+3. Verifies (lint/tests/build)
+4. Commits atomically (per `atomic-commits.md`)
+5. Marks `[x]` in `tasks.md`
+6. Returns success or deviation status to the orchestrating executor
+
+The orchestrating executor:
+
+- Spawns N subagents in parallel (single message, N tool calls)
+- Waits for all to return
+- If all PASS → proceed to next wave
+- If ANY return deviation/blocked → resolve before next wave (see deviation rules in `agents/executor.md`)
+
+## Wave width limits
+
+Practical caps to keep context budget sane:
+
+- **Soft cap: 5 tasks per wave** — tested as the upper bound where parallel execution stays efficient
+- **Hard cap: 8 tasks per wave** — beyond this, the orchestrator's context fills with subagent results faster than tasks complete
+
+If a wave exceeds the hard cap, the planner should split: introduce a synthetic dependency to bisect the wave. Example: if Wave 3 has 10 independent tasks, force tasks 06-10 to depend on a "wave 3a barrier" so they go to Wave 3.5.
+
+The plan-checker (Dimension 5) flags wide waves before execution.
+
+## Cross-wave atomicity
+
+Each wave is a checkpoint:
+
+- After all tasks in a wave commit, run a `git status` check — should be clean (everything committed).
+- If any task in a wave failed permanently (Rule 3 deviation), abort BEFORE starting the next wave. Leave the partial work committed; surface to user via `EXEC-BLOCKED`.
+- Don't run waves N+1 with broken commits in wave N. The dependencies aren't satisfied.
+
+## Order within a wave
+
+Within a wave, order doesn't matter logically (no deps between same-wave tasks). But for **commit history readability**, the executor should commit in numeric order of task number (01 commit before 02 even if both are wave 1). The parallel subagent results may arrive out of order; the executor collects and commits sequentially.
+
+This means: subagents return their changes (files written, but NOT committed). The executor commits them in numeric order.
+
+(Alternative: subagents commit independently and accept commit interleaving. Pick this if commit-order doesn't matter for the project; the orchestrator sets a flag.)
+
+## When to NOT use waves
+
+Single-task changes (`/dw-quick`, `/dw-run-task`) bypass waves entirely. Waves are for `/dw-run-plan` and `/dw-execute-phase` — phase-scale execution.
+
+## Verification of wave structure (pre-execution)
+
+The plan-checker (Dimension 3 in `plan-checker.md`) verifies:
+- Topological sort succeeds (no cycles)
+- All `Depends on:` references point to existing tasks
+- No wave exceeds the hard cap (8 tasks)
+
+If these fail, plan-checker returns REVISE before any code is touched.
+
+## Resume after checkpoint
+
+If the executor checkpoints mid-phase, `active-session.md` records:
+- `last_completed_task`
+- `last_wave_completed`
+- `remaining_tasks`
+
+`/dw-resume` reads this, recomputes waves from `tasks.md`, skips already-committed tasks, and resumes from the wave containing `last_completed_task + 1`.