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

• WorkerHub.ApproveReview (+ MCP ReviewTask approve): if the task has children, invoke PlanningMergeOrchestrator (parent worktree if Active + each Done child in order) then transition parent → Done; on child conflict keep WaitingForReview and surface the conflicting child. If no children, keep the existing TaskMergeService.ApproveAndMergeAsync path.
• Retire WorkerHub.MergeAllPlanning + its UI button/command and any now-dead orchestrator entry that only MergeAllPlanning used (keep the orchestrator itself).
• Sync test fakes for IWorkerClient/WorkerHub if signatures changed.
• Tests: approving a parent with two Done children merges both then sets Done; a conflicting second child keeps the parent in WaitingForReview.

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.