@loneexile/omp-superpowers 7.0.0-omp.2 → 7.0.0-omp.4

package/skills/subagent-driven-development/SKILL.md

@@ -5,11 +5,11 @@ description: Use when executing implementation plans with independent tasks in t
 
 # Subagent-Driven Development
 
-Execute plan by dispatching a fresh implementer subagent per task, a task review (spec compliance + code quality) after each, and a broad whole-branch review at the end.
+Execute a plan by dispatching a fresh implementer subagent per task — independent tasks in parallel waves, each in its own worktree — with a task review (spec compliance + code quality) for each task on the review list, and one broad whole-branch review at the end that also does the task review's work for every other task.
 
 **Why subagents:** You delegate tasks to specialized agents with isolated context. By precisely crafting their instructions and context, you ensure they stay focused and succeed at their task. They should never inherit your session's context or history — you construct exactly what they need. This also preserves your own context for coordination work.
 
-**Core principle:** Fresh subagent per task + task review (spec + quality) + broad final review = high quality, fast iteration
+**Core principle:** Fresh subagent per task + parallel waves for independent tasks + a task review where risk earns it + one broad final review = high quality, fast iteration
 
 **Narration:** between tool calls, narrate at most one short line — the
 ledger and the tool results carry the record.
@@ -28,7 +28,10 @@ Four things stop you, and only these: an irreversible or destructive
 operation; a security-sensitive action; a side effect outside this worktree
 that norms say you ask about first (a merge, a push to a shared branch, a
 publish); and a plan so broken that every path forward is a guess. For those,
-stop and ask.
+stop and ask. This skill's own wave merges into the plan branch, and the task
+worktrees it creates and removes, are not among them. It adds two stops of
+its own: a wave task that still will not merge after its rounds (`merge
+stuck`), and a wave suite still red after its one fix.
 
 **On omp in vibe mode** (your tools include `vibe_spawn` but not `task`)
 you are the director, and this loop cannot run in your session: you have
