ClaudeDo/docs/superpowers/specs/2026-04-24-planning-merge-all-design.md

Planning Merge-All & Subtask Visibility — Design

Date: 2026-04-24 Status: Approved design, ready for implementation planning

Problem

Three concrete issues with the current Planning feature:

1. Queued subtasks are not visible in the Queue List. When a planning session finalizes, its subtasks transition to Queued, but the Queue List's hierarchy rules only show children when their Planning parent is expanded. A collapsed (or already-Planned) parent effectively hides the subtasks.
2. Completed subtasks vanish from view. Once a subtask becomes Done, the regroup logic moves it to the "Completed" bucket. Users expect subtasks to remain visible under their Planning parent until the Planning task itself is marked Done.
3. No aggregated view or bulk merge. Each subtask must be merged individually through its worktree. There is no way to see a combined diff of all changes produced by a Planning session, and no "merge everything" action.

Goals

• Treat Planning subtasks as belonging to their Planning parent for visibility and lifecycle purposes.
• Provide a single aggregated diff view that shows all changes produced by a Planning session.
• Provide a single "Merge all" action that sequentially merges all subtasks, with a usable conflict-resolution flow.
• Auto-complete the Planning task when all merges succeed.

Non-goals

• Building a full-featured in-app diff editor. Textual unified diff is acceptable for now; conflict editing happens in VS Code.
• Persisting Merge-all progress across worker restarts. Restart clears in-memory orchestration state; user re-starts Merge-all (already-merged subtasks are skipped because their worktrees are Merged).
• Modifying how individual subtasks are created, executed, or finalized.

Design

1. Visibility model

Planning subtasks are exclusively children of their Planning parent until the Planning task transitions to Done. The Planning parent acts as a roll-up in the Queue List.

• Tasks with a non-null ParentTaskId are excluded from all virtual lists (virtual:queued, virtual:running, CompletedItems, etc.) as separate rows.
• A Planning/Planned task is included in virtual:queued if any child is Queued, and in virtual:running if any child is Running.
• Children are always attached under their parent in the task tree; expansion purely controls visual collapse.
• When Merge-all completes successfully, the Planning task is set to Done and the entire subtree moves to Completed together.
• Status badge on the Planning row summarizes children (e.g., 3/5 queued, 2 running, 1 failed).

2. Planning detail panel

Extends the existing task detail view. New elements when the selected task is a Planning task:

• Subtasks list. Grouped by status badge (Queued / Running / Done / Failed). Each row preserves existing per-subtask actions (view logs, open worktree, individual merge).
• Merge target dropdown. Single target branch that applies to all subtasks in Merge-all. Defaults to the branch that was current when the Planning session started.
• [Review combined diff] button. Opens the Aggregated Diff Viewer. Enabled as soon as any subtask has produced a diff.
• [Merge all subtasks] button. Orchestrates sequential merge + auto-Done. Disabled until every subtask is Done and every worktree is Active or Merged (no Discarded / Kept). Tooltip explains why when disabled (e.g., "2 subtasks still running", "1 subtask failed — resolve first", "1 worktree was discarded").
• Existing per-subtask merge action remains available; Merge-all is additive.

3. Aggregated diff viewer

New Avalonia view PlanningDiffView + PlanningDiffViewModel, opened as a modal or dedicated tab.

Default — grouped by subtask:

• Left pane: subtask list in creation order with title • +added −deleted • N files.
• Right pane: selected subtask's diff. Reuse any existing diff-rendering control; if none exists, render unified diff text with basic syntax coloring (monospace, minimal decoration).
• Summary stats come from WorktreeEntity.DiffStat. Raw diff comes from git diff <base>..<head> executed in each subtask's worktree via GitService. Cached in memory per subtask until the subtask's HEAD moves.

Toggle — "Preview combined diff":

• Calls PlanningAggregator.BuildIntegrationBranchAsync(planningTaskId, targetBranch, ct):
  1. Create/reset branch planning/<slug>-integration off the current merge target.
  2. Merge each subtask's branch sequentially with --no-ff.
  3. On conflict during preview: abort the merge, reset the integration branch, surface a warning identifying which two subtasks conflict. Grouped view remains available.
  4. On success: compute git diff <merge-target>..planning/<slug>-integration and render as a single flat unified diff.
