refactor(data): retire legacy TaskStatus values and backfill existing rows

Slice 6 of the worker state and queue consolidation refactor.

* Drop Manual, Planning, Planned, Draft, Waiting from the TaskStatus enum
  and from the EF value converter; only the lifecycle values remain
  (Idle, Queued, Running, Done, Failed, Cancelled).
* Add migration RetireLegacyTaskStatus that rewrites existing rows:
  manual/draft -> idle, planning -> idle+planning_phase=active,
  planned -> idle+planning_phase=finalized, waiting -> queued+blocked_by
  derived from sort_order via a CTE with LAG().
* Reroute every call site that compared/set legacy values to the new
  three-field model (Status + PlanningPhase + BlockedByTaskId), including
  the planning repo helpers, MCP services, the planning chain coordinator,
  and the UI view-models. TaskRowViewModel now exposes PlanningPhase to
  drive the planning badge.
* Refresh Worker/CLAUDE.md and Data/CLAUDE.md, the docs/plan.md status
  section, and the planning verification notes in docs/open.md.

src/ClaudeDo.Data/CLAUDE.md

@@ -4,7 +4,7 @@ Shared data layer: models, repositories, SQLite infrastructure, and git operatio
 
 ## Models
 
-- **TaskEntity** — Id, ListId, Title, Description, Status (Manual|Queued|Running|Done|Failed), ScheduledFor, Result, LogPath, timestamps, CommitType, Model / SystemPrompt / AgentPath (nullable overrides), IsStarred, IsMyDay, Notes
+- **TaskEntity** — Id, ListId, Title, Description, Status (`Idle|Queued|Running|Done|Failed|Cancelled`), PlanningPhase (`None|Active|Finalized` — parent-only), BlockedByTaskId (nullable FK to predecessor in a chain), ScheduledFor, Result, LogPath, timestamps, CommitType, Model / SystemPrompt / AgentPath (nullable overrides), IsStarred, IsMyDay, Notes, ParentTaskId, PlanningSessionId, PlanningSessionToken, PlanningFinalizedAt, CreatedBy. Legacy values `Manual`/`Planning`/`Planned`/`Draft`/`Waiting` were retired; existing rows backfill automatically via the `RetireLegacyTaskStatus` migration.
 - **ListEntity** — Id, Name, WorkingDir, DefaultCommitType, CreatedAt
 - **ListConfigEntity** — ListId (PK, 1:1 with list), Model, SystemPrompt, AgentPath (all nullable)
 - **TagEntity** — Id (autoincrement), Name (unique)
@@ -16,7 +16,7 @@ Shared data layer: models, repositories, SQLite infrastructure, and git operatio
 
 All repositories use EF Core LINQ queries via `ClaudeDoDbContext`. Exception: `TaskRepository.GetNextQueuedAgentTaskAsync` uses `FromSqlRaw` for atomic queue claim.
 
-- **TaskRepository** — CRUD, status transitions (`MarkRunningAsync`, `MarkDoneAsync`, `MarkFailedAsync`), `GetNextQueuedAgentTaskAsync` (queue polling), `GetEffectiveTagsAsync` (union of task + list tags), `FlipAllRunningToFailedAsync`, `UpdateAgentSettingsAsync` (model / system-prompt / agent-path overrides)
+- **TaskRepository** — CRUD, planning helpers (`CreateChildAsync`, `SetPlanningStartedAsync`, `DiscardPlanningAsync`, `TryCompleteParentAsync`, `UpdateChildAsync`), tag management (`GetEffectiveTagsAsync` — union of task + list tags), `UpdateAgentSettingsAsync` (model / system-prompt / agent-path overrides). Status-mutation primitives `MarkRunningAsync` / `MarkDoneAsync` / `MarkFailedAsync` / `FlipAllRunningToFailedAsync` are `internal` and called only by `TaskStateService` in the worker. `CreateChildAsync` produces children with `Status=Idle, PlanningPhase=None`; once their parent's `PlanningPhase` becomes `Finalized`, the chain coordinator queues them.
 - **ListRepository** — CRUD, tag junction management, `GetConfigAsync` / `SetConfigAsync` (upsert) / `DeleteConfigAsync` for `list_config`
 - **TagRepository** — `GetOrCreateAsync` (idempotent)
 - **WorktreeRepository** — CRUD, `UpdateHeadAsync`, `SetStateAsync`
