docs(worker): spec + plan for unifying the parent-task model

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

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

@@ -0,0 +1,69 @@
+# 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.