• Toggle flips back to grouped mode.

Integration-branch lifecycle: scratch artifact, rebuilt on every preview (deleted + recreated). Cleaned up when the Planning task is marked Done or when the Planning session is discarded.

4. Merge-all orchestration

Happy path (PlanningMergeOrchestrator.StartAsync):

1. Pre-flight checks — fail fast with a clear message on any:
   • Every subtask is Done.
   • Every subtask's worktree is Active or Merged (no Discarded / Kept). Merged worktrees are allowed so that an interrupted Merge-all can be restarted.
   • Repo working tree is clean.
   • No mid-merge in progress in the target repo.
2. For each subtask in creation order, skip if its worktree is already Merged (idempotent restart). Otherwise call TaskMergeService.MergeAsync with removeWorktree: true and leaveConflictsInTree: true. Each success flips the worktree to Merged.
3. After the last successful merge:
   • Set Planning task Status = Done.
   • Call PlanningAggregator.CleanupIntegrationBranchAsync if the integration branch exists.
   • Emit PlanningCompleted so the UI removes the row from the Queue List.

Conflict path:

1. MergeAsync with leaveConflictsInTree: true reports a conflict, leaves the repo in a mid-merge state, and returns the conflicted file paths (git diff --name-only --diff-filter=U).
2. Orchestrator halts the loop, stores the in-progress state (remaining subtasks, target branch, current subtask id) in memory, and emits PlanningMergeConflict(planningTaskId, subtaskId, conflictedFiles).
3. The UI opens the Conflict Resolution dialog — see §5.
4. On ContinueAsync: calls TaskMergeService.ContinueMergeAsync(subtaskId) which stages the recorded files and runs git commit --no-edit. Flips worktree to Merged. Loop resumes with remaining subtasks.
5. On AbortAsync: calls TaskMergeService.AbortMergeAsync(subtaskId) which runs git merge --abort. Planning stays in Planned. Already-merged earlier subtasks remain Merged. Orchestration state cleared.

Idempotent restart: if the worker restarts mid Merge-all, in-memory state is lost. A fresh StartAsync re-runs pre-flight; already-Merged worktrees are skipped by the loop (their status gates them out). User experience: "I clicked Merge all again and it continued from where it left off."

5. Conflict Resolution dialog

Avalonia modal (ConflictResolutionView + ConflictResolutionViewModel).