@@ -54,24 +57,25 @@ limits are in "Vibe mode" in
 digraph when_to_use {
     "Have implementation plan?" [shape=diamond];
     "Tasks mostly independent?" [shape=diamond];
-    "Partner chose inline, or no subagent tool?" [shape=diamond];
+    "Inline approved at the handoff, or no subagent tool?" [shape=diamond];
     "subagent-driven-development" [shape=box];
     "executing-plans" [shape=box];
     "Manual execution or brainstorm first" [shape=box];
 
     "Have implementation plan?" -> "Tasks mostly independent?" [label="yes"];
     "Have implementation plan?" -> "Manual execution or brainstorm first" [label="no"];
-    "Tasks mostly independent?" -> "Partner chose inline, or no subagent tool?" [label="yes"];
+    "Tasks mostly independent?" -> "Inline approved at the handoff, or no subagent tool?" [label="yes"];
     "Tasks mostly independent?" -> "Manual execution or brainstorm first" [label="no - tightly coupled"];
-    "Partner chose inline, or no subagent tool?" -> "executing-plans" [label="yes"];
-    "Partner chose inline, or no subagent tool?" -> "subagent-driven-development" [label="no"];
+    "Inline approved at the handoff, or no subagent tool?" -> "executing-plans" [label="yes"];
+    "Inline approved at the handoff, or no subagent tool?" -> "subagent-driven-development" [label="no"];
 }
 ```
 
 **vs. Executing Plans (inline):**
 - Fresh subagent per task (no context pollution) instead of one context doing every task
-- Review after each task (spec compliance + code quality) instead of only at the end
-- Costs a fresh context per task and per review; inline costs one context plus one final reviewer
+- Independent tasks run in parallel; inline runs every task in turn
+- A task review (spec compliance + code quality) for each high-risk task, plus the final review; inline has only the final review
+- Costs a fresh context per task and per task review; inline costs one context plus one final reviewer
 - Both run in this session, share the same plan workspace and ledger, and never pause between tasks
 
 ## The Process
@@ -81,11 +85,14 @@ digraph process {
     rankdir=TB;
 
     subgraph cluster_per_task {
-        label="Per Task";
+        label="Per Task (every task of a wave at once)";
         "Dispatch implementer subagent (./implementer-prompt.md)" [shape=box];
         "Implementer asks questions?" [shape=diamond];
         "Answer questions, provide context" [shape=box];
         "Implementer implements, tests, commits, self-reviews" [shape=box];
+        "On the review list?" [shape=diamond];
+        "Run the brief's covering tests yourself" [shape=box];
+        "Resume implementer with the failure" [shape=box];
         "Generate review package, dispatch task reviewer (./task-reviewer-prompt.md)" [shape=box];
         "Spec ✅ and quality approved?" [shape=diamond];
         "Finding conflicts with plan text?" [shape=diamond];
@@ -98,42 +105,49 @@ digraph process {
         "Any load-bearing finding?" [shape=diamond];
         "Rule and continue; stop only if every path forward is a guess" [shape=box];
         "Park findings in ledger with rulings" [shape=box];
-        "Append completion to ledger, mark todo complete" [shape=box];
+        "Merge the task branch (wave of 2+), append completion to ledger, mark todo complete" [shape=box];
     }
 
-    "Setup: worktree, ledger check, read plan, pre-flight review" [shape=box];
-    "More tasks remain?" [shape=diamond];
-    "Dispatch final reviewer: sdd-final-reviewer (package + ledger lines; its agent file governs the output)" [shape=box];
+    "Setup: worktree, ledger check, read plan, pre-flight scan: review list + waves" [shape=box];
+    "Start the next wave: a worktree per task when it has 2+" [shape=box];
+    "More waves remain?" [shape=diamond];
+    "Dispatch final reviewer: sdd-final-reviewer (package + ledger lines + the tasks left to it; its agent file governs the output)" [shape=box];
     "Final findings? ONE fix dispatch, one scoped re-review, adjudicate residuals" [shape=box];
     "Final review clean: delete this plan's workspace" [shape=box];
     "Use superpowers:finishing-a-development-branch" [shape=box style=filled fillcolor=lightgreen];
 
-    "Setup: worktree, ledger check, read plan, pre-flight review" -> "Dispatch implementer subagent (./implementer-prompt.md)";
+    "Setup: worktree, ledger check, read plan, pre-flight scan: review list + waves" -> "Start the next wave: a worktree per task when it has 2+";
+    "Start the next wave: a worktree per task when it has 2+" -> "Dispatch implementer subagent (./implementer-prompt.md)";
     "Dispatch implementer subagent (./implementer-prompt.md)" -> "Implementer asks questions?";
     "Implementer asks questions?" -> "Answer questions, provide context" [label="yes"];
     "Answer questions, provide context" -> "Implementer implements, tests, commits, self-reviews";
     "Implementer asks questions?" -> "Implementer implements, tests, commits, self-reviews" [label="no"];
-    "Implementer implements, tests, commits, self-reviews" -> "Generate review package, dispatch task reviewer (./task-reviewer-prompt.md)";
+    "Implementer implements, tests, commits, self-reviews" -> "On the review list?";
+    "On the review list?" -> "Run the brief's covering tests yourself" [label="no - review at final"];
+    "Run the brief's covering tests yourself" -> "Merge the task branch (wave of 2+), append completion to ledger, mark todo complete" [label="pass"];
+    "Run the brief's covering tests yourself" -> "Resume implementer with the failure" [label="fail"];
+    "Resume implementer with the failure" -> "Run the brief's covering tests yourself";
+    "On the review list?" -> "Generate review package, dispatch task reviewer (./task-reviewer-prompt.md)" [label="yes"];
     "Generate review package, dispatch task reviewer (./task-reviewer-prompt.md)" -> "Spec ✅ and quality approved?";
-    "Spec ✅ and quality approved?" -> "Append completion to ledger, mark todo complete" [label="yes"];
+    "Spec ✅ and quality approved?" -> "Merge the task branch (wave of 2+), append completion to ledger, mark todo complete" [label="yes"];
     "Spec ✅ and quality approved?" -> "Finding conflicts with plan text?" [label="no"];
     "Finding conflicts with plan text?" -> "Rule on the conflict, ledger the ruling" [label="yes"];
     "Rule on the conflict, ledger the ruling" -> "Fix round R of 3: R≤2 resume implementer; R=3 fresh sdd-escalation-implementer";
     "Finding conflicts with plan text?" -> "Fix round R of 3: R≤2 resume implementer; R=3 fresh sdd-escalation-implementer" [label="no"];
     "Fix round R of 3: R≤2 resume implementer; R=3 fresh sdd-escalation-implementer" -> "Dispatch scoped re-review (./re-review-prompt.md)";
     "Dispatch scoped re-review (./re-review-prompt.md)" -> "All findings addressed?";
-    "All findings addressed?" -> "Append completion to ledger, mark todo complete" [label="yes"];
+    "All findings addressed?" -> "Merge the task branch (wave of 2+), append completion to ledger, mark todo complete" [label="yes"];
     "All findings addressed?" -> "R = 3?" [label="no"];
     "R = 3?" -> "Fix round R of 3: R≤2 resume implementer; R=3 fresh sdd-escalation-implementer" [label="no - next round"];
     "R = 3?" -> "Adjudicate each open finding" [label="yes - breaker trips"];
     "Adjudicate each open finding" -> "Any load-bearing finding?";
     "Any load-bearing finding?" -> "Rule and continue; stop only if every path forward is a guess" [label="yes"];
     "Any load-bearing finding?" -> "Park findings in ledger with rulings" [label="no"];
-    "Park findings in ledger with rulings" -> "Append completion to ledger, mark todo complete";
-    "Append completion to ledger, mark todo complete" -> "More tasks remain?";
-    "More tasks remain?" -> "Dispatch implementer subagent (./implementer-prompt.md)" [label="yes"];
-    "More tasks remain?" -> "Dispatch final reviewer: sdd-final-reviewer (package + ledger lines; its agent file governs the output)" [label="no"];
-    "Dispatch final reviewer: sdd-final-reviewer (package + ledger lines; its agent file governs the output)" -> "Final findings? ONE fix dispatch, one scoped re-review, adjudicate residuals";
+    "Park findings in ledger with rulings" -> "Merge the task branch (wave of 2+), append completion to ledger, mark todo complete";
+    "Merge the task branch (wave of 2+), append completion to ledger, mark todo complete" -> "More waves remain?" [label="after the wave's last task"];
+    "More waves remain?" -> "Start the next wave: a worktree per task when it has 2+" [label="yes"];
+    "More waves remain?" -> "Dispatch final reviewer: sdd-final-reviewer (package + ledger lines + the tasks left to it; its agent file governs the output)" [label="no"];
+    "Dispatch final reviewer: sdd-final-reviewer (package + ledger lines + the tasks left to it; its agent file governs the output)" -> "Final findings? ONE fix dispatch, one scoped re-review, adjudicate residuals";
     "Final findings? ONE fix dispatch, one scoped re-review, adjudicate residuals" -> "Final review clean: delete this plan's workspace";
     "Final review clean: delete this plan's workspace" -> "Use superpowers:finishing-a-development-branch";
 }
@@ -141,12 +155,29 @@ digraph process {
 
 ## Setup
 
-Ensure the work happens in an isolated workspace: use
-superpowers:using-git-worktrees to create one or verify the existing one.
-Never start implementation on a main/master branch without your human
-partner's explicit consent.
-
-**On omp, the session must be in the worktree before you dispatch.** A
+Ensure the work happens in an isolated workspace. If the plan's approval
+named a new branch in this checkout (writing-plans' default), that approval
+was your human partner's answer to superpowers:using-git-worktrees' consent
+question: work in place, with no worktree and no `/move`.
+
+- **A ledger for this plan exists** (below): `git switch` to the branch its
+  `Setup:` line names, and resume from the ledger. Run nothing else here.
+- **First run:** run `git status --porcelain`. If it lists a change to a
+  tracked file, or anything staged, ask your human partner to commit or
+  stash it first: a run in place commits from this index and tests this
+  working tree, so their uncommitted work would land in task commits and in
+  every test result. Untracked files may stay; note them, and they stay out
+  of every commit. If a branch with the approved name already exists, ask,
+  or name another. Then `git switch -c <branch>`, run
+  using-git-worktrees' Step 2 (project setup) and Step 3 (baseline tests)
+  here, and, once the ledger exists, ledger `Setup: branch <branch> in this
+  checkout; untracked before start: <paths | none>`.
+
+Otherwise use superpowers:using-git-worktrees to create a worktree or
+verify the existing one. Never start implementation on a main/master branch
+without your human partner's explicit consent.
+
+**On omp, a session worktree needs `/move` before you dispatch.** A
 subagent starts in the session's cwd (the `task` tool has no `cwd`
 argument), so after `omp worktree add` every SDD subagent still works in the
 ORIGINAL checkout until your human partner runs `/move <path>`. Get `/move`
@@ -181,13 +212,43 @@ a ledger file, not only in todos.
   working directory at the repo root — the scripts call `git rev-parse`.
   The invocation lines in this skill stay as upstream wrote them.
 - Check for this plan's ledger at `<workspace>/progress.md`. If its first
-  line names your plan file, tasks with a `Task <N>: complete` line are DONE
-  — do not re-dispatch them; resume at the first task without one. A task
-  whose last line is `dispatched` or `re-dispatched` is mid-implementation:
-  check `git log` from its BASE and read `agent://<id>` before you dispatch
-  anything. A task
-  whose last line is a fix round is mid-loop: resume the loop at the next
-  round. A ledger whose first line names a different plan file — or a stray
+  line names your plan file, first find wave tasks that merged before the
+  ledger caught up: for every wave task whose branch still exists and that
+  has no `merged` line, whatever its last line, the merge happened when the
+  branch has commits past its BASE (`git rev-list --count <BASE>..<branch>`
+  is 1 or more) AND its tip is an ancestor of the plan branch (`git
+  merge-base --is-ancestor <branch> HEAD`); ledger `merged` for it. A
+  branch with no commits past BASE also passes the ancestor test; it is an
+  unstarted or lost task, never a merged one. Then take each task by its
+  last ledger line:
+  - `complete`: DONE — do not re-dispatch it; resume at the first task
+    without one.
+  - `merged`: clean up its worktree and branch (Complete the task) and
+    write its `complete` line.
+  - `dispatched` or `re-dispatched`: mid-implementation. Check `git log`
+    from its BASE (on its task branch, for a wave task whose line names a
+    worktree) and read `agent://<id>` before you dispatch anything.
+  - `fix round` or `rebased`: read `agent://<id>` first, and wait for a
+    round still running. A `rebased` round that reported goes back to its
+    merge; a `fix round` line with findings open goes to the next round,
+    and one with none open completes the task. The two kinds of line
+    together count toward the task's three rounds.
+  - `review per-task — <class or reason>`: with no `dispatched` line before
+    it, the task has not started; after one, the task reported and awaits
+    that review.
+  - `merge stuck`: the run is stopped; wait for your human partner.
+  - A worktree that exists for a task with no `dispatched` line is reused,
+    not added again, and gets the install step and its check again
+    (Dispatch the implementer).
+
+  Then check the plan checkout. A merge in progress (`git rev-parse -q
+  --verify MERGE_HEAD` prints a commit) was interrupted: run `git merge
+  --abort` and redo that task's merge (Complete the task). A wave of two or
+  more whose tasks are all complete still needs its suite run, or its fix
+  and rerun, before the next wave or the final review unless its last
+  `Wave <K>:` line is `suite pass`.
+
+  A ledger whose first line names a different plan file — or a stray
   ledger at the old flat path `.superpowers/sdd/progress.md` — is another
   plan's progress: leave it in place and start your own, fresh.
 - Create the ledger with its identity as the first line:
