docs: child base off parent HEAD, shared planning-style tree merge

Children fan out from the parent's worktree HEAD and merge via a
generalized planning orchestrator (parent branch + children); child
roadblocks roll up to the parent review card.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

docs/superpowers/specs/2026-06-04-child-tasks-and-improvement-loop-design.md

@@ -39,6 +39,33 @@ WaitingForChildren → Cancelled          cancel                 (new)
 - Children run automatically and reach `Done` on success without their own review
   gate (a per-child review would stall the loop). Each child still produces its
   own worktree/commit; those worktrees are surfaced under the parent for merge.
+- Children emit `CLAUDEDO_BLOCKED:` markers like any run (see the prompt-overhaul
+  spec). Each child's collected problems roll up onto the **parent's** review card,
+  so a parent in `WaitingForReview` shows "child N reported a problem" alongside
+  its own roadblocks.
+
+## Worktree topology & merge
+
+The correctness rule that makes this work:
+
+- **Children base off the parent's worktree HEAD, not the list's base branch.**
+  The parent's code work lives only on `claudedo/{parentId}` until merged, so a
+  child refactoring code the parent just wrote must branch from the parent's HEAD
+  to see it. (Planning children base off the target branch because a planning
+  parent writes no code — improvement parents do, hence the difference.) The
+  per-run worktree setup takes the base commit from the parent task's recorded
+  worktree HEAD when `ParentTaskId` is set and the parent is a non-planning task.
+- **Fan-out:** all children branch off the same parent HEAD and run independently
+  (parallel allowed). Parent-dependency is always satisfied; sibling overlaps
+  surface later as merge conflicts.
+- **Merge reuses the planning orchestrator,** generalized into a shared
+  "tree merge": build an integration branch off the target, then sequentially
+  `merge --no-ff` the **parent's own branch** followed by each child branch,
+  pausing on conflict (continue / abort), exactly as `PlanningMergeOrchestrator`
+  /`PlanningAggregator` do today. Approving the parent triggers this one guided
+  flow, merging parent + all children in as few steps as possible. Because
+  children descend from the parent HEAD, the parent's commits are shared ancestors
+  and merge cleanly ahead of the children.
 - The parent advances to `WaitingForReview` once **all** children are terminal —
   counting `Done`, `Failed`, and `Cancelled`, so a failed child can't wedge the
   parent forever. Failed/cancelled children are flagged on the review card.
@@ -113,7 +140,9 @@ SuggestImprovement(title, description) and stay focused on the task at hand.
 - **New status chip** for `WaitingForChildren` (e.g. amber "waiting on N
   improvements") with its own color in `StatusColorConverter`.
 - **Review card** for a parent in `WaitingForReview` lists child outcomes
-  (done/failed) and exposes their worktrees for merge.
+  (done/failed) and their rolled-up `CLAUDEDO_BLOCKED` problems, and drives the
+  shared tree-merge (parent + children) via the planning-style sequential flow
+  with conflict pause/continue/abort.
 
 ## Data / migration
 
@@ -132,20 +161,21 @@ SuggestImprovement(title, description) and stay focused on the task at hand.
   (e.g. `TaskRunMcpService.SuggestImprovement`) + `TaskRunMcpContextAccessor` +
   token auth (mirrors `PlanningTokenAuth`).
 - `src/ClaudeDo.Worker/Planning/*` — refactor planning to consume the shared
-  child-completion coordinator; keep chain-specific advancement local.
+  child-completion coordinator and the shared tree-merge; keep chain-specific
+  advancement local. Generalize `PlanningMergeOrchestrator` / `PlanningAggregator`
+  into a reusable tree-merge that also folds in the parent's own branch.
+- Worktree setup (`TaskRunner` / `WorktreeManager`) — base an improvement-child's
+  worktree on the parent task's recorded worktree HEAD instead of the list base.
 - UI — tree grouping, `WaitingForChildren` chip/color, parent review card with
-  child outcomes.
+  child outcomes + rolled-up roadblocks + the merge flow.
 - Tests — offload tool stamps parent/createdBy + rejects nested calls;
-  parent → `WaitingForChildren` → `WaitingForReview` lifecycle; planning
+  parent → `WaitingForChildren` → `WaitingForReview` lifecycle; child worktree
-  regression (still reaches Done).
+  bases off parent HEAD; tree-merge folds parent + children; planning regression
+  (still reaches Done).
 
 ## Open questions for review
 
-1. **Child review/merge:** children reach `Done` without review and leave
+1. **Failed child:** parent still advances to `WaitingForReview` with the failure
-   worktrees for manual merge. Is reviewing the whole tree at the parent enough,
-   or do you want per-child merge controls in the parent's review card? (Default:
-   surface child worktrees under the parent.)
-2. **Failed child:** parent still advances to `WaitingForReview` with the failure
    flagged (default), vs. parent → `Failed` if any child failed.
 
 ## Out of scope