@@ -35,7 +35,7 @@ All repositories use EF Core LINQ queries via `ClaudeDoDbContext`. Exception: `T
 
 ## Schema
 
-Tables: `lists`, `tasks`, `tags`, `list_tags`, `task_tags`, `worktrees`, `list_config`, `task_runs`, `subtasks`, `app_settings`. Managed by EF Core migrations in the `Migrations/` folder. Seed data: tags "agent" and "manual".
+Tables: `lists`, `tasks`, `tags`, `list_tags`, `task_tags`, `worktrees`, `list_config`, `task_runs`, `subtasks`, `app_settings`. Managed by EF Core migrations in the `Migrations/` folder. Seed data: tags "agent" and "manual". The `tasks` table holds `status`, `planning_phase` (default `none`), and `blocked_by_task_id` (FK to `tasks.id`, `ON DELETE SET NULL`).
 
 ## Conventions
 

src/ClaudeDo.Data/Configuration/TaskEntityConfiguration.cs

@@ -17,12 +17,6 @@ public class TaskEntityConfiguration : IEntityTypeConfiguration<TaskEntity>
             TaskStatus.Done      => "done",
             TaskStatus.Failed    => "failed",
             TaskStatus.Cancelled => "cancelled",
-            // Legacy values — kept for compat until slice 6 retires them.
-            TaskStatus.Manual    => "manual",
-            TaskStatus.Planning  => "planning",
-            TaskStatus.Planned   => "planned",
-            TaskStatus.Draft     => "draft",
-            TaskStatus.Waiting   => "waiting",
             _ => throw new ArgumentOutOfRangeException(nameof(v)),
         };
 
@@ -35,12 +29,6 @@ public class TaskEntityConfiguration : IEntityTypeConfiguration<TaskEntity>
             "done"      => TaskStatus.Done,
             "failed"    => TaskStatus.Failed,
             "cancelled" => TaskStatus.Cancelled,
-            // Legacy values — kept for compat until slice 6 retires them.
-            "manual"    => TaskStatus.Manual,
-            "planning"  => TaskStatus.Planning,
-            "planned"   => TaskStatus.Planned,
-            "draft"     => TaskStatus.Draft,
-            "waiting"   => TaskStatus.Waiting,
             _ => throw new ArgumentOutOfRangeException(nameof(v)),
         };
 

src/ClaudeDo.Data/Migrations/20260427130058_RetireLegacyTaskStatus.cs

@@ -0,0 +1,51 @@
+using Microsoft.EntityFrameworkCore.Migrations;
+
+#nullable disable
+
+namespace ClaudeDo.Data.Migrations
+{
+    /// <inheritdoc />
+    public partial class RetireLegacyTaskStatus : Migration
+    {
+        /// <inheritdoc />
+        protected override void Up(MigrationBuilder migrationBuilder)
+        {
+            // manual / draft -> idle
+            migrationBuilder.Sql("UPDATE tasks SET status = 'idle' WHERE status IN ('manual', 'draft');");
+
+            // planning -> idle + planning_phase=active
+            migrationBuilder.Sql("UPDATE tasks SET status = 'idle', planning_phase = 'active' WHERE status = 'planning';");
+
+            // planned -> idle + planning_phase=finalized
+            migrationBuilder.Sql("UPDATE tasks SET status = 'idle', planning_phase = 'finalized' WHERE status = 'planned';");
+
+            // waiting -> queued + blocked_by_task_id derived from sort_order chain.
+            // SQLite 3.25+ supports window functions (LAG).
+            migrationBuilder.Sql(@"
+WITH ordered AS (
+  SELECT id,
+         LAG(id) OVER (PARTITION BY parent_task_id ORDER BY sort_order, created_at) AS prev_id
+  FROM tasks
+  WHERE status = 'waiting'
+)
+UPDATE tasks
+SET status = 'queued',
+    blocked_by_task_id = (SELECT prev_id FROM ordered WHERE ordered.id = tasks.id)
+WHERE id IN (SELECT id FROM ordered);");
+        }
+
+        /// <inheritdoc />
+        protected override void Down(MigrationBuilder migrationBuilder)
+        {
+            // Best-effort and lossy: cancelled is folded back into failed,
+            // (idle, finalized) -> planned, (idle, active) -> planning,
+            // queued + blocked_by_task_id != null -> waiting.
+            // Manual/Draft distinction is unrecoverable — anything previously
+            // 'manual' or 'draft' stays 'idle' on the way back.
+            migrationBuilder.Sql("UPDATE tasks SET status = 'failed' WHERE status = 'cancelled';");
+            migrationBuilder.Sql("UPDATE tasks SET status = 'planned' WHERE status = 'idle' AND planning_phase = 'finalized';");
+            migrationBuilder.Sql("UPDATE tasks SET status = 'planning' WHERE status = 'idle' AND planning_phase = 'active';");
+            migrationBuilder.Sql("UPDATE tasks SET status = 'waiting', blocked_by_task_id = NULL WHERE status = 'queued' AND blocked_by_task_id IS NOT NULL;");
+        }
+    }
+}

src/ClaudeDo.Data/Models/TaskEntity.cs

@@ -2,22 +2,12 @@ namespace ClaudeDo.Data.Models;
 
 public enum TaskStatus
 {
-    // Lifecycle (canonical values).
     Idle,
     Queued,
     Running,
     Done,
     Failed,
     Cancelled,
-
-    // Legacy values — kept for backwards compatibility while the worker
-    // layer is migrated to (Status, PlanningPhase, BlockedByTaskId).
-    // Removed in slice 6 of the worker-state-and-queue-consolidation refactor.
-    Manual,
-    Planning,
-    Planned,
-    Draft,
-    Waiting,
 }
 
 public enum PlanningPhase
@@ -33,7 +23,7 @@ public sealed class TaskEntity
     public required string ListId { get; init; }
     public required string Title { get; set; }
     public string? Description { get; set; }
-    public TaskStatus Status { get; set; } = TaskStatus.Manual;
+    public TaskStatus Status { get; set; } = TaskStatus.Idle;
     public PlanningPhase PlanningPhase { get; set; } = PlanningPhase.None;
     public string? BlockedByTaskId { get; set; }
     public DateTime? ScheduledFor { get; set; }

src/ClaudeDo.Data/Repositories/TaskRepository.cs

@@ -141,7 +141,7 @@ public sealed class TaskRepository
         await _context.Tasks
             .Where(t => t.Id == taskId)
             .ExecuteUpdateAsync(s => s
-                .SetProperty(t => t.Status, TaskStatus.Manual)
+                .SetProperty(t => t.Status, TaskStatus.Idle)
                 .SetProperty(t => t.StartedAt, (DateTime?)null)
                 .SetProperty(t => t.FinishedAt, (DateTime?)null)
                 .SetProperty(t => t.Result, (string?)null), ct);
@@ -270,7 +270,7 @@ public sealed class TaskRepository
             ListId = parent.ListId,
             Title = title,
             Description = description,
-            Status = TaskStatus.Draft,
+            Status = TaskStatus.Idle,
             CreatedAt = DateTime.UtcNow,
             CommitType = string.IsNullOrEmpty(commitType) ? parent.CommitType : commitType,
             ParentTaskId = parentId,
@@ -355,9 +355,10 @@ public sealed class TaskRepository
         CancellationToken ct = default)
     {
         var affected = await _context.Tasks
-            .Where(t => t.Id == taskId && t.Status == TaskStatus.Manual)
+            .Where(t => t.Id == taskId
+                        && t.Status == TaskStatus.Idle
+                        && t.PlanningPhase == PlanningPhase.None)
             .ExecuteUpdateAsync(s => s
-                .SetProperty(t => t.Status, TaskStatus.Planning)
                 .SetProperty(t => t.PlanningPhase, PlanningPhase.Active)
                 .SetProperty(t => t.PlanningSessionToken, sessionToken), ct);
 
@@ -406,20 +407,23 @@ public sealed class TaskRepository
         var parent = await _context.Tasks
             .AsNoTracking()
             .FirstOrDefaultAsync(t => t.Id == parentId, ct);
-        if (parent is null || parent.Status != TaskStatus.Planning)
+        if (parent is null || parent.PlanningPhase != PlanningPhase.Active)
         {
             await tx.RollbackAsync(ct);
             return false;
         }
 
+        // Children created during the planning session are Status=Idle, PlanningPhase=None.
         await _context.Tasks
-            .Where(t => t.ParentTaskId == parentId && t.Status == TaskStatus.Draft)
+            .Where(t => t.ParentTaskId == parentId
+                        && t.Status == TaskStatus.Idle
+                        && t.PlanningPhase == PlanningPhase.None)
             .ExecuteDeleteAsync(ct);
 
         await _context.Tasks
             .Where(t => t.Id == parentId)
             .ExecuteUpdateAsync(s => s
-                .SetProperty(t => t.Status, TaskStatus.Manual)
+                .SetProperty(t => t.Status, TaskStatus.Idle)
                 .SetProperty(t => t.PlanningPhase, PlanningPhase.None)
                 .SetProperty(t => t.PlanningSessionId, (string?)null)
                 .SetProperty(t => t.PlanningSessionToken, (string?)null)
@@ -434,7 +438,7 @@ public sealed class TaskRepository
         CancellationToken ct = default)
     {
         var parent = await _context.Tasks.AsNoTracking().FirstOrDefaultAsync(t => t.Id == parentId, ct);
-        if (parent is null || parent.Status != TaskStatus.Planned) return;
+        if (parent is null || parent.PlanningPhase != PlanningPhase.Finalized) return;
 
         var children = await _context.Tasks
             .Where(t => t.ParentTaskId == parentId)

src/ClaudeDo.Ui/ViewModels/Islands/DetailsIslandViewModel.cs

@@ -474,8 +474,7 @@ public sealed partial class DetailsIslandViewModel : ViewModelBase
             foreach (var s in subs)
                 Subtasks.Add(new SubtaskRowViewModel { Id = s.Id, Title = s.Title, Done = s.Completed });
 
-            if (entity.Status == ClaudeDo.Data.Models.TaskStatus.Planning ||
-                entity.Status == ClaudeDo.Data.Models.TaskStatus.Planned)
+            if (entity.PlanningPhase != ClaudeDo.Data.Models.PlanningPhase.None)
             {
                 await LoadPlanningChildrenAsync(row.Id, ct);
             }

src/ClaudeDo.Ui/ViewModels/Islands/TaskRowViewModel.cs

@@ -15,6 +15,7 @@ public sealed partial class TaskRowViewModel : ViewModelBase
     [ObservableProperty] private bool _isMyDay;
     [ObservableProperty] private bool _isSelected;
     [ObservableProperty] private TaskStatus _status;
+    [ObservableProperty] private PlanningPhase _planningPhase;
     [ObservableProperty] private string? _branch;
     [ObservableProperty] private string? _diffStat;
     [ObservableProperty] private string? _liveTail;
@@ -37,19 +38,20 @@ public sealed partial class TaskRowViewModel : ViewModelBase
     public int StepsCompleted { get; init; }
 
     public bool IsChild          => !string.IsNullOrEmpty(ParentTaskId);
-    public bool IsPlanningParent => Status == TaskStatus.Planning
-                                  || Status == TaskStatus.Planned
+    public bool IsPlanningParent => PlanningPhase != PlanningPhase.None
                                   || HasPlanningChildren;
-    public bool IsDraft          => Status == TaskStatus.Draft;
+    public bool IsDraft          => IsChild && Status == TaskStatus.Idle;
 
-    public bool CanOpenPlanningSession   => Status == TaskStatus.Manual && !IsChild;
-    public bool CanResumeOrDiscardPlanning => Status == TaskStatus.Planning;
+    public bool CanOpenPlanningSession   => Status == TaskStatus.Idle
+                                          && PlanningPhase == PlanningPhase.None
+                                          && !IsChild;
+    public bool CanResumeOrDiscardPlanning => PlanningPhase == PlanningPhase.Active;
 
-    public string? PlanningBadge => Status switch
+    public string? PlanningBadge => PlanningPhase switch
     {
-        TaskStatus.Planning => "PLANNING",
-        TaskStatus.Planned  => "PLANNED",
-        _                   => null,
+        PlanningPhase.Active    => "PLANNING",
+        PlanningPhase.Finalized => "PLANNED",
+        _                       => null,
     };
 
     public bool HasBranch   => !string.IsNullOrWhiteSpace(Branch);
@@ -59,8 +61,7 @@ public sealed partial class TaskRowViewModel : ViewModelBase
     public bool IsOverdue   => ScheduledFor is { } d && d.Date < DateTime.Today && !Done;
     public bool IsRunning   => Status == TaskStatus.Running;
     public bool IsQueued    => Status == TaskStatus.Queued && string.IsNullOrEmpty(BlockedByTaskId);
-    public bool IsWaiting   => (Status == TaskStatus.Queued && !string.IsNullOrEmpty(BlockedByTaskId))
-                            || Status == TaskStatus.Waiting;
+    public bool IsWaiting   => Status == TaskStatus.Queued && !string.IsNullOrEmpty(BlockedByTaskId);
     public bool CanRemoveFromQueue => IsQueued || HasQueuedSubtasks;
     public bool HasSchedule => ScheduledFor.HasValue;
     public bool HasLiveTail => IsRunning && !string.IsNullOrEmpty(LiveTail);
@@ -71,13 +72,12 @@ public sealed partial class TaskRowViewModel : ViewModelBase
 
     public string StatusChipClass => (Status, IsBlocked: !string.IsNullOrEmpty(BlockedByTaskId)) switch
     {
-        (TaskStatus.Running, _)   => "running",
-        (TaskStatus.Failed,  _)   => "error",
-        (TaskStatus.Done,    _)   => "review",
+        (TaskStatus.Running, _)     => "running",
+        (TaskStatus.Failed,  _)     => "error",
+        (TaskStatus.Done,    _)     => "review",
         (TaskStatus.Queued,  true)  => "waiting",
         (TaskStatus.Queued,  false) => "queued",
-        (TaskStatus.Waiting, _)   => "waiting",
-        _                          => "idle",
+        _                           => "idle",
     };
 
     partial void OnStatusChanged(TaskStatus value)
@@ -87,14 +87,19 @@ public sealed partial class TaskRowViewModel : ViewModelBase
         OnPropertyChanged(nameof(IsQueued));
         OnPropertyChanged(nameof(IsWaiting));
         OnPropertyChanged(nameof(HasLiveTail));
-        OnPropertyChanged(nameof(IsPlanningParent));
-        OnPropertyChanged(nameof(PlanningBadge));
         OnPropertyChanged(nameof(IsDraft));
         OnPropertyChanged(nameof(CanOpenPlanningSession));
-        OnPropertyChanged(nameof(CanResumeOrDiscardPlanning));
         OnPropertyChanged(nameof(CanRemoveFromQueue));
     }
 
+    partial void OnPlanningPhaseChanged(PlanningPhase value)
+    {
+        OnPropertyChanged(nameof(IsPlanningParent));
+        OnPropertyChanged(nameof(PlanningBadge));
+        OnPropertyChanged(nameof(CanOpenPlanningSession));
+        OnPropertyChanged(nameof(CanResumeOrDiscardPlanning));
+    }
+
     partial void OnHasQueuedSubtasksChanged(bool value)
         => OnPropertyChanged(nameof(CanRemoveFromQueue));
 
@@ -141,6 +146,7 @@ public sealed partial class TaskRowViewModel : ViewModelBase
         IsStarred         = t.IsStarred;
         IsMyDay           = t.IsMyDay;
         Status            = t.Status;
+        PlanningPhase     = t.PlanningPhase;
         Branch            = t.Worktree?.BranchName;
         DiffStat          = t.Worktree?.DiffStat;
         ScheduledFor      = t.ScheduledFor;

src/ClaudeDo.Ui/ViewModels/Islands/TasksIslandViewModel.cs

@@ -176,7 +176,7 @@ public sealed partial class TasksIslandViewModel : ViewModelBase
 
             ct.ThrowIfCancellationRequested();
 
-            static bool IsPlanningStatus(TaskStatus s) => s == TaskStatus.Planning || s == TaskStatus.Planned;
+            static bool IsPlanningParent(TaskEntity t) => t.PlanningPhase != PlanningPhase.None;
 
             IEnumerable<TaskEntity> filtered = list.Kind switch
             {
@@ -185,10 +185,10 @@ public sealed partial class TasksIslandViewModel : ViewModelBase
                 ListKind.Smart when list.Id == "smart:planned"     => all.Where(t => t.ScheduledFor != null),
                 ListKind.Virtual when list.Id == "virtual:queued"  => all.Where(t =>
                     (t.Status == TaskStatus.Queued && t.ParentTaskId == null) ||
-                    (IsPlanningStatus(t.Status) && all.Any(c => c.ParentTaskId == t.Id && (c.Status == TaskStatus.Queued || c.Status == TaskStatus.Waiting)))),
+                    (IsPlanningParent(t) && all.Any(c => c.ParentTaskId == t.Id && c.Status == TaskStatus.Queued))),
                 ListKind.Virtual when list.Id == "virtual:running" => all.Where(t =>
                     (t.Status == TaskStatus.Running && t.ParentTaskId == null) ||
-                    (IsPlanningStatus(t.Status) && all.Any(c => c.ParentTaskId == t.Id && c.Status == TaskStatus.Running))),
+                    (IsPlanningParent(t) && all.Any(c => c.ParentTaskId == t.Id && c.Status == TaskStatus.Running))),
                 ListKind.Virtual when list.Id == "virtual:review"  => all.Where(t => t.Status == TaskStatus.Done && t.Worktree?.State == WorktreeState.Active && t.ParentTaskId == null),
                 ListKind.User  => all.Where(t => $"user:{t.ListId}" == list.Id),
                 _              => Enumerable.Empty<TaskEntity>(),
@@ -437,7 +437,7 @@ public sealed partial class TasksIslandViewModel : ViewModelBase
         var entity = await db.Tasks.FirstOrDefaultAsync(t => t.Id == row.Id);
         if (entity != null)
         {
-            entity.Status = row.Done ? TaskStatus.Done : TaskStatus.Manual;
+            entity.Status = row.Done ? TaskStatus.Done : TaskStatus.Idle;
             row.Status = entity.Status;
             await db.SaveChangesAsync();
         }
@@ -493,18 +493,16 @@ public sealed partial class TasksIslandViewModel : ViewModelBase
         var entity = await db.Tasks.FirstOrDefaultAsync(t => t.Id == row.Id);
         if (entity is null) return;
 
-        // For a planning parent the dequeue button targets queued/waiting children,
-        // not the parent itself (whose Status is Planning/Planned).
-        if (entity.Status == TaskStatus.Planning || entity.Status == TaskStatus.Planned
-            || entity.PlanningPhase != PlanningPhase.None)
+        // For a planning parent the dequeue button targets queued children
+        // (chain-blocked or not), not the parent itself.
+        if (entity.PlanningPhase != PlanningPhase.None)
         {
             var children = await db.Tasks
-                .Where(t => t.ParentTaskId == row.Id
-                         && (t.Status == TaskStatus.Queued || t.Status == TaskStatus.Waiting))
+                .Where(t => t.ParentTaskId == row.Id && t.Status == TaskStatus.Queued)
                 .ToListAsync();
             foreach (var c in children)
             {
-                c.Status = TaskStatus.Manual;
+                c.Status = TaskStatus.Idle;
                 c.BlockedByTaskId = null;
             }
             await db.SaveChangesAsync();
@@ -513,7 +511,7 @@ public sealed partial class TasksIslandViewModel : ViewModelBase
                 var childRow = Items.FirstOrDefault(r => r.Id == c.Id);
                 if (childRow is not null)
                 {
-                    childRow.Status = TaskStatus.Manual;
+                    childRow.Status = TaskStatus.Idle;
                     childRow.BlockedByTaskId = null;
                 }
             }
@@ -521,9 +519,9 @@ public sealed partial class TasksIslandViewModel : ViewModelBase
         }
         else
         {
-            entity.Status = TaskStatus.Manual;
+            entity.Status = TaskStatus.Idle;
             await db.SaveChangesAsync();
-            row.Status = TaskStatus.Manual;
+            row.Status = TaskStatus.Idle;
         }
         Regroup();
         UpdateSubtitle();
@@ -565,7 +563,8 @@ public sealed partial class TasksIslandViewModel : ViewModelBase
     [RelayCommand]
     private async Task OpenPlanningSessionAsync(TaskRowViewModel? row)
     {
-        if (row is null || row.Status != TaskStatus.Manual) return;
+        if (row is null) return;
+        if (row.Status != TaskStatus.Idle || row.PlanningPhase != PlanningPhase.None) return;
         ForegroundHelper.AllowAny();
         try { await _worker!.StartPlanningSessionAsync(row.Id); }
         catch { }

src/ClaudeDo.Worker/CLAUDE.md

@@ -2,15 +2,60 @@
 
 ASP.NET Core hosted service that executes tasks via Claude CLI in isolated environments.
 
+## Folder Layout
+
+```
+Worker/
+  State/        — TaskStateService + TransitionResult (sole owner of Status/PlanningPhase/BlockedBy writes)
+  Queue/        — IQueueWaker, IQueuePicker, QueueService (BackgroundService), OverrideSlotService
+  Lifecycle/    — StaleTaskRecovery, TaskResetService, TaskMergeService
+  Worktrees/    — WorktreeMaintenanceService
+  Agents/       — AgentFileService, DefaultAgentSeeder
+  Runner/       — TaskRunner + Claude CLI integration
+  Planning/     — PlanningSessionManager, PlanningChainCoordinator, PlanningMcpService
+  External/     — ExternalMcpService
+  Hub/          — WorkerHub, HubBroadcaster
+```
+
 ## Architecture
 
 - **Program.cs** — loads config, inits schema, registers DI, configures SignalR on `/hub`, binds to `127.0.0.1:47821`
-- **QueueService** — `BackgroundService` with two execution slots:
-  - Queue slot: FIFO sequential processing of "agent"-tagged queued tasks
-  - Override slot: immediate execution via `RunNow(taskId)`
-  - Wake signaling via `SemaphoreSlim`, backstop timer (30s default)
-- **StaleTaskRecovery** — startup-only service, flips orphaned "running" tasks to "failed"
-- **External/ExternalMcpService** — always-on MCP tools for general Claude sessions: `ListTaskLists`, `ListTasks`, `GetTask`, `AddTask` (with tags), `UpdateTask`, `UpdateTaskStatus`, `SetTaskTags`, `ListTags`, `DeleteTask`, `RunTaskNow`, `CancelTask`. Auth via optional `X-ClaudeDo-Key` header.
+- **TaskStateService** — only component that writes `Status`, `PlanningPhase`, `BlockedByTaskId`. All transitions return a `TransitionResult` (no exceptions on invalid moves). Wakes the queue and broadcasts `TaskUpdated` automatically; advances the planning chain on child terminal transitions.
+- **IQueueWaker / IQueuePicker / QueueService** — waker is a singleton `SemaphoreSlim`; picker performs the atomic `Queued → Running` claim filtered by `BlockedByTaskId IS NULL`, schedule, and the `agent` tag; QueueService is a thin `BackgroundService` that loops on the waker and dispatches via `TaskRunner`.
+- **OverrideSlotService** — owns `RunNow` / `ContinueTask`; goes through `TaskStateService.StartRunningAsync` (caller-driven, serialized by slot lock).
+- **StaleTaskRecovery** — startup-only service; calls `TaskStateService.RecoverStaleRunningAsync` to flip orphaned `Running` rows to `Failed`.
+- **External/ExternalMcpService** — always-on MCP tools for general Claude sessions: `ListTaskLists`, `ListTasks`, `GetTask`, `AddTask` (with tags), `UpdateTask`, `UpdateTaskStatus` (`Idle` / `Queued`), `SetTaskTags`, `ListTags`, `DeleteTask`, `RunTaskNow`, `CancelTask`. Auth via optional `X-ClaudeDo-Key` header.
+
+## Status Model
+
+`TaskEntity` carries three orthogonal fields. Lifecycle, planning hierarchy, and chain blocking are no longer conflated.
+
+| Field | Values | Meaning |
+|---|---|---|
+| `Status` | `Idle`, `Queued`, `Running`, `Done`, `Failed`, `Cancelled` | Lifecycle only. |
+| `PlanningPhase` | `None`, `Active`, `Finalized` | Parent-only marker. `Active` ≈ legacy `Planning`; `Finalized` ≈ legacy `Planned`. |
+| `BlockedByTaskId` | nullable FK | Replaces legacy `Waiting`. A queued row with `BlockedByTaskId != NULL` is skipped by the picker. |
+
+Allowed transitions (enforced by `TaskStateService`):
+
+```
+Idle      → Queued | Running (RunNow)
+Queued    → Running | Cancelled | Idle
+Running   → Done | Failed | Cancelled
+Done      → Idle (re-run)
+Failed    → Idle | Queued
+Cancelled → Idle | Queued
+```
+
+## Planning Flow
+
+`PlanningSessionManager.FinalizeAsync` is the single path:
+
+1. `_state.FinalizePlanningAsync(parent)` flips parent `PlanningPhase` to `Finalized`.
+2. `PlanningChainCoordinator.SetupChainAsync` attaches the `agent` tag to every child, enqueues child[0], and `BlockOn`s child[i] → child[i-1].
+3. The first child is woken automatically; successors unblock as their predecessor reaches a terminal state via `OnChildFinishedAsync`.
+
+`TaskRepository.FinalizePlanningAsync` no longer exists. The `Mark*Async` repository helpers are `internal` — only `TaskStateService` calls them.
 
 ## Task Execution Pipeline
 
@@ -28,7 +73,7 @@ ASP.NET Core hosted service that executes tasks via Claude CLI in isolated envir
 - **ClaudeProcess** — spawns `claude -p --output-format stream-json --verbose --permission-mode auto` (or whatever permission mode the app settings specify). Writes prompt to stdin, reads NDJSON from stdout. Supports CancellationToken (kills process tree).
 - **ClaudeArgsBuilder** — dynamically constructs CLI args; supports `--model`, `--append-system-prompt`, `--agents`, `--json-schema`, `--resume`
 - **StreamAnalyzer** — parses rich NDJSON output; extracts session_id, token counts, turn counts, result text, structured output. Replaces MessageParser.
-- **TaskResetService** — discards a failed task's worktree and resets the task row to Manual; preserves run history.
+- **TaskResetService** — discards a failed task's worktree and resets the task row to Idle; preserves run history.
 - **WorktreeManager** — creates worktrees at `claudedo/{taskId[:8]}` branches, commits changes with semantic messages, updates DB with head commit and diff stats
 - **CommitMessageBuilder** — formats `{commitType}(slug): title\n\ndescription\n\nClaudeDo-Task: taskId`
 - **AgentFileService** — manages `~/.todo-app/agents/*.md` agent definition files; exposes list/refresh via SignalR

src/ClaudeDo.Worker/External/ExternalMcpService.cs

@@ -117,7 +117,7 @@ public sealed class ExternalMcpService
             ListId = listId,
             Title = title,
             Description = description,
-            Status = TaskStatus.Manual,
+            Status = TaskStatus.Idle,
             CreatedAt = DateTime.UtcNow,
             CommitType = list.DefaultCommitType,
             CreatedBy = createdBy,
@@ -167,7 +167,7 @@ public sealed class ExternalMcpService
         return ToDto(reload);
     }
 
-    [McpServerTool, Description("Update a task's status. Only 'Manual' and 'Queued' are permitted — use RunTaskNow or CancelTask for execution control.")]
+    [McpServerTool, Description("Update a task's status. Only 'Idle' and 'Queued' are permitted — use RunTaskNow or CancelTask for execution control.")]
     public async Task<TaskDto> UpdateTaskStatus(
         string taskId,
         string status,
@@ -181,7 +181,7 @@ public sealed class ExternalMcpService
 
         switch (target)
         {
-            case TaskStatus.Manual:
+            case TaskStatus.Idle:
                 await _tasks.ResetToManualAsync(taskId, cancellationToken);
                 await _broadcaster.TaskUpdated(taskId);
                 break;

src/ClaudeDo.Worker/Planning/PlanningChainCoordinator.cs

@@ -39,16 +39,10 @@ public sealed class PlanningChainCoordinator
         if (children.Count == 0)
             throw new InvalidOperationException("Parent has no subtasks.");
 
-        // Eligibility: new layout uses Status=Idle. Tolerate legacy Manual/Planned/Draft
-        // values during this slice — they will be migrated away in slice 6.
-        var bad = children.FirstOrDefault(c =>
-            c.Status != TaskStatus.Idle &&
-            c.Status != TaskStatus.Manual &&
-            c.Status != TaskStatus.Planned &&
-            c.Status != TaskStatus.Draft);
+        var bad = children.FirstOrDefault(c => c.Status != TaskStatus.Idle);
         if (bad is not null)
             throw new InvalidOperationException(
-                $"Child {bad.Id} is in status {bad.Status}; expected Idle (or legacy Manual/Planned/Draft).");
+                $"Child {bad.Id} is in status {bad.Status}; expected Idle.");
 
         // Worker queue picker requires the "agent" tag — attach it so children are pickable.
         var agentTag = await ctx.Tags.FirstOrDefaultAsync(t => t.Name == "agent", ct);

src/ClaudeDo.Worker/Planning/PlanningMcpService.cs

@@ -49,7 +49,7 @@ public sealed class PlanningMcpService
         var child = await _tasks.CreateChildAsync(ctx.ParentTaskId, title, description, tags, commitType, cancellationToken);
         await BroadcastTaskUpdatedAsync(child.Id, cancellationToken);
         await BroadcastTaskUpdatedAsync(ctx.ParentTaskId, cancellationToken);
-        return new CreatedChildDto(child.Id, "Draft");
+        return new CreatedChildDto(child.Id, child.Status.ToString());
     }
 
     [McpServerTool, Description("List all child tasks under the current planning session's parent task.")]
@@ -68,9 +68,9 @@ public sealed class PlanningMcpService
     }
 
     private static readonly TaskStatus[] EditableStatuses =
-        { TaskStatus.Draft, TaskStatus.Idle, TaskStatus.Manual, TaskStatus.Queued };
+        { TaskStatus.Idle, TaskStatus.Queued };
 
-    [McpServerTool, Description("Update a child task in the active planning session. Can change title, description, tags (replaces the full set), commit type, and status. Status must be one of: Draft, Idle, Manual, Queued.")]
+    [McpServerTool, Description("Update a child task in the active planning session. Can change title, description, tags (replaces the full set), commit type, and status. Status must be one of: Idle, Queued.")]
     public async Task<ChildTaskDto> UpdateChildTask(
         string taskId,
         string? title,
@@ -97,7 +97,7 @@ public sealed class PlanningMcpService
             if (!Enum.TryParse<TaskStatus>(status, ignoreCase: true, out var parsed))
                 throw new InvalidOperationException($"Unknown status '{status}'.");
             if (!EditableStatuses.Contains(parsed))
-                throw new InvalidOperationException($"Status '{parsed}' cannot be set via MCP. Allowed: Draft, Idle, Manual, Queued.");
+                throw new InvalidOperationException($"Status '{parsed}' cannot be set via MCP. Allowed: Idle, Queued.");
             newStatus = parsed;
         }
 

src/ClaudeDo.Worker/Planning/PlanningSessionManager.cs

@@ -81,8 +81,9 @@ public sealed class PlanningSessionManager
             ?? throw new InvalidOperationException($"Task {taskId} not found.");
         if (task.ParentTaskId is not null)
             throw new InvalidOperationException("Cannot start a planning session on a child task.");
-        if (task.Status != TaskStatus.Manual)
-            throw new InvalidOperationException($"Task is in status {task.Status}; only Manual can start planning.");
+        if (task.Status != TaskStatus.Idle || task.PlanningPhase != PlanningPhase.None)
+            throw new InvalidOperationException(
+                $"Task is in status {task.Status}/{task.PlanningPhase}; only Idle+None can start planning.");
 
         var list = await lists.GetByIdAsync(task.ListId, ct)
             ?? throw new InvalidOperationException($"List {task.ListId} not found.");
@@ -232,7 +233,7 @@ public sealed class PlanningSessionManager
         var (tasks, _, settings, ctx) = CreateRepos();
         await using var __ = ctx;
         var children = await tasks.GetChildrenAsync(taskId, ct);
-        return children.Count(c => c.Status == TaskStatus.Draft);
+        return children.Count(c => c.Status == TaskStatus.Idle);
     }
 
     public async Task DiscardAsync(string taskId, CancellationToken ct)
@@ -261,8 +262,9 @@ public sealed class PlanningSessionManager
 
         var task = await tasks.GetByIdAsync(taskId, ct)
             ?? throw new InvalidOperationException($"Task {taskId} not found.");
-        if (task.Status != TaskStatus.Planning)
-            throw new InvalidOperationException($"Task is in status {task.Status}; resume requires Planning.");
+        if (task.PlanningPhase != PlanningPhase.Active)
+            throw new InvalidOperationException(
+                $"Task planning phase is {task.PlanningPhase}; resume requires Active planning.");
         if (string.IsNullOrEmpty(task.PlanningSessionId))
             throw new InvalidOperationException("No Claude session ID captured yet; cannot resume.");
 

src/ClaudeDo.Worker/Planning/PlanningTokenAuth.cs

@@ -27,7 +27,7 @@ public sealed class PlanningTokenAuthMiddleware
 
         var token = auth.Substring("Bearer ".Length).Trim();
         var parent = await tasks.FindByPlanningTokenAsync(token, ctx.RequestAborted);
-        if (parent is null || parent.Status != ClaudeDo.Data.Models.TaskStatus.Planning)
+        if (parent is null || parent.PlanningPhase != ClaudeDo.Data.Models.PlanningPhase.Active)
         {
             ctx.Response.StatusCode = 401;
             await ctx.Response.WriteAsync("Invalid or expired planning token");

src/ClaudeDo.Worker/State/TaskStateService.cs

@@ -144,10 +144,10 @@ public sealed class TaskStateService : ITaskStateService
     {
         await using var ctx = await _dbFactory.CreateDbContextAsync(ct);
         var affected = await ctx.Tasks
-            .Where(t => t.Id == parentId &&
-                (t.Status == TaskStatus.Manual || t.Status == TaskStatus.Idle))
+            .Where(t => t.Id == parentId
+                        && t.Status == TaskStatus.Idle
+                        && t.PlanningPhase == PlanningPhase.None)
             .ExecuteUpdateAsync(s => s
-                .SetProperty(t => t.Status, TaskStatus.Planning)
                 .SetProperty(t => t.PlanningPhase, PlanningPhase.Active), ct);
 
         if (affected == 0)
@@ -198,13 +198,6 @@ public sealed class TaskStateService : ITaskStateService
         if (affected == 0)
             return new TransitionResult(false, "Task not found.");
 
-        // Bridge to legacy chain layout: a Waiting predecessor-blocked sibling becomes Queued
-        // when its predecessor finishes. New layout (post-Slice 4) stores siblings as
-        // Status=Queued + BlockedByTaskId set, so this is a no-op for them.
-        await ctx.Tasks
-            .Where(t => t.Id == taskId && t.Status == TaskStatus.Waiting)
-            .ExecuteUpdateAsync(s => s.SetProperty(t => t.Status, TaskStatus.Queued), ct);
-
         _waker.Wake();
         await _broadcaster.TaskUpdated(taskId);
         return new TransitionResult(true, null);