@@ -222,9 +283,35 @@ Write the table to the ledger. Rule on everything you find before execution
 begins — each finding against the plan text that mandates it — and record
 each ruling in the ledger. If the scan is clean, proceed without comment.
 Rule on each conflict it surfaces — the spec is the binding authority, the
-plan is its argument — record the ruling beside its row, and dispatch
-Task 1. The review loop remains the net for conflicts that only emerge from
-implementation.
+plan is its argument — and record the ruling beside its row. Clean or not,
+the same table then gives you the two ledger blocks below; write both before
+the first dispatch. The review loop remains the net for conflicts that only
+emerge from implementation.
+
+**The review list.** A task gets its own task review when the plan marks it
+`**Review:** per-task`, or when you rule it high-risk: security or
+authentication, concurrency, a data migration or persisted format, money, a
+destructive operation, or an interface two or more later tasks consume. A
+batch (below) counts as one task. Ledger one line per task, `Task <N>:
+review per-task — <class>` or `Task <N>: review at final`. The final
+whole-branch review does the task review's work for every `review at final`
+task. A task joins the list mid-run, ledgered as `Task <N>: review per-task
+— <reason>`, when its report is DONE_WITH_CONCERNS about correctness or
+scope, it went BLOCKED, or its implementer needed 100+ turns.
+
+**The waves.** Tasks with no row between them in the scan table (no shared
+file, no shared interface), whose `Consumes` all come from earlier waves,
+form one wave: take them in plan order, at most three to a wave. A task that
+consumes another's interface waits for the wave that produces it. Files
+every task tends to touch (a lockfile, a manifest, a CHANGELOG, an index or
+barrel file) count as shared, and so does anything the tests hold at run
+time (a fixed port, a database, a cache directory). Ledger
+`Wave <K>: tasks <N>, <N>, <N>` for each wave, then start Wave 1. A plan that
+is one long chain gets one task per wave and runs in sequence, and so does
+every plan whose checkout has uncommitted changes to tracked files
+(`git status --porcelain --untracked-files=no` not empty): a merge needs
+them committed or stashed. Untracked files keep waves on, but git refuses
+to start a merge that would overwrite one (Complete the task).
 
 ## Agent Selection
 
