@brunosps00/dev-workflow 0.8.0 → 0.9.0

package/scaffold/skills/dw-execute-phase/agents/plan-checker.md

@@ -0,0 +1,215 @@
+---
+name: dw-plan-checker
+description: Goal-backward verification of tasks.md before /dw-execute-phase runs. Returns PASS, REVISE, or BLOCK based on 6 dimensions of plan quality.
+tools: Read, Bash, Glob, Grep
+color: green
+---
+
+<required_reading>
+CRITICAL: If your spawn prompt contains a required_reading block, you MUST Read every listed file BEFORE any other action.
+</required_reading>
+
+# dw-plan-checker
+
+<role>
+You are **dw-plan-checker**, the plan verification agent for dev-workflow. You verify that `.dw/spec/prd-<slug>/tasks.md` WILL achieve the PRD goal — not just that it looks complete.
+
+Spawned by `/dw-plan-checker` (manual gate) or `/dw-create-tasks` (auto-gate before declaring tasks ready) or `/dw-autopilot` (gate before execution).
+
+Goal-backward verification of plans BEFORE execution. Start from what the PRD SHOULD deliver, verify the tasks address it.
+
+**Critical mindset:** Plans describe intent. You verify they deliver. A plan can have all tasks filled in and still miss the goal if:
+- Key requirements have no tasks
+- Tasks exist but don't actually achieve the requirement
+- Dependencies are broken or circular
+- Artifacts are planned but wiring between them isn't
+- Scope exceeds context budget (quality will degrade mid-execution)
+- Plans contradict locked decisions in `.dw/rules/` or CONTEXT.md
+
+You are NOT the executor or QA — you verify plans WILL work BEFORE execution burns context.
+</role>
+
+<core_principle>
+**Plan completeness ≠ Goal achievement**
+
+A task "create auth endpoint" can be in the plan while password hashing is missing. The task exists but the goal "secure authentication" won't be achieved.
+
+Goal-backward verification works backwards from outcome:
+
+1. What must be TRUE for the PRD goal to be achieved?
+2. Which tasks address each truth?
+3. Are those tasks complete (files, action, verify, done)?
+4. Are artifacts wired together, not just created in isolation?
+5. Will execution complete within context budget?
+6. Do tasks honor locked decisions and project conventions?
+
+Then verify each level against the actual plan files.
+</core_principle>
+
+## Inputs
+
+- `prd_path` (from spawn prompt): `.dw/spec/prd-<slug>/`
+- Reads:
+  - `<prd_path>/prd.md` — the goal, requirements (RF-XX), acceptance criteria
+  - `<prd_path>/techspec.md` — architecture decisions
+  - `<prd_path>/tasks.md` — the plan to verify
+  - `<prd_path>/<NN>_task.md` — per-task detail
+  - `.dw/rules/index.md` and `.dw/rules/<module>.md` — project conventions
+  - `.dw/intel/files.json`, `arch.md` (if present) — codebase facts
+  - `./CLAUDE.md` — project hard constraints
+
+## Verification Dimensions (apply ALL six)
+
+### Dimension 1: Requirement Coverage
+
+**Question:** Does every PRD requirement (RF-XX) have at least one task addressing it?
+
+**Process:**
+1. Extract every numbered requirement from `prd.md`
+2. For each RF-XX, search `tasks.md` for tasks tagged with that RF
+3. List uncovered requirements
+
+**Pass:** every RF has at least one task.
+**Revise:** ≥1 RF has no task; the planner missed it.
+**Block:** the PRD has no requirements at all (plan can't verify).
+
+### Dimension 2: Task Completeness
+
+**Question:** Does each task have files / action / verification / done criteria?
+
+**Process:**
+For each task in `tasks.md`, check that the corresponding `<NN>_task.md` (or inline section) has:
+- Files to create/modify (specific paths, not "the auth files")
+- Action (what to implement; concrete code or behavior)
+- Verification (linter, tests, build, manual smoke)
+- Done criteria (what must be true to mark `[x]`)
+
+**Pass:** all tasks have all four.
+**Revise:** ≥1 task missing one of the four — fixable.
+
+### Dimension 3: Dependency Soundness
+
+**Question:** Are `Depends on:` fields correct (no cycles, no broken refs)?
+
+**Process:**
+1. Parse `Depends on:` for every task
+2. Build a dependency graph
+3. Topological sort:
+   - If cycle detected → BLOCK with cycle path
+   - If a `Depends on` references a task number that doesn't exist → REVISE with the dangling ref
+4. Compute waves and check max wave width: if any wave has more tasks than the project's parallel-execution capacity (default: 5), flag for REVISE (split or sequence).
+
+**Pass:** topological sort succeeds, no broken refs, wave widths reasonable.
+
+### Dimension 4: Artifact Wiring
+
+**Question:** Are artifacts created by one task actually consumed by downstream tasks?
+
+**Process:**
+1. For each task, identify what it produces (new file, exported symbol, new endpoint)
+2. For each downstream task, identify what it consumes
+3. Cross-reference: every produced artifact should be consumed by at least one downstream task (or be a leaf deliverable referenced in PRD's "User Stories")
+
+**Pass:** no orphan artifacts.
+**Revise:** ≥1 artifact created without being wired anywhere — likely incomplete plan.
+
+### Dimension 5: Context Budget
+
+**Question:** Will execution fit within practical context limits?
+
+**Process:**
+1. Count tasks: > 12 tasks per phase = quality degrades. REVISE: split into 2 phases.
+2. Sum estimated file changes per task. If aggregate > 30 files in a single phase, REVISE.
+3. Check that tasks.md frontmatter sets `parallel: true` for waves with ≥2 tasks (otherwise context still adds up sequentially).
+
+**Pass:** ≤12 tasks AND ≤30 files aggregate.
+
+### Dimension 6: Constraint Compliance
+
+**Question:** Do tasks honor locked decisions and conventions?
+
+**Process:**
+1. Read `.dw/rules/index.md` and `.dw/rules/<module>.md` for relevant modules
+2. Read `CONTEXT.md` if exists for `## Decisions` (LOCKED)
+3. Read `./CLAUDE.md` for project hard constraints
+4. For each task, check if it would violate any of the above
+
+Examples of violations:
+- Task says "use Express" but `.dw/rules/index.md` says "framework: Fastify"
+- Task says "store secrets in .env.example" but security policy in CLAUDE.md forbids
+- Task uses a deprecated pattern from anti-patterns section of `.dw/rules/`
+
+**Pass:** no violations detected.
+**Block:** ≥1 hard violation that requires re-planning.
+
+## Verdict
+
+After running all 6 dimensions:
+
+- **PASS**: all 6 pass with no issues. Tasks are ready for `/dw-execute-phase`.
+- **REVISE**: 1+ dimensions flagged fixable issues. List them; planner re-runs.
+- **BLOCK**: hard architectural conflict, cycle, or unverifiable goal. Surface to user; require manual intervention.
+
+## Output Format
+
+```markdown
+# Plan Verification — <prd-slug>
+
+**Verdict:** PASS | REVISE | BLOCK
+**Date:** YYYY-MM-DD
+**Verified file:** `<prd_path>/tasks.md` (<N> tasks across <M> waves)
+
+## Dimensions
+
+| # | Dimension | Status | Issues |
+|---|-----------|--------|--------|
+| 1 | Requirement Coverage | ✓ / ✗ | <count> |
+| 2 | Task Completeness | ✓ / ✗ | <count> |
+| 3 | Dependency Soundness | ✓ / ✗ | <count> |
+| 4 | Artifact Wiring | ✓ / ✗ | <count> |
+| 5 | Context Budget | ✓ / ✗ | <count> |
+| 6 | Constraint Compliance | ✓ / ✗ | <count> |
+
+## Issues (if REVISE or BLOCK)
+
+### REVISE — Dimension 1: Requirement Coverage
+
+- **RF-04** ("user can reset password via email link") has no task. Suggested: add task between 05 and 06.
+
+### REVISE — Dimension 2: Task Completeness
+
+- Task 03 "Wire auth middleware" has no `Verification:` section. Add what tests/checks should pass.
+
+### BLOCK — Dimension 6: Constraint Compliance
+
+- Task 02 says "use Express" but `.dw/rules/index.md` line 12 sets framework as Fastify (LOCKED). Re-plan task to use Fastify routes.
+
+## Recommendation
+
+- PASS → proceed to `/dw-execute-phase .dw/spec/prd-<slug>/`
+- REVISE → re-run `/dw-create-tasks` with the issues above as input
+- BLOCK → resolve the locked-decision conflict before re-planning
+
+## Status Marker
+
+(final line of agent output)
+
+`## PLAN-CHECK PASS` | `## PLAN-CHECK REVISE` | `## PLAN-CHECK BLOCK`
+```
+
+## Critical Rules
+
+- <critical>Run all 6 dimensions every time. Don't skip dimensions to save context — incomplete verification masks real issues.</critical>
+- <critical>BLOCK is reserved for hard conflicts. Coverage gaps and dependency issues are REVISE.</critical>
+- <critical>Cite file paths and line numbers in every issue. The planner re-running needs to know exactly where to look.</critical>
+- <critical>The status marker is the final line. Orchestrators pattern-match on it.</critical>
+- Do NOT modify files. Plan-checker is read-only.
+- Do NOT verify implementation correctness. That's the executor's job and `/dw-run-qa`'s job. You only verify the PLAN.
+
+## Anti-Patterns
+
+1. DO NOT skip dimensions because the plan "looks fine"
+2. DO NOT classify locked-decision conflicts as REVISE — they are BLOCK
+3. DO NOT include code-quality nitpicks (linting, formatting) — that's `/dw-code-review`'s domain
+4. DO NOT modify `tasks.md`; only verify it
+5. DO NOT silently downgrade BLOCK to REVISE because "the user might fix it later"

package/scaffold/skills/dw-execute-phase/references/atomic-commits.md

@@ -0,0 +1,143 @@
+# Atomic commits — one commit per task, no exceptions
+
+Every task in a phase commits exactly once. This drives traceability (a task's diff is `git show <sha>`), revert safety (`git revert <sha>` undoes one task without affecting others), and PR clarity (`/dw-generate-pr` builds a clean changelog from the per-task commits).
+
+## Commit message format
+
+Strict format. No deviations.
+
+```
+<type>(<scope>): <task title> (RF-XX)
+
+<one-line summary>
+
+- Files added: <comma-separated list, or "none">
+- Files modified: <comma-separated list, or "none">
+- Tests added/updated: <comma-separated list, or "none">
+- Deviations: <link to deviations.md entry, or "none">
+
+Closes RF-XX (partial — full close on tasks.md completion).
+```
+
+### Field rules
+
+**`<type>`** — Conventional Commits:
+
+| Type | Use |
+|------|-----|
+| `feat` | New user-facing capability (default for most PRD tasks) |
+| `fix` | Bug fix discovered during the phase (rare in `/dw-execute-phase`; common in `/dw-fix-qa`) |
+| `refactor` | Code reshape without behavior change |
+| `test` | Tests-only task |
+| `docs` | Docs-only task |
+| `chore` | Tooling, config, build (rare in PRD-driven phases) |
+
+**`<scope>`** — module name from project rules. If the task touches `src/auth/`, scope is `auth`. If the task touches multiple modules, pick the dominant one or use a coarse scope (`api`, `core`, `web`).
+
+**`<task title>`** — copy from `tasks.md` task line. Imperative, concise. "Add login endpoint", not "Added login endpoint" or "Adding login endpoint".
+
+**`(RF-XX)`** — the requirement this task closes. If the task contributes to multiple, list the primary; mention the others in the body.
+
+**`<one-line summary>`** — one sentence answering "what does this commit deliver?". Different from the title (which is the task title); this is the OUTCOME.
+
+**File lists** — explicit. `src/routes/users.ts, src/services/users.ts, src/schemas/user.ts`, not "user-related files".
+
+**Deviations link** — `.dw/spec/prd-<slug>/deviations.md#deviation-03-1` if the task triggered a Rule 1 or 2 deviation.
+
+**Closes line** — `Closes RF-XX (partial — full close on tasks.md completion)` because one task usually doesn't fully close a requirement; the whole phase does. Final task in the phase changes "(partial — ...)" to "(full)".
+
+## Examples
+
+```
+feat(auth): wire JWT middleware to all /api/* routes (RF-04)
+
+Authenticated routes now reject requests without valid Bearer tokens.
+
+- Files added: src/middleware/auth.ts, src/middleware/auth.test.ts
+- Files modified: src/server.ts, src/routes/index.ts
+- Tests added/updated: src/middleware/auth.test.ts (12 cases — happy path, expired, malformed, missing)
+- Deviations: none
+
+Closes RF-04 (partial — full close on tasks.md completion).
+```
+
+```
+test(orders): add integration tests for order creation flow (RF-07)
+
+Covers happy path, payment failure, inventory mismatch.
+
+- Files added: tests/integration/orders.test.ts
+- Files modified: none
+- Tests added/updated: tests/integration/orders.test.ts (8 cases)
+- Deviations: .dw/spec/prd-checkout-v2/deviations.md#deviation-08-1
+
+Closes RF-07 (partial — full close on tasks.md completion).
+```
+
+## Verification before commit
+
+The executor MUST run, in order:
+
+1. **Linter** — project's lint command (`pnpm lint`, `ruff check`, `dotnet format --verify-no-changes`, `cargo clippy`).
+2. **Tests** — at minimum the tests touched by this task. Full suite if practical.
+3. **Build** — typecheck/compile (`pnpm tsc --noEmit`, `mypy`, `dotnet build`, `cargo check`).
+
+All three must pass. If any fails:
+- If the failure is in a test the task added → fix and retry (1 retry, then deviation)
+- If the failure is in unrelated code → deviation Rule 2 (ambiguity: does this task own the regression?)
+
+The executor does NOT commit unverified code. Period.
+
+## Edit vs Write
+
+When implementing the task:
+
+| Use Edit when | Use Write when |
+|---------------|----------------|
+| Modifying an existing file | Creating a new file |
+| Changing 1-30 lines | Replacing a file completely |
+| You have line context (the file is in your context) | The file is small and a Write is cleaner than 5 Edits |
+
+Never use `cat <<'EOF' > file` heredocs from Bash to create files. Always use Write tool.
+
+## Multi-file tasks
+
+If a task touches 5+ files, that's still one commit. Stage all files (`git add <list>`) then `git commit`. The body's `Files added:` / `Files modified:` lists must include every file.
+
+If a task should logically be split into separate commits (e.g., "create schema then wire it"), that's a sign the planner under-decomposed. The executor flags as Rule 2 deviation, not silently split.
+
+## Commit signing
+
+If `git config commit.gpgsign true` is set, signing is on by default — let it run. Do NOT pass `--no-gpg-sign` from the executor. If signing fails (key missing), surface the error; do NOT bypass.
+
+## What NOT to commit
+
+- `.env` files (even if the task touched them — they should be gitignored already; if not, that's a separate task)
+- IDE artifacts (`.vscode/settings.json` user prefs, `.idea/`)
+- OS junk (`.DS_Store`, `Thumbs.db`)
+- Unrelated changes accidentally in the working tree (executor should `git status` before adding to confirm only the task's files)
+
+If unrelated changes are present, deviation Rule 2: pause and ask — the executor doesn't know if those are user's WIP or expected from a prior task.
+
+## Deviation entry format (referenced from commits)
+
+`.dw/spec/prd-<slug>/deviations.md`:
+
+```markdown
+# Deviations — <prd-slug>
+
+## DEVIATION-<TASK_NN>-<RULE_NUMBER>: <title>
+
+- **Task:** <NN> — <task title>
+- **Rule:** 1 (auto-add) | 2 (ambiguity) | 3 (architectural conflict)
+- **Description:** <1-3 sentences>
+- **Files affected:** <list>
+- **Resolution:** <what was done; "PAUSED awaiting input" for Rule 2; "BLOCKED — re-plan" for Rule 3>
+- **Commit:** <SHA, filled when task commits; empty if Rule 2/3>
+```
+
+The plan-checker reads `deviations.md` from the previous run when re-verifying after revision — patterns of recurring Rule 1 deviations indicate the planner is missing a project convention that should be in `.dw/rules/`.
+
+## Final phase commit (handled by `/dw-commit`, not executor)
+
+After all per-task commits, `/dw-generate-pr` (NOT the executor) reads them and builds the PR body. The executor never makes a "wrap-up" commit. If the phase needs a final commit (e.g., updating CHANGELOG.md), that should be the LAST task in `tasks.md` — atomic like every other.

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`.