ClaudeDo/docs/superpowers/plans/2026-06-09-unify-parent-task-model-plan.md

Plan — Unify the parent-task model

Spec: docs/superpowers/specs/2026-06-09-unify-parent-task-model-design.md

Subagents: sonnet. Stage files explicitly by path (never git add -A). TDD. Build with -c Release per project. Commit per task (Conventional Commits).

Task 1 — Single parent-advance path

• Rename TaskStateService.TryAdvanceImprovementParentAsync → TryAdvanceParentAsync.
• Make it advance any WaitingForChildren parent → WaitingForReview when all children are terminal, and advance a parent with zero children straight to WaitingForReview.
• In OnChildTerminalAsync: drop the TryCompleteParentAsync call; keep _chain.OnChildFinishedAsync; call the renamed advance method for all parents.
• Tests: extend WaitingForChildrenLifecycleTests — (a) improvement parent still advances; (b) a WaitingForChildren parent whose children are a sequential chain advances only after the last one is terminal; (c) zero-children parent advances.

Task 2 — Delete TryCompleteParentAsync

• Remove TaskRepository.TryCompleteParentAsync (TaskRepository.cs:477-502) and any remaining references.
• Update src/ClaudeDo.Data/CLAUDE.md (drop it from the TaskRepository helper list).
• Build Data + Worker; fix references.

Task 3 — Planning finalize enters WaitingForChildren

• TaskStateService.FinalizePlanningAsync: in the same ExecuteUpdateAsync, set Status = WaitingForChildren alongside PlanningPhase = Finalized / PlanningFinalizedAt.
• Verify PlanningSessionManager.FinalizeAsync ordering: finalize (→ WaitingForChildren) before SetupChainAsync enqueues child[0]. Adjust only if ordering is wrong.
• Tests: finalizing a planning parent with N children leaves it WaitingForChildren; after the chain completes it is WaitingForReview (not Done); a planning parent with zero finalized children lands in WaitingForReview.

Task 4 — Approve merges the whole unit

Decision: full UX consolidation. Approve becomes the single entry for reviewing and merging any task; the separate planning-merge views are folded into the review panel. The PlanningMergeOrchestrator (which already merges the unit + sets the parent Done for both planning and improvement, with conflict continue/abort) is reused as the engine; only its entry/UI moves.

Backend:

• WorkerHub.ApproveReview: for a parent that has children, drive PlanningMergeOrchestrator.StartAsync (event-based: PlanningMergeStarted / PlanningSubtaskMerged / PlanningMergeConflict / PlanningMergeAborted / PlanningCompleted) instead of the one-shot ApproveAndMergeAsync. Childless tasks keep ApproveAndMergeAsync. Conflict resolution still goes through ContinuePlanningMerge / AbortPlanningMerge.
• Keep the orchestrator, ContinuePlanningMerge, AbortPlanningMerge, GetPlanningAggregate, BuildPlanningIntegrationBranch. Remove the now-redundant standalone MergeAllPlanning hub method (approve is the entry).
• (Optional cleanup) route the orchestrator's FinalizeParentDoneAsync through TaskStateService so Status writes stay centralized; low priority.

UI (Avalonia, MVVM — visual-verification gaps, flag for user):

• The review panel (DetailsIslandViewModel / its view) is the single approve+merge surface. For a child-bearing parent in WaitingForReview, approve shows the unit-merge progress + per-subtask state, the aggregate/integration diff preview, and conflict continue/abort — all inline in the review panel.
• Remove the separate planning-merge view(s)/commands and the standalone "Merge all" button; re-wire their PlanningMerge* event handlers into the review panel VM.
• Sync IWorkerClient + hand-rolled test fakes in both UI/Worker test projects.

Tests: approving a parent with two Done children merges both then sets Done; a conflicting second child surfaces the conflict and pauses (continue/abort) without losing the parent's WaitingForReview/merge state.

Task 5 — Cancellable WaitingForChildren parent

• Add TaskStatus.WaitingForChildren to the CancelAsync guard.
• Test: a parent in WaitingForChildren can be cancelled.

Task 6 — Docs

• src/ClaudeDo.Worker/CLAUDE.md: add WaitingForChildren to the Status table + transition diagram; document the unified parent flow and approve-merges-unit; remove MergeAllPlanning from the Hub method list.
• src/ClaudeDo.Data/CLAUDE.md: add WaitingForChildren to the TaskEntity status list.
• Root CLAUDE.md: update the "Task status flow" convention line.

Verify

• dotnet test for Worker.Tests + Data.Tests (-c Release).
• UI flows (planning finalize → review → approve-merge; improvement parent; retired MergeAllPlanning button) are visual-verification gaps — flag for the user to run the app; do not claim they work from tests alone.