@@ -346,13 +433,12 @@ needs 100+ turns, or a re-review that wanders, is the signal to rule that
 task onto the escalation seat. Re-reviews are verdict-only work over a small
 diff — `low` reasoning is correct for them, not a compromise.
 
-**Scale the task review to the diff's risk.** The reviewer seat is fixed, but
-a small mechanical diff does not need the deepest reasoning and a subtle one
-(concurrency, security, a data migration) does. When `task.enableEffort` is
-on (it is off by default — `omp config get task.enableEffort`), dispatch the
-reviewer for such a diff with `effort: "hi"`: that selects the resolved
-model's top thinking level, capped by `task.maxEffort`. When it is off, ledger
-the risk — `Task <N>: high-risk diff — <class>` — and name that class in the
+**Scale the task review to the diff's risk.** Every task on the review list
+is there for its risk class or a trouble signal (Setup), so its reviewer needs the deepest
+reasoning the seat has. When `task.enableEffort` is on (it is off by
+default — `omp config get task.enableEffort`), dispatch that reviewer with
+`effort: "hi"`: that selects the resolved model's top thinking level,
+capped by `task.maxEffort`. Either way, name each listed task's class in the
 final review dispatch.
 
 **Escalation (fix round 3):** the implementer that got stuck cannot see its
@@ -406,8 +492,9 @@ judge, and **Mergeable:** come last.
 
 ### 1. Dispatch the implementer
 
-Record BASE (`git rev-parse HEAD`) before dispatching — the review package
-and fix-round diffs need it.
+Record BASE (`git rev-parse HEAD` in the plan checkout) before dispatching —
+the review package and fix-round diffs need it. Every task in a wave shares
+the wave's BASE.
 
 - **Task brief:** before dispatching an implementer, run this skill's
   `bash scripts/task-brief PLAN_FILE N` — it extracts the task's full text to a
@@ -440,7 +527,8 @@ and fix-round diffs need it.
   a pointer to that ledger entry in the dispatch.
 - Record the implementer's agent identity from the dispatch result —
   fix-loop rounds 1-2 resume this agent.
-- Never dispatch multiple implementation subagents in parallel (conflicts).
+- Dispatch a wave's implementers together: ONE `task` call with one item per
+  task. A task runs only in the wave the ledger gave it.
 - **On omp, the agent id is the handle and resume is a message.** The
   `<task-result id="X" …>` envelope (inline, or delivered as a notice)
   reports the agent id and says the agent is now idle. Use that id exactly
@@ -448,7 +536,8 @@ and fix-round diffs need it.
   that was already taken (`Name-2`), and calls a follow-up turn's job
   `<id>-2` — the job id is not the agent id. Ledger the dispatch the moment
   you have the id, together with BASE, so both survive compaction:
-  `Task <N>: dispatched (BASE <base7>, implementer <id>)`. Fix rounds 1-2
+  `Task <N>: dispatched (BASE <base7>, implementer <id>[, worktree <absolute path>])`,
+  the worktree part for a wave task only. Fix rounds 1-2
   and the answer to a NEEDS_CONTEXT then go to that agent with
   `write agent://<id>`.
 - **The write has two success answers; only an error means "dispatch
@@ -461,14 +550,67 @@ and fix-round diffs need it.
   next result arrives as a notice either way. Only an error answer (`Failed:
   …`, or a write error) means dispatch a fresh `sdd-implementer`. That
   dispatch gets a new id, which omp may suffix (`Name-2`) because the old id is
-  taken: ledger it — `Task <N>: re-dispatched (implementer <new id>)` — and use
+  taken: ledger it — `Task <N>: re-dispatched (implementer <new id>[, worktree <absolute path>])` — and use
   it from then on.
