From 84fd2c11a09021feeec6f60c30c9d61d64adc8f4 Mon Sep 17 00:00:00 2001 From: mika kuns Date: Thu, 4 Jun 2026 13:45:54 +0200 Subject: [PATCH] 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 --- ...child-tasks-and-improvement-loop-design.md | 50 +++++++++++++++---- 1 file changed, 40 insertions(+), 10 deletions(-) diff --git a/docs/superpowers/specs/2026-06-04-child-tasks-and-improvement-loop-design.md b/docs/superpowers/specs/2026-06-04-child-tasks-and-improvement-loop-design.md index d47cdb2..f39b6ac 100644 --- a/docs/superpowers/specs/2026-06-04-child-tasks-and-improvement-loop-design.md +++ b/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 - regression (still reaches Done). + parent → `WaitingForChildren` → `WaitingForReview` lifecycle; child worktree + 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 - 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 +1. **Failed child:** parent still advances to `WaitingForReview` with the failure flagged (default), vs. parent → `Failed` if any child failed. ## Out of scope