# 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.