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