• Header: Conflicts in subtask: <title> merging into <target-branch>.
• File list: full absolute paths of conflicted files.
• [Open all in VS Code] — for each file, spawn code <absolute-path> via Process.Start. If code is not on PATH, show an inline error row with the file list so the user can copy paths manually. No popup-on-popup.
• [I've resolved — continue] — calls ContinuePlanningMerge(planningTaskId) hub method, closes dialog. The orchestration loop continues with the remaining subtasks.
• [Abort this merge] — calls AbortPlanningMerge(planningTaskId) hub method, closes dialog. Planning stays Planned.

6. Data model

No schema changes.

• Conflicted files are queried from git on demand (git diff --name-only --diff-filter=U) while the merge is in progress.
• Integration branch name is derived from the Planning task slug: planning/<slug>-integration.
• Planning completion uses existing TaskStatus.Done.

7. Services

New:

• PlanningAggregator (src/ClaudeDo.Worker/Planning/PlanningAggregator.cs)

  • GetAggregatedDiffAsync(planningTaskId, ct) — returns per-subtask diff entries.
  • BuildIntegrationBranchAsync(planningTaskId, targetBranch, ct) — creates/resets the integration branch, merges subtasks sequentially, returns (success, combinedDiff) or (failure, firstConflictSubtaskId, conflictedFiles). Always leaves the integration branch in a consistent state (aborts + resets on failure).
  • CleanupIntegrationBranchAsync(planningTaskId, ct) — deletes the integration branch.

• PlanningMergeOrchestrator (singleton, src/ClaudeDo.Worker/Planning/PlanningMergeOrchestrator.cs)

  • Owns in-memory state per planning task: { remainingSubtasks, targetBranch, currentSubtaskId }.
  • StartAsync(planningTaskId, targetBranch), ContinueAsync(planningTaskId), AbortAsync(planningTaskId).
  • Emits SignalR events: PlanningMergeStarted, PlanningSubtaskMerged, PlanningMergeConflict, PlanningMergeAborted, PlanningCompleted.

Modified:

• TaskMergeService

  • MergeAsync gets a leaveConflictsInTree: bool parameter (default false). When true, on conflict records conflicted files on the returned result, does not call git merge --abort.
  • New ContinueMergeAsync(taskId, ct) — stages the recorded conflicted files and runs git commit --no-edit, flips worktree to Merged.
  • New AbortMergeAsync(taskId, ct) — runs git merge --abort, restores pre-merge state.
  • Existing callers unaffected by the default.

• WorkerHub — new methods:

  • GetPlanningAggregate(planningTaskId)
  • BuildPlanningIntegrationBranch(planningTaskId, targetBranch)
  • MergeAllPlanning(planningTaskId, targetBranch)
  • ContinuePlanningMerge(planningTaskId)
  • AbortPlanningMerge(planningTaskId)

• TasksIslandViewModel.Regroup

  • Exclude tasks with ParentTaskId != null from virtual lists.
  • Include Planning parents in virtual:queued / virtual:running based on children's statuses.
  • Keep children attached to parent in the tree at all times until Planning is Done.

8. UI components (new)

• PlanningDiffView + PlanningDiffViewModel — aggregated diff viewer (§3).
• ConflictResolutionView + ConflictResolutionViewModel — conflict dialog (§5).
• Planning Detail section inside the existing task detail pane — subtask list + merge target dropdown + two buttons (§2).

Error handling

• Pre-flight failures — surface as inline errors in the Planning detail panel. No merge work attempted.
• Preview-build conflict — keep grouped diff available; show a warning banner identifying the conflicting pair of subtasks.
• Merge-all conflict — Conflict Resolution dialog (§5). The failed subtask's worktree stays Active; prior successes stay Merged.
• VS Code not on PATH — inline error row in the Conflict dialog with copyable file paths.
• Worker restart mid-merge — in-memory state lost; restarting Merge-all is idempotent because merged worktrees are skipped by status gating.

Testing

Convention: xUnit integration tests with real SQLite and real git (tests/ClaudeDo.Worker.Tests).

PlanningAggregatorTests — real git fixture

• GetAggregatedDiffAsync returns one entry per subtask with correct stats.
• BuildIntegrationBranchAsync with non-conflicting subtasks — success, branch contains all changes.
• BuildIntegrationBranchAsync with conflicting subtasks — failure, branch reset (not mid-merge), correct subtask id and file list reported.
• Rebuild overwrites a stale integration branch.
• CleanupIntegrationBranchAsync removes the branch.

PlanningMergeOrchestratorTests — real git + real DB

• Happy path: all subtasks merge → worktrees Merged, Planning Done, PlanningCompleted emitted.
• Conflict path: first subtask conflicts → repo left in conflict state, PlanningMergeConflict emitted with correct file list, worktree stays Active, Planning stays Planned.
• ContinueAsync after conflict: resolution commits, loop proceeds, final state Done.
• AbortAsync after conflict: merge --abort restores clean state, earlier merged subtasks remain Merged, Planning stays Planned.
• Pre-flight rejection: running subtask, failed subtask, dirty repo — each returns the expected error with no side effects.
• Idempotent restart: partial merge + fresh StartAsync — already-Merged worktrees skipped.

TaskMergeServiceConflictTests (extending existing tests)

• MergeAsync(leaveConflictsInTree: true) on conflict: no merge --abort, returns conflicted files, worktree state unchanged.
• ContinueMergeAsync: completes in-progress merge, flips worktree to Merged.
• AbortMergeAsync: runs merge --abort, restores clean state.

TasksIslandRegroupTests — ViewModel unit tests, no DB

• Queued subtask with a Planning parent is NOT in virtual:queued as its own row.
• Planning parent with any Queued child IS in virtual:queued.
• Done subtask stays nested under Planning parent until Planning is Done.
• After Planning is marked Done, parent + children move to Completed together.

Manual smoke test (documented in PR description):

• End-to-end planning session in the app: create plan, finalize, let subtasks run.
• Open aggregated diff, toggle Preview combined.
• Merge-all happy path.
• Merge-all conflict path with VS Code dialog open/continue.
• Merge-all conflict path abort.

Open questions

None at this stage. All decisions from the brainstorming session are captured above.