-- **One implementer at a time, no isolation.** On omp, SDD dispatches
-  implementers one at a time, in plan order, in the shared checkout, and does
-  not use `task.isolation.enabled`: under the default
-  `task.isolation.merge: patch` an isolated run's work lands as an applied but
-  uncommitted diff, so a review package has no commit range to cut, and an
-  isolated agent cannot be resumed or messaged, which fix rounds 1-2 need.
+- **A wave of two or more: one git worktree per task, not omp isolation.**
+  Implementers sharing one checkout overwrite each other, and
+  `task.isolation.enabled` does not fit SDD. Under the default
+  `task.isolation.merge: patch` an isolated run's work lands as an applied
+  but uncommitted diff, so a review package has no commit range to cut.
+  `merge: branch` keeps the commits, but omp cherry-picks them onto the plan
+  branch the moment the task ends, before any review, under new commit ids,
+  and deletes the task branch. And fix rounds 1-2 resume the implementer,
+  which an isolated agent cannot take. Measured on omp 18.11.0: a `write
+  agent://<id>` to an isolated agent answers `Delivered`, the agent commits
+  its fix in its own copy, and the fix never reaches the plan branch while
+  the session runs; after the session ended it sat on a leftover
+  `omp/task/<id>` branch that also repeats the already-merged commit.
+  Before dispatching the wave, from the plan checkout, add one
+  worktree per task at the plan branch's head:
+
+  ```bash
+  repo=$(basename "$(git rev-parse --show-toplevel)")
+  omp worktree add -b "sdd/<plan>/task-<N>" ~/.omp/wt/"$repo-<plan>-task-<N>"
+  ```
+
+  `<plan>` is the plan file's name without `.md`;
+  superpowers:using-git-worktrees says why `omp worktree add` and
+  `~/.omp/wt/`. Then, in each new worktree and before dispatching, run the
+  project's install step there (`npm ci`, `uv sync`, the plan's setup
+  command), even when the clone succeeded. A clone that fell back to a
+  plain checkout has no `node_modules` or other build output at all, and a
+  successful clone copies an in-project virtualenv (`.venv`) that keeps
+  absolute paths into the plan checkout — its scripts' interpreter, any
+  editable install — so tests run with it would run the plan checkout's
+  code. Remove a cloned in-project virtualenv before the install step
+  recreates it (`uv sync`, or `python3 -m venv .venv` and `.venv/bin/python
+  -m pip install -e .` — the venv's own pip, not the one on `PATH`). Then
+  check that the code resolves in the worktree, with `cwd` outside it (`/`)
+  so the current directory is not on the import path: for Python,
+  `<worktree>/.venv/bin/python -c 'import <package>;
+  print(<package>.__file__)'` must print a path under the worktree. Record
+  `git -C <worktree> status --porcelain` after the install: files the
+  install wrote are not the implementer's (DONE compares against this). A
+  wave of one runs in the plan checkout, with no extra worktree.
+
+  **Until it merges, a wave task lives in its worktree, not in yours.** The
+  `task` tool has no `cwd`, so every subagent starts in your checkout, which
+  does not have the task's commits yet. So every dispatch for the task —
+  implementer, re-dispatch, escalation, reviewer, re-reviewer — carries its
+  worktree's absolute path: the implementer template's `Work from:` line
+  and its wave line (in a wave of two or more, the implementer runs only
+  the covering tests before committing; you run the full suite after the
+  wave merges), and for a reviewer a `Checkout: <path>` line saying to
+  read the changed files and their call sites there. Every command you
+  run for the task (its tests, a proven-trivial fix and its commit) runs
+  with the `bash` tool's `cwd` set to that path, and its branch
+  `sdd/<plan>/task-<N>` stands
+  in for HEAD in every review-package command for it. The skill's scripts
+  (`task-brief`, `review-package`) still run from the plan checkout, never
+  from a task worktree: they write into the workspace of the checkout they
+  run in, and a task worktree's copy is deleted with it. If the session
+  never got `/move`d into the plan's worktree (Setup), run every git command
+  that touches the plan branch with `cwd` set to the plan checkout, too.
 
 Template: [implementer-prompt.md](implementer-prompt.md)
 
@@ -476,9 +618,19 @@ Template: [implementer-prompt.md](implementer-prompt.md)
 
 Implementer subagents report one of four statuses. Handle each appropriately:
 
-**DONE:** Generate the review package (`bash scripts/review-package PLAN_FILE BASE HEAD`, from this skill's directory — it prints the unique file path it wrote; BASE is the commit you recorded before dispatching the implementer — never `HEAD~1`, which silently drops all but the last commit of a multi-commit task), then dispatch `sdd-reviewer` with the printed path.
+**DONE:** For a wave task, first check it worked where it should: its
+worktree has commits past BASE (`git -C <worktree> rev-list --count
+BASE..HEAD` is 1 or more), its worktree is clean (`git -C <worktree> status
+--porcelain` lists nothing beyond what it listed after the install; other
+untracked leftovers go back to the implementer), and
+your own checkout gained no changes. A task that wrote into your checkout
+goes back to its implementer with the paths. Then check the task's line in
+the review list.
+
+- **`review per-task`:** generate the review package (`bash scripts/review-package PLAN_FILE BASE HEAD`, from this skill's directory — it prints the unique file path it wrote; BASE is the commit you recorded before dispatching the implementer — never `HEAD~1`, which silently drops all but the last commit of a multi-commit task; for a wave task, its branch `sdd/<plan>/task-<N>` stands in for HEAD), then dispatch `sdd-reviewer` with the printed path.
+- **`review at final`:** run the covering test command from the brief yourself, once, in the task's checkout, with its output redirected to a file in the plan's workspace; read the tail. A brief that names no test (docs, configuration) gets the cheapest check that can fail instead (a build, a lint, a parse), or goes on the review list. That run is the only check this task gets before the final review, so never take the implementer's report in its place. A pass completes the task (step 5). A failure goes back to the implementer with the output file's path: rounds 1-2 resume it, round 3 is a fresh `sdd-escalation-implementer`, as in the fix loop, and each round ends when your rerun passes, with no re-review. A failure after round 3 is a plan the tests disagree with: stop and ask.
 
-**DONE_WITH_CONCERNS:** The implementer completed the work but flagged doubts. Read the concerns before proceeding. If the concerns are about correctness or scope, address them before review. If they're observations (e.g., "this file is getting large"), note them and proceed to review.
+**DONE_WITH_CONCERNS:** The implementer completed the work but flagged doubts. Read the concerns before proceeding. If the concerns are about correctness or scope, address them before review, and put a `review at final` task on the review list (`Task <N>: review per-task — <concern>`). A wave task that changed a file outside its brief's Files list broke its wave's independence: merge it after its wave's other tasks, and run their covering tests too on the merged tree. If the concerns are observations (e.g., "this file is getting large"), note them and proceed.
 
 **NEEDS_CONTEXT:** The implementer needs information that wasn't provided. Provide the missing context and re-dispatch. On omp, message the idle agent instead (`write agent://<id>`, the id from the ledger's `dispatched` line): it keeps its context and yields again. Only a write error means re-dispatch, with the context carried in the brief.
 
@@ -505,11 +657,13 @@ rush it into implementation.
 
 ### 3. Review the task
 
-Per-task reviews are task-scoped gates. The broad review happens once, at the
-final whole-branch review. Never skip the task review, and never accept a
-report missing either verdict — spec compliance AND task quality are both
-required. Implementer self-review never replaces the task review; both are
-needed.
+Task reviews run for the tasks on the review list (Setup); every other task
+gets its review from the final whole-branch review. Per-task reviews are
+task-scoped gates; the broad review happens once, at the end. For a task on
+the list, never skip the review, and never accept a report missing either
+verdict — spec compliance AND task quality are both required. Implementer
+self-review never replaces a review: for a listed task the task review is
+it, for any other the final review is.
 
 - Hand the reviewer its diff as a file: run this skill's
   `bash scripts/review-package PLAN_FILE BASE HEAD` and pass the reviewer the file path
@@ -527,7 +681,8 @@ needed.
   dispatch a task reviewer without a diff file.
 - **Reviewer inputs:** the task reviewer gets three paths — the same brief
   file, the report file, and the review package — plus the global
-  constraints that bind the task.
+  constraints that bind the task, and for a wave task a `Checkout:` line with
+  its worktree's absolute path (the re-reviewer gets the same line).
 - The global-constraints block you hand the reviewer is its attention
   lens. Copy the binding requirements verbatim from the plan's Global
   Constraints section or the spec: exact values, exact formats, and the
@@ -647,7 +802,9 @@ covering test files in the fix message — a one-line fix does not need the
 whole suite.
 
 **The re-review is scoped.** Run `bash scripts/review-package PLAN_FILE FIX_BASE HEAD`
-where FIX_BASE is the head the previous review saw, and dispatch
+where FIX_BASE is the head the previous review saw, as a commit SHA (for a
+wave task, its branch tip then: `git rev-parse sdd/<plan>/task-<N>`; never
+the branch name, which moves with the fix), and dispatch
 `sdd-rereviewer` with [re-review-prompt.md](re-review-prompt.md): the
 findings list, the brief, the report file, and the printed diff path. It
 has no bash, edit, or file-write tool and a four-call working budget plus its
@@ -693,17 +850,90 @@ a silent discard is forbidden.
 
 ### 5. Complete the task
 
-When the review comes back clean — or every open finding is parked with a
-ruling at the cap — append the completion line to the ledger in the same
-message as your other bookkeeping:
+A task is done when its review comes back clean, when every open finding is
+parked with a ruling at the cap, or, for a `review at final` task, when your
+own run of its covering tests passes.
+
+**A wave task merges first, and its tests run before the merge commits.**
+From the plan checkout, as soon as the task is done (wave tasks are
+independent, so their order does not matter):
+
+```bash
+git merge --no-ff --no-commit "sdd/<plan>/task-<N>"
+# run the task's covering tests on the merged tree, output to a workspace file
+git commit --no-edit
+```
+
+If git refuses to start the merge (`untracked working tree files would be
+overwritten`, or local changes to a file the merge touches), no merge is
+in progress, so `git merge --abort` has nothing to abort, and the fault is
+in your checkout, not the task: move the named untracked file out of the
+way (it is yours if setup or a script made it; otherwise ask), or commit or
+stash a tracked change of yours, then merge again. That costs the task no
+round.
+
+If the merge stops on a conflict, or the covering tests fail on the merged
+tree, run `git merge --abort` and send the task back to its implementer
+(`write agent://<id>`) with the plan branch's name and, for a failure, the
+output file's path: rebase onto the plan branch, fix what the merge
+exposed, re-run its covering tests, report again. Each such round counts
+toward the task's three rounds, with the fix loop's seats: round 3 is a
+fresh `sdd-escalation-implementer` whose dispatch names the plan branch,
+the worktree, and the conflict or the failing output file, framed as
+"rebase this task's branch onto the plan branch and make its covering
+tests pass on the result". A task whose three rounds were already spent in
+its review loop still gets one merge round, on that seat. Ledger each round
+as `Task <N>: rebased (<conflict | failing test>)`. A task that still
+conflicts or fails after its last round is never parked and never merged:
+ledger `Task <N>: merge stuck (<conflict | failing test>)`, merge the wave's
+other tasks, start no new wave, and stop and ask. A `review per-task` task
+whose rebase changed code gets its task review again, not a scoped
+re-review (there are no open findings to check, and the rebase may have
+changed anything): `review-package PLAN_FILE "$(git merge-base
+<plan-branch> sdd/<plan>/task-<N>)" sdd/<plan>/task-<N>` — a SHA, since the
+plan branch moves when a sibling merges — then `sdd-reviewer`, at `effort:
+"hi"` when `task.enableEffort` is on. A failure that belongs to a task
+already merged, not to this one: abort this merge, get a fix on the plan
+checkout (below), then merge this one.
+
+Right after the merge commit, ledger `Task <N>: merged (<sha7>)`, then
+remove the task's worktree and branch: `git worktree remove <path>`, then
+`git branch -d "sdd/<plan>/task-<N>"`. If the removal refuses, read
+`git -C <path> status --short`: use `--force` only when nothing it lists is
+missing from the merge; otherwise ledger it and leave it for Finish.
+
+After the last task of a wave of two or more merges, run the full suite once
+in the plan checkout, output to a workspace file, and ledger `Wave <K>:
+suite pass` or `Wave <K>: suite fail (<failing tests>)`. Implementers ran
+only their covering tests, in worktrees without their siblings, so this is
+the first full run on the combined tree. Any failure here gets a fix on the
+plan checkout before the next wave or the final review — the last wave's
+suite runs too.
+
+**A fix on the plan checkout:** write a brief,
+`<workspace>/wave-<K>-fix-brief.md`: the failing tests, the output file, the
+test command to make pass, and the wave's merge commits; when one merged
+task owns the failure, that task's brief and report paths. Dispatch a fresh
+`sdd-implementer` with the implementer template, task `Wave <K> fix`,
+`Work from:` the plan checkout, that brief, and
+`<workspace>/wave-<K>-fix-report.md` as its report file, and ledger `Wave
+<K>: fix dispatched (implementer <id>)`. Merge nothing else while it works.
+When it reports, run the full suite yourself and ledger `Wave <K>: fix
+(<failing tests>; commits <a7>..<b7>)`, then `Wave <K>: suite pass`, or
+`Wave <K>: suite fail (after fix: <failing tests>)` and stop and ask.
+
+Then append the completion line to the ledger in the same message as your
+other bookkeeping:
 
 - `Task <N>: complete (commits <base7>..<head7>, review clean)`
 - `Task <N>: complete (commits <base7>..<head7>, <K> parked)` after a
   tripped breaker
+- `Task <N>: complete (commits <base7>..<head7>, review at final — tests: <command>, pass)`
 
-Then mark the todo complete and move on. Never move to the next task while
-the review has open Critical/Important issues that are neither fixed nor
-parked-with-ruling at the cap.
+Then mark the todo complete. Start the next wave only when every task of
+this one is complete and merged; never start it while a task has open
+Critical/Important issues that are neither fixed nor parked-with-ruling at
+the cap.
 
 ## Final Review
 
@@ -713,13 +943,15 @@ branch started from, e.g. `git merge-base main HEAD`) and include the
 printed path in the final review dispatch, so the final reviewer reads
 one file instead of re-deriving the branch diff with git commands. Dispatch
 `sdd-final-reviewer` (the deepest seat, once per plan — see Agent
-Selection) with a `task` that says the plan ran subagent-driven — every
-task went through its task review, except the fixes you applied yourself on
-the proven-trivial route, which skipped the re-review — and names: the
-package path, the plan/spec paths, and the ledger's deferred-minor and
-parked-with-ruling lines verbatim, plus every `Task <N>: applied … proof:`
-line (the reviewer checks those fixes as if unreviewed) and any
-`high-risk diff` line (so the last review spends its depth there). Do not
+Selection) with a `task` that says the plan ran subagent-driven and names:
+the package path; the plan/spec paths; every `review per-task` task with its
+class, which had its own task review (so the last review spends its depth
+on the seams around them); every `review at final` task, which had none, so
+the final reviewer does the task review's work on it first; the ledger's
+deferred-minor and parked-with-ruling lines verbatim; every `rebased` and
+`Wave <K>: fix` line (code no task review saw); and every `Task <N>:
+applied … proof:` line, a fix you applied yourself on the proven-trivial
+route without a re-review (the reviewer checks those as if unreviewed). Do not
 paste requesting-code-review's `code-reviewer.md` into the dispatch — that
 template asks a prose "Ready to merge?" and has no slot for the package or
 the ledger; the agent reads that file's review rubric itself. The agent
