prjct-cli 1.22.0 → 1.24.0

package/core/storage/state-storage.ts

@@ -1,1035 +0,0 @@
-/**
- * State Storage
- *
- * Manages current task state via storage/state.json
- * Generates context/now.md for Claude
- *
- * Note: Local .prjct-state.md is generated by sync-service which has access
- * to projectPath. This class only has projectId.
- */
-
-import { generateUUID } from '../schemas'
-import type {
-  CurrentTask,
-  PreviousTask,
-  StateJson,
-  Subtask,
-  SubtaskCompletionData,
-  TaskFeedback,
-  TaskHistoryEntry,
-} from '../schemas/state'
-import { StateJsonSchema, SubtaskCompletionDataSchema } from '../schemas/state'
-import { getTimestamp, toRelative } from '../utils/date-helper'
-import { md } from '../utils/markdown-builder'
-import type { WorkflowCommand } from '../workflow/state-machine'
-import { workflowStateMachine } from '../workflow/state-machine'
-import { archiveStorage } from './archive-storage'
-import { StorageManager } from './storage-manager'
-
-class StateStorage extends StorageManager<StateJson> {
-  constructor() {
-    super('state.json', StateJsonSchema)
-  }
-
-  protected getDefault(): StateJson {
-    return {
-      currentTask: null,
-      previousTask: null,
-      pausedTasks: [],
-      taskHistory: [],
-      lastUpdated: '',
-    }
-  }
-
-  protected getMdFilename(): string {
-    return 'now.md'
-  }
-
-  protected getLayer(): string {
-    return 'core'
-  }
-
-  protected getEventType(action: 'update' | 'create' | 'delete'): string {
-    return `state.${action}d`
-  }
-
-  protected toMarkdown(data: StateJson): string {
-    return md()
-      .h1('NOW')
-      .when(!!data.currentTask, (m) => {
-        const task = data.currentTask!
-        m.bold(task.description)
-          .blank()
-          .raw(`Started: ${toRelative(task.startedAt)}`)
-          .raw(`Session: ${task.sessionId}`)
-          .maybe(task.featureId, (m, id) => m.raw(`Feature: ${id}`))
-
-        // Subtask progress table
-        if (task.subtasks && task.subtasks.length > 0) {
-          m.blank()
-            .h2('Subtasks Progress')
-            .raw(
-              `**Progress**: ${task.subtaskProgress?.completed || 0}/${task.subtaskProgress?.total || 0} (${task.subtaskProgress?.percentage || 0}%)`
-            )
-            .blank()
-            .raw('| # | Domain | Description | Status | Agent |')
-            .raw('|---|--------|-------------|--------|-------|')
-
-          task.subtasks.forEach((subtask, index) => {
-            const statusIcon =
-              subtask.status === 'completed'
-                ? '✅'
-                : subtask.status === 'in_progress'
-                  ? '▶️'
-                  : subtask.status === 'failed'
-                    ? '❌'
-                    : subtask.status === 'skipped'
-                      ? '⏭️'
-                      : subtask.status === 'blocked'
-                        ? '🚫'
-                        : '⏳'
-            const isActive = index === task.currentSubtaskIndex ? ' **← Active**' : ''
-            m.raw(
-              `| ${index + 1} | ${subtask.domain} | ${subtask.description} | ${statusIcon} ${subtask.status}${isActive} | ${subtask.agent} |`
-            )
-          })
-
-          // Current subtask details
-          const currentSubtask = task.subtasks[task.currentSubtaskIndex || 0]
-          if (currentSubtask && currentSubtask.status === 'in_progress') {
-            m.blank()
-              .h3('Current Subtask')
-              .raw(`**#${(task.currentSubtaskIndex || 0) + 1}**: ${currentSubtask.description}`)
-              .raw(`**Agent**: ${currentSubtask.agent}`)
-              .raw(`**Domain**: ${currentSubtask.domain}`)
-
-            // Show dependencies
-            if (currentSubtask.dependsOn.length > 0) {
-              m.raw(`**Depends on**: ${currentSubtask.dependsOn.join(', ')}`)
-            }
-          }
-
-          // Show last completed subtask summary if available
-          const completedSubtasks = task.subtasks.filter(
-            (s) => s.status === 'completed' && s.summary
-          )
-          if (completedSubtasks.length > 0) {
-            const lastCompleted = completedSubtasks[completedSubtasks.length - 1]
-            if (lastCompleted.summary) {
-              m.blank()
-                .h3('Previous Subtask Output')
-                .raw(`**${lastCompleted.summary.title}**`)
-                .raw(lastCompleted.summary.description)
-                .maybe(lastCompleted.summary.outputForNextAgent, (m, output) =>
-                  m.blank().raw(`**Available for next agent**: ${output}`)
-                )
-            }
-          }
-        }
-      })
-      .when(!data.currentTask, (m) => {
-        m.italic('No active task. Use /p:work to start.')
-      })
-      .when((data.pausedTasks?.length || 0) > 0 || !!data.previousTask, (m) => {
-        const paused = data.pausedTasks?.length
-          ? data.pausedTasks
-          : data.previousTask
-            ? [data.previousTask]
-            : []
-        if (paused.length === 0) return
-        m.hr().h2(`Paused (${paused.length})`)
-        paused.forEach((prev, i) => {
-          m.raw(`${i + 1}. **${prev.description}**`).raw(`   Paused: ${toRelative(prev.pausedAt)}`)
-          if (prev.pauseReason) m.raw(`   Reason: ${prev.pauseReason}`)
-        })
-        m.blank().italic('Use /p:resume to continue')
-      })
-      .when((data.taskHistory?.length || 0) > 0, (m) => {
-        const history = this.getTaskHistoryFromState(data)
-        if (history.length === 0) return
-
-        // Filter by current task classification if available
-        const currentTaskType = (data.currentTask as any)?.type
-        const relevantHistory = currentTaskType
-          ? history.filter((h) => h.classification === currentTaskType).slice(0, 3)
-          : history.slice(0, 5)
-
-        if (relevantHistory.length === 0) return
-
-        m.hr().h2(
-          currentTaskType
-            ? `Recent ${currentTaskType} tasks (${relevantHistory.length})`
-            : `Recent tasks (${relevantHistory.length})`
-        )
-        relevantHistory.forEach((entry, i) => {
-          m.raw(`${i + 1}. **${entry.title}** (${entry.classification})`)
-            .raw(
-              `   Completed: ${toRelative(entry.completedAt)} | ${entry.subtaskCount} subtask${entry.subtaskCount > 1 ? 's' : ''}`
-            )
-            .raw(`   Outcome: ${entry.outcome}`)
-          if (entry.linearId) m.raw(`   Linear: ${entry.linearId}`)
-          if (entry.feedback?.patternsDiscovered?.length) {
-            m.raw(`   Patterns: ${entry.feedback.patternsDiscovered.join(', ')}`)
-          }
-          if (entry.feedback?.issuesEncountered?.length) {
-            m.raw(`   Gotchas: ${entry.feedback.issuesEncountered.join(', ')}`)
-          }
-        })
-        m.blank().italic('Task history helps identify patterns and improve decisions')
-      })
-      .blank()
-      .build()
-  }
-
-  // =========== Transition Validation ===========
-
-  /**
-   * Validate a state transition through the state machine.
-   * Throws if the transition is invalid.
-   */
-  private validateTransition(state: StateJson, command: WorkflowCommand): void {
-    const currentState = workflowStateMachine.getCurrentState(state)
-    const result = workflowStateMachine.canTransition(currentState, command)
-    if (!result.valid) {
-      throw new Error(`${result.error}. ${result.suggestion || ''}`.trim())
-    }
-  }
-
-  // =========== Domain Methods ===========
-
-  /**
-   * Get current active task
-   */
-  async getCurrentTask(projectId: string): Promise<CurrentTask | null> {
-    const state = await this.read(projectId)
-    return state.currentTask
-  }
-
-  /**
-   * Start a new task
-   */
-  async startTask(projectId: string, task: Omit<CurrentTask, 'startedAt'>): Promise<CurrentTask> {
-    const state = await this.read(projectId)
-    this.validateTransition(state, 'task')
-
-    const currentTask: CurrentTask = {
-      ...task,
-      startedAt: getTimestamp(),
-    }
-
-    await this.update(projectId, (state) => ({
-      ...state,
-      currentTask,
-      lastUpdated: getTimestamp(),
-    }))
-
-    // Publish incremental event
-    await this.publishEvent(projectId, 'task.started', {
-      taskId: currentTask.id,
-      description: currentTask.description,
-      startedAt: currentTask.startedAt,
-      sessionId: currentTask.sessionId,
-    })
-
-    return currentTask
-  }
-
-  /**
-   * Update fields on the current task (partial update)
-   */
-  async updateCurrentTask(
-    projectId: string,
-    fields: Partial<CurrentTask>
-  ): Promise<CurrentTask | null> {
-    const state = await this.read(projectId)
-    if (!state.currentTask) return null
-
-    const updated: CurrentTask = { ...state.currentTask, ...fields }
-
-    await this.update(projectId, (s) => ({
-      ...s,
-      currentTask: updated,
-      lastUpdated: getTimestamp(),
-    }))
-
-    return updated
-  }
-
-  /**
-   * Complete current task
-   * Creates a TaskHistoryEntry and adds it to taskHistory with FIFO eviction
-   * Optionally accepts structured feedback for the task-to-analysis feedback loop (PRJ-272)
-   */
-  async completeTask(projectId: string, feedback?: TaskFeedback): Promise<CurrentTask | null> {
-    const state = await this.read(projectId)
-    const completedTask = state.currentTask
-
-    if (!completedTask) {
-      return null
-    }
-
-    this.validateTransition(state, 'done')
-
-    const completedAt = getTimestamp()
-
-    // Create task history entry for completed task (with optional feedback)
-    const historyEntry = this.createTaskHistoryEntry(completedTask, completedAt, feedback)
-
-    // Get existing task history with backward compatibility
-    const existingHistory = this.getTaskHistoryFromState(state)
-
-    // Add new entry to beginning, enforce max limit with FIFO eviction
-    const taskHistory = [historyEntry, ...existingHistory].slice(0, this.maxTaskHistory)
-
-    await this.update(projectId, () => ({
-      currentTask: null,
-      previousTask: null,
-      taskHistory,
-      lastUpdated: completedAt,
-    }))
-
-    // Publish incremental event
-    await this.publishEvent(projectId, 'task.completed', {
-      taskId: completedTask.id,
-      description: completedTask.description,
-      startedAt: completedTask.startedAt,
-      completedAt,
-    })
-
-    return completedTask
-  }
-
-  /**
-   * Create a TaskHistoryEntry from a completed task
-   * Optionally includes structured feedback for the feedback loop (PRJ-272)
-   */
-  private createTaskHistoryEntry(
-    task: CurrentTask,
-    completedAt: string,
-    feedback?: TaskFeedback
-  ): TaskHistoryEntry {
-    // Extended task properties (may be present in storage but not in schema)
-    const taskAny = task as any
-
-    // Extract subtask summaries (only completed subtasks with summaries)
-    const subtaskSummaries = (task.subtasks || [])
-      .filter((st) => st.status === 'completed' && st.summary)
-      .map((st) => st.summary!)
-
-    // Calculate outcome description from subtask summaries
-    const outcome =
-      subtaskSummaries.length > 0
-        ? subtaskSummaries.map((s) => s.title).join(', ')
-        : 'Task completed'
-
-    const entry: TaskHistoryEntry = {
-      taskId: task.id,
-      title: taskAny.parentDescription || task.description,
-      classification: taskAny.type || 'improvement',
-      startedAt: task.startedAt,
-      completedAt,
-      subtaskCount: task.subtasks?.length || 0,
-      subtaskSummaries,
-      outcome,
-      branchName: taskAny.branch || 'unknown',
-      linearId: task.linearId,
-      linearUuid: task.linearUuid,
-      prUrl: taskAny.prUrl,
-    }
-
-    // Attach feedback if provided (PRJ-272)
-    if (feedback) {
-      entry.feedback = feedback
-    }
-
-    return entry
-  }
-
-  /** Max number of paused tasks (configurable) */
-  private maxPausedTasks = 5
-
-  /** Max number of task history entries (configurable) */
-  private maxTaskHistory = 20
-
-  /** Staleness threshold in days */
-  private stalenessThresholdDays = 30
-
-  /**
-   * Pause current task — pushes onto pausedTasks[] array
-   */
-  async pauseTask(projectId: string, reason?: string): Promise<PreviousTask | null> {
-    const state = await this.read(projectId)
-
-    if (!state.currentTask) {
-      return null
-    }
-
-    this.validateTransition(state, 'pause')
-
-    const pausedTask: PreviousTask = {
-      id: state.currentTask.id,
-      description: state.currentTask.description,
-      status: 'paused',
-      startedAt: state.currentTask.startedAt,
-      pausedAt: getTimestamp(),
-      pauseReason: reason,
-    }
-
-    // Get existing paused tasks, migrate from previousTask if needed
-    const existingPaused = this.getPausedTasksFromState(state)
-
-    // Enforce max paused limit
-    const pausedTasks = [pausedTask, ...existingPaused].slice(0, this.maxPausedTasks)
-
-    await this.update(projectId, () => ({
-      currentTask: null,
-      previousTask: null, // deprecated, keep null for compat
-      pausedTasks,
-      lastUpdated: getTimestamp(),
-    }))
-
-    // Publish incremental event
-    await this.publishEvent(projectId, 'task.paused', {
-      taskId: pausedTask.id,
-      description: pausedTask.description,
-      pausedAt: pausedTask.pausedAt,
-      reason,
-      pausedCount: pausedTasks.length,
-    })
-
-    return pausedTask
-  }
-
-  /**
-   * Resume most recent paused task (or by ID)
-   */
-  async resumeTask(projectId: string, taskId?: string): Promise<CurrentTask | null> {
-    const state = await this.read(projectId)
-
-    // Migrate from previousTask if pausedTasks is empty
-    const pausedTasks = this.getPausedTasksFromState(state)
-
-    if (pausedTasks.length === 0) {
-      return null
-    }
-
-    this.validateTransition(state, 'resume')
-
-    // Find target task: by ID or most recent (first in array)
-    let targetIndex = 0
-    if (taskId) {
-      targetIndex = pausedTasks.findIndex((t) => t.id === taskId)
-      if (targetIndex === -1) return null
-    }
-
-    const target = pausedTasks[targetIndex]
-    const remaining = pausedTasks.filter((_, i) => i !== targetIndex)
-
-    const currentTask: CurrentTask = {
-      id: target.id,
-      description: target.description,
-      startedAt: getTimestamp(),
-      sessionId: generateUUID(),
-    }
-
-    await this.update(projectId, () => ({
-      currentTask,
-      previousTask: null, // deprecated, keep null
-      pausedTasks: remaining,
-      lastUpdated: getTimestamp(),
-    }))
-
-    // Publish incremental event
-    await this.publishEvent(projectId, 'task.resumed', {
-      taskId: currentTask.id,
-      description: currentTask.description,
-      resumedAt: currentTask.startedAt,
-      remainingPaused: remaining.length,
-    })
-
-    return currentTask
-  }
-
-  /**
-   * Get paused tasks from state, migrating from legacy previousTask if needed
-   */
-  private getPausedTasksFromState(state: StateJson): PreviousTask[] {
-    const paused = state.pausedTasks || []
-
-    // Migrate legacy previousTask into array if present
-    if (state.previousTask && state.previousTask.status === 'paused') {
-      const alreadyInArray = paused.some((t) => t.id === state.previousTask!.id)
-      if (!alreadyInArray) {
-        return [state.previousTask, ...paused]
-      }
-    }
-
-    return paused
-  }
-
-  /**
-   * Get task history from state with backward compatibility
-   * Ensures taskHistory is always an array (never undefined)
-   */
-  private getTaskHistoryFromState(state: StateJson): TaskHistoryEntry[] {
-    return state.taskHistory || []
-  }
-
-  /**
-   * Get stale paused tasks (older than threshold)
-   */
-  async getStalePausedTasks(projectId: string): Promise<PreviousTask[]> {
-    const state = await this.read(projectId)
-    const pausedTasks = this.getPausedTasksFromState(state)
-    const threshold = Date.now() - this.stalenessThresholdDays * 24 * 60 * 60 * 1000
-
-    return pausedTasks.filter((t) => new Date(t.pausedAt).getTime() < threshold)
-  }
-
-  /**
-   * Archive stale paused tasks (PRJ-267).
-   * Persists to archive table before removing from active storage.
-   * Returns archived tasks.
-   */
-  async archiveStalePausedTasks(projectId: string): Promise<PreviousTask[]> {
-    const state = await this.read(projectId)
-    const pausedTasks = this.getPausedTasksFromState(state)
-    const threshold = Date.now() - this.stalenessThresholdDays * 24 * 60 * 60 * 1000
-
-    const stale = pausedTasks.filter((t) => new Date(t.pausedAt).getTime() < threshold)
-    const fresh = pausedTasks.filter((t) => new Date(t.pausedAt).getTime() >= threshold)
-
-    if (stale.length === 0) return []
-
-    // Persist to archive table before removal
-    archiveStorage.archiveMany(
-      projectId,
-      stale.map((task) => ({
-        entityType: 'paused_task' as const,
-        entityId: task.id,
-        entityData: task,
-        summary: task.description,
-        reason: 'staleness',
-      }))
-    )
-
-    await this.update(projectId, (s) => ({
-      ...s,
-      pausedTasks: fresh,
-      previousTask: null,
-      lastUpdated: getTimestamp(),
-    }))
-
-    for (const task of stale) {
-      await this.publishEvent(projectId, 'task.archived', {
-        taskId: task.id,
-        description: task.description,
-        pausedAt: task.pausedAt,
-        reason: 'staleness',
-      })
-    }
-
-    return stale
-  }
-
-  /**
-   * Clear all task state
-   */
-  async clearTask(projectId: string): Promise<void> {
-    await this.update(projectId, () => ({
-      currentTask: null,
-      previousTask: null,
-      pausedTasks: [],
-      lastUpdated: getTimestamp(),
-    }))
-  }
-
-  /**
-   * Check if there's an active or paused task
-   */
-  async hasTask(projectId: string): Promise<boolean> {
-    const state = await this.read(projectId)
-    const paused = this.getPausedTasksFromState(state)
-    return state.currentTask !== null || paused.length > 0
-  }
-
-  /**
-   * Get most recently paused task
-   */
-  async getPausedTask(projectId: string): Promise<PreviousTask | null> {
-    const state = await this.read(projectId)
-    const paused = this.getPausedTasksFromState(state)
-    return paused[0] || null
-  }
-
-  /**
-   * Get all paused tasks
-   */
-  async getAllPausedTasks(projectId: string): Promise<PreviousTask[]> {
-    const state = await this.read(projectId)
-    return this.getPausedTasksFromState(state)
-  }
-
-  /**
-   * Get full task history (completed tasks)
-   */
-  async getTaskHistory(projectId: string): Promise<TaskHistoryEntry[]> {
-    const state = await this.read(projectId)
-    return this.getTaskHistoryFromState(state)
-  }
-
-  /**
-   * Get most recent task from history
-   */
-  async getMostRecentTask(projectId: string): Promise<TaskHistoryEntry | null> {
-    const state = await this.read(projectId)
-    const history = this.getTaskHistoryFromState(state)
-    return history[0] || null
-  }
-
-  /**
-   * Get task history filtered by classification
-   */
-  async getTaskHistoryByType(
-    projectId: string,
-    classification: TaskHistoryEntry['classification']
-  ): Promise<TaskHistoryEntry[]> {
-    const state = await this.read(projectId)
-    const history = this.getTaskHistoryFromState(state)
-    return history.filter((t) => t.classification === classification)
-  }
-
-  /**
-   * Aggregate feedback from all task history entries (PRJ-272)
-   * Used by sync to feed task discoveries back into analysis and agent generation.
-   * Returns consolidated patterns, stack confirmations, issues, and agent accuracy.
-   */
-  async getAggregatedFeedback(projectId: string): Promise<{
-    stackConfirmed: string[]
-    patternsDiscovered: string[]
-    agentAccuracy: Array<{ agent: string; rating: string; note?: string }>
-    issuesEncountered: string[]
-    knownGotchas: string[]
-  }> {
-    const history = await this.getTaskHistory(projectId)
-    const entriesWithFeedback = history.filter((h) => h.feedback)
-
-    const stackConfirmed: string[] = []
-    const patternsDiscovered: string[] = []
-    const agentAccuracy: Array<{ agent: string; rating: string; note?: string }> = []
-    const allIssues: string[] = []
-
-    for (const entry of entriesWithFeedback) {
-      const fb = entry.feedback!
-      if (fb.stackConfirmed) stackConfirmed.push(...fb.stackConfirmed)
-      if (fb.patternsDiscovered) patternsDiscovered.push(...fb.patternsDiscovered)
-      if (fb.agentAccuracy) agentAccuracy.push(...fb.agentAccuracy)
-      if (fb.issuesEncountered) allIssues.push(...fb.issuesEncountered)
-    }
-
-    // Deduplicate patterns and stack confirmations
-    const uniqueStack = [...new Set(stackConfirmed)]
-    const uniquePatterns = [...new Set(patternsDiscovered)]
-
-    // Promote recurring issues (2+) to known gotchas
-    const issueCounts = new Map<string, number>()
-    for (const issue of allIssues) {
-      issueCounts.set(issue, (issueCounts.get(issue) || 0) + 1)
-    }
-    const knownGotchas = [...issueCounts.entries()]
-      .filter(([_, count]) => count >= 2)
-      .map(([issue]) => issue)
-
-    return {
-      stackConfirmed: uniqueStack,
-      patternsDiscovered: uniquePatterns,
-      agentAccuracy,
-      issuesEncountered: [...new Set(allIssues)],
-      knownGotchas,
-    }
-  }
-
-  // =========== Subtask Methods ===========
-
-  /**
-   * Create subtasks when fragmenting a task
-   * Sets first subtask to in_progress
-   */
-  async createSubtasks(
-    projectId: string,
-    subtasks: Omit<Subtask, 'status' | 'startedAt' | 'completedAt' | 'output' | 'summary'>[]
-  ): Promise<void> {
-    const state = await this.read(projectId)
-    if (!state.currentTask) return
-
-    // Convert input to full Subtask objects
-    const fullSubtasks: Subtask[] = subtasks.map((s, index) => ({
-      ...s,
-      status: index === 0 ? 'in_progress' : 'pending',
-      startedAt: index === 0 ? getTimestamp() : undefined,
-      dependsOn: s.dependsOn || [],
-    }))
-
-    await this.update(projectId, (current) => ({
-      ...current,
-      currentTask: {
-        ...current.currentTask!,
-        subtasks: fullSubtasks,
-        currentSubtaskIndex: 0,
-        subtaskProgress: {
-          completed: 0,
-          total: fullSubtasks.length,
-          percentage: 0,
-        },
-      },
-      lastUpdated: getTimestamp(),
-    }))
-
-    // Publish event
-    await this.publishEvent(projectId, 'subtasks.created', {
-      taskId: state.currentTask.id,
-      subtaskCount: fullSubtasks.length,
-      subtasks: fullSubtasks.map((s) => ({
-        id: s.id,
-        description: s.description,
-        domain: s.domain,
-      })),
-    })
-  }
-
-  /**
-   * Complete current subtask and advance to next.
-   * Requires output and summary for mandatory handoff (PRJ-262).
-   * Returns the next subtask (or null if all complete).
-   */
-  async completeSubtask(
-    projectId: string,
-    completionData: SubtaskCompletionData
-  ): Promise<Subtask | null> {
-    // Validate handoff data with Zod before persisting
-    const validation = SubtaskCompletionDataSchema.safeParse(completionData)
-    if (!validation.success) {
-      const errors = validation.error.issues.map((i) => `${i.path.join('.')}: ${i.message}`)
-      throw new Error(`Subtask completion requires handoff data:\n${errors.join('\n')}`)
-    }
-
-    const { output, summary } = validation.data
-
-    const state = await this.read(projectId)
-    if (!state.currentTask?.subtasks) return null
-
-    const currentIndex = state.currentTask.currentSubtaskIndex || 0
-    const current = state.currentTask.subtasks[currentIndex]
-    if (!current) return null
-
-    // Mark current as completed with mandatory handoff
-    const updatedSubtasks = [...state.currentTask.subtasks]
-    updatedSubtasks[currentIndex] = {
-      ...current,
-      status: 'completed',
-      completedAt: getTimestamp(),
-      output,
-      summary,
-    }
-
-    // Calculate new progress
-    const completed = updatedSubtasks.filter((s) => s.status === 'completed').length
-    const total = updatedSubtasks.length
-    const percentage = Math.round((completed / total) * 100)
-
-    // Advance to next subtask if available
-    const nextIndex = currentIndex + 1
-    if (nextIndex < updatedSubtasks.length) {
-      updatedSubtasks[nextIndex] = {
-        ...updatedSubtasks[nextIndex],
-        status: 'in_progress',
-        startedAt: getTimestamp(),
-      }
-    }
-
-    await this.update(projectId, (s) => ({
-      ...s,
-      currentTask: {
-        ...s.currentTask!,
-        subtasks: updatedSubtasks,
-        currentSubtaskIndex: nextIndex < total ? nextIndex : currentIndex,
-        subtaskProgress: { completed, total, percentage },
-      },
-      lastUpdated: getTimestamp(),
-    }))
-
-    // Publish event with handoff data
-    await this.publishEvent(projectId, 'subtask.completed', {
-      taskId: state.currentTask.id,
-      subtaskId: current.id,
-      description: current.description,
-      output,
-      handoff: summary.outputForNextAgent,
-      filesChanged: summary.filesChanged.length,
-      progress: { completed, total, percentage },
-    })
-
-    // Return next subtask or null
-    return nextIndex < total ? updatedSubtasks[nextIndex] : null
-  }
-
-  /**
-   * Get current subtask
-   */
-  async getCurrentSubtask(projectId: string): Promise<Subtask | null> {
-    const state = await this.read(projectId)
-    if (!state.currentTask?.subtasks) return null
-    const index = state.currentTask.currentSubtaskIndex || 0
-    return state.currentTask.subtasks[index] || null
-  }
-
-  /**
-   * Get next subtask (after current)
-   */
-  async getNextSubtask(projectId: string): Promise<Subtask | null> {
-    const state = await this.read(projectId)
-    if (!state.currentTask?.subtasks) return null
-    const nextIndex = (state.currentTask.currentSubtaskIndex || 0) + 1
-    return state.currentTask.subtasks[nextIndex] || null
-  }
-
-  /**
-   * Get previous subtask (before current)
-   */
-  async getPreviousSubtask(projectId: string): Promise<Subtask | null> {
-    const state = await this.read(projectId)
-    if (!state.currentTask?.subtasks) return null
-    const prevIndex = (state.currentTask.currentSubtaskIndex || 0) - 1
-    if (prevIndex < 0) return null
-    return state.currentTask.subtasks[prevIndex] || null
-  }
-
-  /**
-   * Get handoff from the most recently completed subtask (PRJ-262).
-   * Returns the summary.outputForNextAgent and related context,
-   * or null if no previous subtask or no handoff data.
-   */
-  async getPreviousHandoff(projectId: string): Promise<{
-    fromSubtask: string
-    outputForNextAgent: string
-    filesChanged: Array<{ path: string; action: string }>
-    whatWasDone: string[]
-  } | null> {
-    const prev = await this.getPreviousSubtask(projectId)
-    if (!prev?.summary?.outputForNextAgent) return null
-    return {
-      fromSubtask: prev.description,
-      outputForNextAgent: prev.summary.outputForNextAgent,
-      filesChanged: prev.summary.filesChanged,
-      whatWasDone: prev.summary.whatWasDone,
-    }
-  }
-
-  /**
-   * Get all subtasks
-   */
-  async getSubtasks(projectId: string): Promise<Subtask[]> {
-    const state = await this.read(projectId)
-    return state.currentTask?.subtasks || []
-  }
-
-  /**
-   * Get subtask progress
-   */
-  async getSubtaskProgress(
-    projectId: string
-  ): Promise<{ completed: number; total: number; percentage: number } | null> {
-    const state = await this.read(projectId)
-    return state.currentTask?.subtaskProgress || null
-  }
-
-  /**
-   * Check if task has subtasks
-   */
-  async hasSubtasks(projectId: string): Promise<boolean> {
-    const state = await this.read(projectId)
-    return (state.currentTask?.subtasks?.length || 0) > 0
-  }
-
-  /**
-   * Check if all subtasks are complete
-   */
-  async areAllSubtasksComplete(projectId: string): Promise<boolean> {
-    const state = await this.read(projectId)
-    if (!state.currentTask?.subtasks) return true
-    return state.currentTask.subtasks.every(
-      (s) => s.status === 'completed' || s.status === 'failed' || s.status === 'skipped'
-    )
-  }
-
-  /**
-   * Fail current subtask and advance to next
-   * Returns the next subtask (or null if all done/failed)
-   */
-  async failSubtask(projectId: string, error: string): Promise<Subtask | null> {
-    const state = await this.read(projectId)
-    if (!state.currentTask?.subtasks) return null
-
-    const currentIndex = state.currentTask.currentSubtaskIndex || 0
-    const current = state.currentTask.subtasks[currentIndex]
-    if (!current) return null
-
-    const updatedSubtasks = [...state.currentTask.subtasks]
-    updatedSubtasks[currentIndex] = {
-      ...current,
-      status: 'failed',
-      completedAt: getTimestamp(),
-      output: `Failed: ${error}`,
-    }
-
-    // Advance to next subtask if available
-    const nextIndex = currentIndex + 1
-    const total = updatedSubtasks.length
-    if (nextIndex < total) {
-      updatedSubtasks[nextIndex] = {
-        ...updatedSubtasks[nextIndex],
-        status: 'in_progress',
-        startedAt: getTimestamp(),
-      }
-    }
-
-    // Count completed + failed + skipped as "resolved" for progress
-    const resolved = updatedSubtasks.filter(
-      (s) => s.status === 'completed' || s.status === 'failed' || s.status === 'skipped'
-    ).length
-    const percentage = Math.round((resolved / total) * 100)
-
-    await this.update(projectId, (s) => ({
-      ...s,
-      currentTask: {
-        ...s.currentTask!,
-        subtasks: updatedSubtasks,
-        currentSubtaskIndex: nextIndex < total ? nextIndex : currentIndex,
-        subtaskProgress: { completed: resolved, total, percentage },
-      },
-      lastUpdated: getTimestamp(),
-    }))
-
-    // Publish event
-    await this.publishEvent(projectId, 'subtask.failed', {
-      taskId: state.currentTask.id,
-      subtaskId: current.id,
-      description: current.description,
-      error,
-    })
-
-    return nextIndex < total ? updatedSubtasks[nextIndex] : null
-  }
-
-  /**
-   * Skip current subtask with reason and advance to next
-   * Returns the next subtask (or null if all done)
-   */
-  async skipSubtask(projectId: string, reason: string): Promise<Subtask | null> {
-    const state = await this.read(projectId)
-    if (!state.currentTask?.subtasks) return null
-
-    const currentIndex = state.currentTask.currentSubtaskIndex || 0
-    const current = state.currentTask.subtasks[currentIndex]
-    if (!current) return null
-
-    const updatedSubtasks = [...state.currentTask.subtasks]
-    updatedSubtasks[currentIndex] = {
-      ...current,
-      status: 'skipped',
-      completedAt: getTimestamp(),
-      output: `Skipped: ${reason}`,
-      skipReason: reason,
-    }
-
-    // Advance to next subtask if available
-    const nextIndex = currentIndex + 1
-    const total = updatedSubtasks.length
-    if (nextIndex < total) {
-      updatedSubtasks[nextIndex] = {
-        ...updatedSubtasks[nextIndex],
-        status: 'in_progress',
-        startedAt: getTimestamp(),
-      }
-    }
-
-    const resolved = updatedSubtasks.filter(
-      (s) => s.status === 'completed' || s.status === 'failed' || s.status === 'skipped'
-    ).length
-    const percentage = Math.round((resolved / total) * 100)
-
-    await this.update(projectId, (s) => ({
-      ...s,
-      currentTask: {
-        ...s.currentTask!,
-        subtasks: updatedSubtasks,
-        currentSubtaskIndex: nextIndex < total ? nextIndex : currentIndex,
-        subtaskProgress: { completed: resolved, total, percentage },
-      },
-      lastUpdated: getTimestamp(),
-    }))
-
-    await this.publishEvent(projectId, 'subtask.skipped', {
-      taskId: state.currentTask.id,
-      subtaskId: current.id,
-      description: current.description,
-      reason,
-    })
-
-    return nextIndex < total ? updatedSubtasks[nextIndex] : null
-  }
-
-  /**
-   * Block current subtask with reason, allow proceeding to next
-   * Returns the next subtask (or null if no more)
-   */
-  async blockSubtask(projectId: string, blocker: string): Promise<Subtask | null> {
-    const state = await this.read(projectId)
-    if (!state.currentTask?.subtasks) return null
-
-    const currentIndex = state.currentTask.currentSubtaskIndex || 0
-    const current = state.currentTask.subtasks[currentIndex]
-    if (!current) return null
-
-    const updatedSubtasks = [...state.currentTask.subtasks]
-    updatedSubtasks[currentIndex] = {
-      ...current,
-      status: 'blocked',
-      output: `Blocked: ${blocker}`,
-      blockReason: blocker,
-    }
-
-    // Advance to next subtask if available (blocked doesn't halt)
-    const nextIndex = currentIndex + 1
-    const total = updatedSubtasks.length
-    if (nextIndex < total) {
-      updatedSubtasks[nextIndex] = {
-        ...updatedSubtasks[nextIndex],
-        status: 'in_progress',
-        startedAt: getTimestamp(),
-      }
-    }
-
-    await this.update(projectId, (s) => ({
-      ...s,
-      currentTask: {
-        ...s.currentTask!,
-        subtasks: updatedSubtasks,
-        currentSubtaskIndex: nextIndex < total ? nextIndex : currentIndex,
-      },
-      lastUpdated: getTimestamp(),
-    }))
-
-    await this.publishEvent(projectId, 'subtask.blocked', {
-      taskId: state.currentTask.id,
-      subtaskId: current.id,
-      description: current.description,
-      blocker,
-    })
-
-    return nextIndex < total ? updatedSubtasks[nextIndex] : null
-  }
-}
-
-export const stateStorage = new StateStorage()
-export default stateStorage