@@ -757,6 +989,11 @@ took on your human partner's behalf reach them — they read it and rework
 whatever you got wrong. A ruling that dies with the workspace was a decision
 made in secret.
 
+Check that no wave left anything behind: `git worktree list` shows none of
+this plan's task worktrees, and `git branch --list 'sdd/<plan>/*'` is empty.
+Remove a leftover as in Complete the task, or name it in your final message
+if it holds work the merge does not.
+
 When the final whole-branch review is clean and its fixes are merged,
 delete this plan's workspace (`rm -rf <workspace>`) — the git history is
 the record now. Sibling directories belong to other plans; leave them
@@ -774,7 +1011,9 @@ Use superpowers:finishing-a-development-branch.
 | "The reviewer will just find something new anyway" | Scoped re-reviews verify fixes; they cannot wander. New findings on untouched code go to the ledger, not the loop. |
 | "This finding is obviously wrong, I'll drop it" | You adjudicate only at the cap, and every ruling is a ledger entry. Silent discards are forbidden. |
 | "The fix was small, skip the re-review" | Small is not the test — proven is. If you cannot run one command that proves the exact property (and ledger it), the round ends with a scoped re-review. |
-| "Reviews slow the loop down" | The loop without reviews is just unverified churn. Reviews are the loop's brakes and steering. |
+| "This auth change is one line — review it at final" | Risk class, not size, puts a task on the review list. One line of auth gets its own review. |
+| "The report says the tests pass, skip my run" | For a `review at final` task, your run is the only check before the merge. Run it. |
+| "These two tasks barely touch — same wave" | A shared file or a Consumes/Produces link means separate waves. A conflict costs a rebase round; a silent clash between them costs the final review. |
 | "Ledger bookkeeping is overhead" | The ledger is what survives compaction. Controllers without one have re-dispatched entire completed task sequences. |
 | "The implementer spawned its own reviewer — free extra assurance" | It's a duplicate seat reviewing the same diff; the task review is the gate. A worker-spawned reviewer is a defect to flag, not rigor. |
 
@@ -783,16 +1022,18 @@ Use superpowers:finishing-a-development-branch.
 ```
 You: I'm using Subagent-Driven Development to execute this plan.
 
-[Setup: worktree verified; on omp, session moved into it with /move]
+[Setup: the approval named a new branch feat/hooks in this checkout — git switch -c feat/hooks, project setup and baseline tests in place, no worktree, no /move]
 [Read plan file once: docs/plans/feature-plan.md]
 [Resolve workspace: bash scripts/sdd-workspace docs/plans/feature-plan.md — no ledger inside, fresh start]
 [On omp: scripts dir resolved with realpath skill://subagent-driven-development/scripts and added to the ledger as "SDD scripts: <dir>"; each script runs as bash <dir>/<name>]
 [Create todos for all tasks]
+[Pre-flight scan → ledger: Tasks 1, 3, 4: review at final · Task 2: review per-task — persisted data (repair rewrites stored records) · Wave 1: tasks 1, 3 · Wave 2: tasks 2, 4]
 
-Task 1: Hook installation script
+Wave 1: Task 1 (hook installation script) and Task 3 (help text)
 
-[Run task-brief for Task 1; dispatch implementer with brief + report paths + context]
-[Ledger: Task 1: dispatched (BASE a1b2c3d, implementer Impl1)]
+[Two worktrees: omp worktree add -b sdd/feature-plan/task-1 …, and task-3; npm ci in each, and a check that the code resolves in the worktree]
+[Run task-brief for Tasks 1 and 3; ONE task call with two implementer items, each naming its worktree]
+[Ledger: Task 1: dispatched (BASE a1b2c3d, implementer Impl1, worktree /home/me/.omp/wt/app-feature-plan-task-1)]
 
 Implementer: "Before I begin - should the hook be installed at user or system level?"
 
@@ -804,23 +1045,23 @@ Implementer: [Later]
   - Self-review: Found I missed --force flag, added it
   - Committed
 
-[Run review-package PLAN_FILE BASE HEAD; dispatch sdd-reviewer with the printed path]
-sdd-reviewer: spec_compliance: compliant · task_quality: approved
-  strengths: ["Good test coverage", "clean"] · findings: []
-
-[Ledger: Task 1: complete (commits a1b2c3d..d4e5f6a, review clean)]
+[Task 1 is review at final: run the brief's covering test in its worktree — npm test test/install.test.js: 5/5 passing]
+[git merge --no-ff --no-commit sdd/feature-plan/task-1; covering test on the merged tree passes; git commit --no-edit]
+[Ledger: Task 1: merged (9a8b7c6); worktree and branch removed]
+[Ledger: Task 1: complete (commits a1b2c3d..d4e5f6a, review at final — tests: npm test test/install.test.js, pass)]
+[Task 3 likewise; its merge was the wave's last, so the full suite runs once in the plan checkout — Ledger: Wave 1: suite pass]
 
-Task 2: Recovery modes
+Wave 2: Task 2 (recovery modes, review per-task) and Task 4
 
 [Run task-brief for Task 2; dispatch implementer with brief + report paths + context]
-[Ledger: Task 2: dispatched (BASE d4e5f6a, implementer Impl2)]
+[Ledger: Task 2: dispatched (BASE e5f6a7b, implementer Impl2, worktree /home/me/.omp/wt/app-feature-plan-task-2)]
 
 Implementer: [No questions]
   - Added verify/repair modes
   - 8/8 tests passing
   - Committed
 
-[Run review-package PLAN_FILE BASE HEAD; dispatch sdd-reviewer with the printed path]
+[Run review-package PLAN_FILE BASE sdd/feature-plan/task-2; dispatch sdd-reviewer with the printed path]
 sdd-reviewer: spec_compliance: issues · task_quality: needs_fixes
   spec_issues: ["Missing: progress reporting (spec says 'report every 100 items')"]
   findings: [{severity: Important, location: src/recovery.js:7, body: "Magic number (100)"}]
@@ -829,19 +1070,20 @@ sdd-reviewer: spec_compliance: issues · task_quality: needs_fixes
 Implementer: Added progress reporting, extracted PROGRESS_INTERVAL constant.
   Re-ran test/recovery.test.js — 10/10 passing. Fix report appended.
 
-[Run review-package PLAN_FILE FIX_BASE HEAD; dispatch sdd-rereviewer]
+[Run review-package PLAN_FILE FIX_BASE sdd/feature-plan/task-2; dispatch sdd-rereviewer]
 sdd-rereviewer: round_verdict: all_addressed
   finding_verdicts: [{Missing progress reporting: ADDRESSED, src/recovery.js:41},
                      {Magic number: ADDRESSED, src/recovery.js:7}]
   new_breakage: [] · out_of_scope: []
 
-[Ledger: Task 2: fix round 1/3 (2 addressed, 0 open; commits d4e5f6a..b7c8d9e)]
-[Ledger: Task 2: complete (commits d4e5f6a..b7c8d9e, review clean)]
+[Ledger: Task 2: fix round 1/3 (2 addressed, 0 open; commits e5f6a7b..b7c8d9e)]
+[Merge sdd/feature-plan/task-2 the same way; Ledger: Task 2: merged (c3d4e5f)]
+[Ledger: Task 2: complete (commits e5f6a7b..b7c8d9e, review clean)]
 
 ...
 
-[After all tasks]
-[Run review-package PLAN_FILE MERGE_BASE HEAD; dispatch sdd-final-reviewer]
+[After the last wave]
+[Run review-package PLAN_FILE MERGE_BASE HEAD; dispatch sdd-final-reviewer naming Task 2's class, and Tasks 1, 3, 4 as review at final]
 [Read the full result at agent://<id>]
 sdd-final-reviewer: Ledger triage: deferred minors — none block merge. **Mergeable:** yes