gsd-lite 0.5.10 → 0.5.13

package/src/tools/orchestrator.js

@@ -1,1243 +0,0 @@
-import { readFile, readdir, stat } from 'node:fs/promises';
-import { join, relative } from 'node:path';
-import {
-  read,
-  storeResearch,
-  update,
-  selectRunnableTask,
-  buildExecutorContext,
-  matchDecisionForBlocker,
-  reclassifyReviewLevel,
-  propagateInvalidation,
-} from './state.js';
-import { validateDebuggerResult, validateExecutorResult, validateResearcherResult, validateReviewerResult } from '../schema.js';
-import { getGitHead, getGsdDir } from '../utils.js';
-
-const MAX_DEBUG_RETRY = 3;
-const MAX_RESUME_DEPTH = 3;
-const CONTEXT_RESUME_THRESHOLD = 40;
-const MAX_DECISIONS = 200;
-
-// ── Result Contracts ──
-// Provided in dispatch responses so agents produce valid results on the first call.
-const RESULT_CONTRACTS = {
-  executor: {
-    task_id: 'string — must match dispatched task_id',
-    outcome: '"checkpointed" | "blocked" | "failed"',
-    summary: 'string — non-empty description of work done',
-    checkpoint_commit: 'string — required when outcome="checkpointed"',
-    files_changed: 'string[] — list of modified file paths',
-    decisions: '{ id, title, rationale }[] — architectural decisions made',
-    blockers: '{ description, type }[] — what blocked progress (when outcome="blocked")',
-    contract_changed: 'boolean — true if external API/behavior contract changed',
-    evidence: '{ type, detail }[] — verification evidence (test results, lint, etc.)',
-  },
-  reviewer: {
-    scope: '"task" | "phase"',
-    scope_id: 'string | number — task id (e.g. "1.2") or phase number',
-    review_level: '"L2" | "L1-batch" | "L1"',
-    spec_passed: 'boolean',
-    quality_passed: 'boolean',
-    critical_issues: '{ reason|description, task_id?, invalidates_downstream? }[] — blocking issues',
-    important_issues: '{ description, task_id? }[]',
-    minor_issues: '{ description, task_id? }[]',
-    accepted_tasks: 'string[] — task ids that passed review',
-    rework_tasks: 'string[] — task ids that need rework (disjoint with accepted_tasks)',
-    evidence: '{ type, detail }[]',
-  },
-  researcher: {
-    result: {
-      decision_ids: 'string[] — ids of decisions addressed',
-      volatility: '"low" | "medium" | "high"',
-      expires_at: 'string — ISO date when research expires',
-      sources: '{ id, type, ref, title?, accessed_at? }[] — research sources',
-    },
-    decision_index: '{ [id]: { id, title, rationale, status, summary } } — keyed by decision id',
-    artifacts: '{ "STACK.md", "ARCHITECTURE.md", "PITFALLS.md", "SUMMARY.md" } — all four required',
-  },
-  debugger: {
-    task_id: 'string — must match debug target',
-    outcome: '"root_cause_found" | "fix_suggested" | "failed"',
-    root_cause: 'string — non-empty root cause description',
-    evidence: '{ type, detail }[]',
-    hypothesis_tested: '{ hypothesis, result: "confirmed"|"rejected", evidence }[]',
-    fix_direction: 'string — recommended fix approach',
-    fix_attempts: 'number — non-negative integer (>=3 requires outcome="failed")',
-    blockers: '{ description, type }[]',
-    architecture_concern: 'boolean',
-  },
-};
-
-function isTerminalWorkflowMode(workflowMode) {
-  return workflowMode === 'completed' || workflowMode === 'failed';
-}
-
-function parseTimestamp(value) {
-  const parsed = Date.parse(value);
-  return Number.isFinite(parsed) ? parsed : null;
-}
-
-async function readContextHealth(basePath) {
-  const gsdDir = await getGsdDir(basePath);
-  if (!gsdDir) return null;
-  try {
-    const raw = await readFile(join(gsdDir, '.context-health'), 'utf-8');
-    const health = Number.parseInt(raw, 10);
-    return Number.isFinite(health) ? health : null;
-  } catch {
-    return null;
-  }
-}
-
-function collectExpiredResearch(state) {
-  const expired = [];
-  const now = Date.now();
-  const researchExpiry = parseTimestamp(state.research?.expires_at);
-  if (researchExpiry !== null && researchExpiry <= now) {
-    expired.push({ id: 'research', expires_at: state.research.expires_at });
-  }
-
-  for (const [id, entry] of Object.entries(state.research?.decision_index || {})) {
-    const expiresAt = parseTimestamp(entry?.expires_at);
-    if (expiresAt !== null && expiresAt <= now) {
-      expired.push({
-        id,
-        summary: entry.summary || null,
-        expires_at: entry.expires_at,
-      });
-    }
-  }
-
-  return expired;
-}
-
-function getDirectionDriftPhase(state) {
-  const currentPhase = state.phases?.find((phase) => phase.id === state.current_phase);
-  if (currentPhase?.phase_handoff?.direction_ok === false && currentPhase.lifecycle !== 'accepted') {
-    return currentPhase;
-  }
-
-  return (state.phases || []).find((phase) => (
-    phase?.phase_handoff?.direction_ok === false && phase.lifecycle !== 'accepted'
-  )) || null;
-}
-
-async function detectPlanDrift(basePath, lastSession) {
-  const lastSessionTs = parseTimestamp(lastSession);
-  if (lastSessionTs === null) return [];
-
-  const gsdDir = await getGsdDir(basePath);
-  if (!gsdDir) return [];
-
-  const candidates = [join(gsdDir, 'plan.md')];
-  try {
-    const phaseFiles = await readdir(join(gsdDir, 'phases'));
-    for (const fileName of phaseFiles) {
-      if (fileName.endsWith('.md')) {
-        candidates.push(join(gsdDir, 'phases', fileName));
-      }
-    }
-  } catch {}
-
-  const changedFiles = [];
-  for (const filePath of candidates) {
-    try {
-      const fileStat = await stat(filePath);
-      if (fileStat.mtimeMs > lastSessionTs) {
-        changedFiles.push(relative(gsdDir, filePath));
-      }
-    } catch {}
-  }
-
-  return changedFiles.sort();
-}
-
-async function evaluatePreflight(state, basePath) {
-  if (isTerminalWorkflowMode(state.workflow_mode)) {
-    return { override: null };
-  }
-
-  const hints = [];
-
-  const currentGitHead = await getGitHead(basePath);
-  if (state.git_head && currentGitHead && state.git_head !== currentGitHead) {
-    hints.push({
-      workflow_mode: 'reconcile_workspace',
-      action: 'await_manual_intervention',
-      updates: { workflow_mode: 'reconcile_workspace' },
-      saved_git_head: state.git_head,
-      current_git_head: currentGitHead,
-      message: 'Saved git_head does not match the current workspace HEAD',
-    });
-  }
-
-  const changed_files = await detectPlanDrift(basePath, state.context?.last_session);
-  if (changed_files.length > 0) {
-    hints.push({
-      workflow_mode: 'replan_required',
-      action: 'await_manual_intervention',
-      updates: { workflow_mode: 'replan_required' },
-      changed_files,
-      message: 'Plan artifacts changed after the last recorded session',
-    });
-  }
-
-  const skipDirectionDrift = state.workflow_mode === 'awaiting_user'
-    && state.current_review?.stage === 'direction_drift';
-  if (!skipDirectionDrift) {
-    const driftPhase = getDirectionDriftPhase(state);
-    if (driftPhase) {
-      hints.push({
-        workflow_mode: 'awaiting_user',
-        action: 'awaiting_user',
-        updates: {
-          workflow_mode: 'awaiting_user',
-          current_task: null,
-          current_review: {
-            scope: 'phase',
-            scope_id: driftPhase.id,
-            stage: 'direction_drift',
-            summary: `Direction drift detected for phase ${driftPhase.id}`,
-          },
-        },
-        drift_phase: { id: driftPhase.id, name: driftPhase.name },
-        message: `Direction drift detected for phase ${driftPhase.id}; user decision required before resuming`,
-      });
-    }
-  }
-
-  const expired_research = collectExpiredResearch(state);
-  if (expired_research.length > 0) {
-    hints.push({
-      workflow_mode: 'research_refresh_needed',
-      action: 'dispatch_researcher',
-      updates: { workflow_mode: 'research_refresh_needed' },
-      expired_research,
-      message: 'Research cache expired and must be refreshed before execution resumes',
-    });
-  }
-
-  // P0-2: Dirty-phase detection — rollback current_phase to earliest phase
-  // that has needs_revalidation tasks, ensuring earlier invalidated work
-  // is re-executed before proceeding with later phases.
-  // Use filter+reduce (not .find) to guarantee lowest-ID match regardless of array order.
-  const dirtyPhases = (state.phases || []).filter(p =>
-    p.id < state.current_phase
-    && (p.todo || []).some(t => t.lifecycle === 'needs_revalidation'),
-  );
-  const earliestDirtyPhase = dirtyPhases.length > 0
-    ? dirtyPhases.reduce((min, p) => (p.id < min.id ? p : min))
-    : null;
-  if (earliestDirtyPhase) {
-    hints.push({
-      workflow_mode: 'executing_task',
-      action: 'rollback_to_dirty_phase',
-      updates: {
-        workflow_mode: 'executing_task',
-        current_phase: earliestDirtyPhase.id,
-        current_task: null,
-        current_review: null,
-      },
-      dirty_phase: { id: earliestDirtyPhase.id, name: earliestDirtyPhase.name },
-      message: `Phase ${earliestDirtyPhase.id} has invalidated tasks; rolling back from phase ${state.current_phase}`,
-    });
-  }
-
-  if (hints.length === 0) return { override: null };
-
-  return {
-    override: hints[0],
-    // Always report all hint messages so caller can surface pending issues
-    hints: hints.map(h => h.message),
-  };
-}
-
-function getCurrentPhase(state) {
-  return state.phases?.find((phase) => phase.id === state.current_phase)
-    || state.phases?.find((phase) => phase.lifecycle === 'active')
-    || null;
-}
-
-function getTaskById(phase, taskId) {
-  return phase?.todo?.find((task) => task.id === taskId) || null;
-}
-
-function getBlockedTasks(phase) {
-  return (phase?.todo || [])
-    .filter((task) => task.lifecycle === 'blocked')
-    .map((task) => ({
-      id: task.id,
-      reason: task.blocked_reason || 'Blocked without reason',
-      unblock_condition: task.unblock_condition || null,
-    }));
-}
-
-function getReviewTargets(phase, reviewScope, scopeId) {
-  if (!phase) return [];
-  if (reviewScope === 'task') {
-    const task = getTaskById(phase, scopeId);
-    return task ? [task] : [];
-  }
-  return (phase.todo || []).filter((task) => task.level !== 'L0' && task.lifecycle === 'checkpointed');
-}
-
-function getPhaseAndTask(state, taskId) {
-  for (const phase of (state.phases || [])) {
-    const task = getTaskById(phase, taskId);
-    if (task) return { phase, task };
-  }
-  return { phase: null, task: null };
-}
-
-function getDebugTarget(phase, task, currentReview) {
-  if (!phase || !task) return null;
-  return {
-    id: task.id,
-    level: task.level || 'L1',
-    retry_count: task.retry_count || 0,
-    error_fingerprint: task.last_error_fingerprint || currentReview?.error_fingerprint || null,
-    last_failure_summary: task.last_failure_summary || currentReview?.summary || null,
-    files_changed: task.files_changed || [],
-    checkpoint_commit: task.checkpoint_commit || null,
-    debug_context: task.debug_context || null,
-  };
-}
-
-function buildDecisionEntries(decisions, phaseId, taskId, existingCount = 0) {
-  return (decisions || [])
-    .map((decision, index) => {
-      if (typeof decision === 'string' && decision.length > 0) {
-        return {
-          id: `decision:${phaseId}:${taskId}:${existingCount + index + 1}`,
-          summary: decision,
-          phase: phaseId,
-          task: taskId,
-        };
-      }
-      if (decision && typeof decision === 'object' && typeof decision.summary === 'string') {
-        return {
-          id: decision.id || `decision:${phaseId}:${taskId}:${existingCount + index + 1}`,
-          phase: decision.phase ?? phaseId,
-          task: decision.task ?? taskId,
-          ...decision,
-        };
-      }
-      return null;
-    })
-    .filter(Boolean);
-}
-
-function buildErrorFingerprint(result) {
-  const parts = [];
-  if (result.blockers?.length > 0) {
-    const b = result.blockers[0];
-    parts.push(typeof b === 'string' ? b : (b.reason || b.type || ''));
-  }
-  if (result.files_changed?.length > 0) {
-    parts.push([...result.files_changed].sort().join(','));
-  }
-  const combined = parts.filter(Boolean).join('|');
-  return combined.length > 0 ? combined.slice(0, 120) : result.summary.slice(0, 80);
-}
-
-function getBlockedReasonFromResult(result) {
-  const firstBlocker = (result.blockers || [])[0];
-  if (!firstBlocker) return { blocked_reason: result.summary, unblock_condition: null };
-  if (typeof firstBlocker === 'string') {
-    return { blocked_reason: firstBlocker, unblock_condition: null };
-  }
-  return {
-    blocked_reason: firstBlocker.reason || result.summary,
-    unblock_condition: firstBlocker.unblock_condition || null,
-  };
-}
-
-async function persist(basePath, updates) {
-  const result = await update({ updates, basePath });
-  if (result.error) {
-    return result;
-  }
-  return null;
-}
-
-async function resumeAwaitingClear(state, basePath) {
-  const health = await readContextHealth(basePath);
-  if (health !== null && health < CONTEXT_RESUME_THRESHOLD) {
-    const persistError = await persist(basePath, {
-      workflow_mode: 'awaiting_clear',
-      context: {
-        ...state.context,
-        remaining_percentage: health,
-      },
-    });
-    if (persistError) return persistError;
-
-    return {
-      success: true,
-      action: 'await_manual_intervention',
-      workflow_mode: 'awaiting_clear',
-      remaining_percentage: health,
-      message: 'Context health is still below the resume threshold; run /clear and retry /gsd:resume',
-    };
-  }
-
-  const updates = { workflow_mode: 'executing_task' };
-  if (health !== null) {
-    updates.context = {
-      ...state.context,
-      remaining_percentage: health,
-    };
-  }
-  const persistError = await persist(basePath, updates);
-  if (persistError) return persistError;
-  return resumeWorkflow({ basePath });
-}
-
-function buildExecutorDispatch(state, phase, task, extras = {}) {
-  const context = buildExecutorContext(state, task.id, phase.id);
-  if (context.error) return context;
-  return {
-    success: true,
-    action: 'dispatch_executor',
-    workflow_mode: 'executing_task',
-    phase_id: phase.id,
-    task_id: task.id,
-    executor_context: context,
-    result_contract: RESULT_CONTRACTS.executor,
-    ...extras,
-  };
-}
-
-async function tryAutoUnblock(state, phase, basePath) {
-  const blockedTasks = (phase?.todo || []).filter((task) => task.lifecycle === 'blocked');
-  const decisions = state.decisions || [];
-  if (blockedTasks.length === 0 || decisions.length === 0) {
-    return { autoUnblocked: [], blockers: getBlockedTasks(phase) };
-  }
-
-  const patches = [];
-  const autoUnblocked = [];
-
-  for (const task of blockedTasks) {
-    const matchedDecision = matchDecisionForBlocker(decisions, task.blocked_reason);
-    if (!matchedDecision) continue;
-    patches.push({
-      id: task.id,
-      lifecycle: 'pending',
-      blocked_reason: null,
-      unblock_condition: null,
-    });
-    autoUnblocked.push({
-      task_id: task.id,
-      decision_id: matchedDecision.id,
-      decision_summary: matchedDecision.summary,
-    });
-  }
-
-  if (patches.length === 0) {
-    return { autoUnblocked: [], blockers: getBlockedTasks(phase) };
-  }
-
-  const persistError = await persist(basePath, {
-    phases: [{ id: phase.id, todo: patches }],
-  });
-  if (persistError) return persistError;
-
-  const refreshed = await read({ basePath });
-  if (refreshed.error) return refreshed;
-  const refreshedPhase = getCurrentPhase(refreshed);
-  return {
-    autoUnblocked,
-    blockers: getBlockedTasks(refreshedPhase),
-  };
-}
-
-async function resumeExecutingTask(state, basePath) {
-  const phase = getCurrentPhase(state);
-  if (!phase) {
-    return { error: true, message: `Current phase ${state.current_phase} not found` };
-  }
-
-  if (state.current_review?.stage === 'debugging') {
-    const debugTaskId = state.current_review.scope_id || state.current_task;
-    const task = getTaskById(phase, debugTaskId);
-    if (!task) {
-      return { error: true, message: `Debug target task ${debugTaskId} not found in current phase` };
-    }
-    return {
-      success: true,
-      action: 'dispatch_debugger',
-      workflow_mode: 'executing_task',
-      phase_id: phase.id,
-      current_review: state.current_review,
-      debug_target: getDebugTarget(phase, task, state.current_review),
-      result_contract: RESULT_CONTRACTS.debugger,
-    };
-  }
-
-  if (state.current_task) {
-    const currentTask = getTaskById(phase, state.current_task);
-    if (currentTask?.lifecycle === 'running') {
-      const isRetrying = (currentTask.retry_count || 0) > 0;
-      const persistError = await persist(basePath, {
-        workflow_mode: 'executing_task',
-        current_task: currentTask.id,
-        current_review: null,
-      });
-      if (persistError) return persistError;
-      return buildExecutorDispatch(state, phase, currentTask, {
-        resumed: true,
-        interruption_recovered: !isRetrying,
-        ...(isRetrying ? {
-          retry_after_failure: true,
-          retry_count: currentTask.retry_count,
-          last_failure_summary: currentTask.last_failure_summary,
-        } : {}),
-      });
-    }
-  }
-
-  const selection = selectRunnableTask(phase, state);
-  if (selection.error) return selection;
-
-  if (selection.task) {
-    const task = selection.task;
-    // Compound transition: auto-reset to pending for states that require it
-    // needs_revalidation/blocked/failed all transition through pending before running
-    if (['needs_revalidation', 'blocked', 'failed'].includes(task.lifecycle)) {
-      const resetError = await persist(basePath, {
-        phases: [{ id: phase.id, todo: [{ id: task.id, lifecycle: 'pending' }] }],
-      });
-      if (resetError) return resetError;
-    }
-    const persistError = await persist(basePath, {
-      workflow_mode: 'executing_task',
-      current_task: task.id,
-      current_review: null,
-      phases: [{
-        id: phase.id,
-        todo: [{ id: task.id, lifecycle: 'running' }],
-      }],
-    });
-    if (persistError) return persistError;
-    return buildExecutorDispatch(state, phase, task);
-  }
-
-  if (selection.mode === 'trigger_review') {
-    const current_review = { scope: 'phase', scope_id: phase.id };
-    const updates = {
-      workflow_mode: 'reviewing_phase',
-      current_task: null,
-      current_review,
-    };
-    // Auto-advance phase lifecycle to 'reviewing' if currently 'active'
-    if (phase.lifecycle === 'active') {
-      updates.phases = [{ id: phase.id, lifecycle: 'reviewing' }];
-    }
-    const persistError = await persist(basePath, updates);
-    if (persistError) return persistError;
-
-    return {
-      success: true,
-      action: 'trigger_review',
-      workflow_mode: 'reviewing_phase',
-      phase_id: phase.id,
-      current_review,
-    };
-  }
-
-  if (selection.mode === 'awaiting_user') {
-    const phaseBlockers = getBlockedTasks(phase);
-    const blockers = phaseBlockers.length > 0
-      ? phaseBlockers
-      : (selection.blockers || []);
-    const persistError = await persist(basePath, {
-      workflow_mode: 'awaiting_user',
-      current_task: null,
-      current_review: null,
-    });
-    if (persistError) return persistError;
-
-    return {
-      success: true,
-      action: 'awaiting_user',
-      workflow_mode: 'awaiting_user',
-      phase_id: phase.id,
-      blockers,
-    };
-  }
-
-  // P0-1: Auto phase completion — when all tasks accepted and review passed,
-  // signal complete_phase instead of going idle
-  const allAccepted = phase.todo.length > 0 && phase.todo.every(t => t.lifecycle === 'accepted');
-  const reviewPassed = phase.phase_review?.status === 'accepted'
-    || phase.phase_handoff?.required_reviews_passed === true;
-  if (allAccepted && reviewPassed) {
-    // Auto-advance phase lifecycle to 'reviewing' if currently 'active'
-    // (mirrors trigger_review path at line 480-482)
-    if (phase.lifecycle === 'active') {
-      const advanceError = await persist(basePath, {
-        phases: [{ id: phase.id, lifecycle: 'reviewing' }],
-      });
-      if (advanceError) return advanceError;
-    }
-    return {
-      success: true,
-      action: 'complete_phase',
-      workflow_mode: 'executing_task',
-      phase_id: phase.id,
-      message: 'All tasks accepted and review passed; phase ready for completion',
-    };
-  }
-
-  const persistError = await persist(basePath, {
-    current_task: null,
-    current_review: null,
-  });
-  if (persistError) return persistError;
-
-  return {
-    success: true,
-    action: 'idle',
-    workflow_mode: 'executing_task',
-    phase_id: phase.id,
-    message: 'No runnable task found in current phase',
-  };
-}
-
-export async function resumeWorkflow({ basePath = process.cwd(), _depth = 0, unblock_tasks } = {}) {
-  if (_depth >= MAX_RESUME_DEPTH) {
-    return { error: true, message: `resumeWorkflow recursive depth limit exceeded (max ${MAX_RESUME_DEPTH})` };
-  }
-
-  const state = await read({ basePath });
-  if (state.error) {
-    return state;
-  }
-
-  // Force-unblock specified tasks before normal resume flow
-  if (Array.isArray(unblock_tasks) && unblock_tasks.length > 0 && _depth === 0) {
-    const phase = getCurrentPhase(state);
-    if (phase) {
-      const patches = [];
-      for (const taskId of unblock_tasks) {
-        const task = (phase.todo || []).find(t => t.id === taskId);
-        if (task?.lifecycle === 'blocked') {
-          patches.push({ id: taskId, lifecycle: 'pending', blocked_reason: null, unblock_condition: null });
-        }
-      }
-      if (patches.length > 0) {
-        const persistError = await persist(basePath, {
-          workflow_mode: 'executing_task',
-          current_task: null,
-          current_review: null,
-          phases: [{ id: phase.id, todo: patches }],
-        });
-        if (persistError) return persistError;
-        // Re-read state after unblock and continue
-        return resumeWorkflow({ basePath, _depth: _depth + 1 });
-      }
-    }
-  }
-
-  const preflight = await evaluatePreflight(state, basePath);
-  if (preflight.override) {
-    const persistError = await persist(basePath, preflight.override.updates);
-    if (persistError) return persistError;
-
-    return {
-      success: true,
-      action: preflight.override.action,
-      workflow_mode: preflight.override.workflow_mode,
-      message: preflight.override.message,
-      ...(preflight.override.drift_phase ? { drift_phase: preflight.override.drift_phase } : {}),
-      ...(preflight.override.saved_git_head ? { saved_git_head: preflight.override.saved_git_head } : {}),
-      ...(preflight.override.current_git_head ? { current_git_head: preflight.override.current_git_head } : {}),
-      ...(preflight.override.changed_files ? { changed_files: preflight.override.changed_files } : {}),
-      ...(preflight.override.expired_research ? { expired_research: preflight.override.expired_research } : {}),
-      ...(preflight.override.dirty_phase ? { dirty_phase: preflight.override.dirty_phase } : {}),
-      ...(preflight.hints && preflight.hints.length > 1 ? { pending_issues: preflight.hints.slice(1) } : {}),
-    };
-  }
-
-  switch (state.workflow_mode) {
-    case 'executing_task':
-      return resumeExecutingTask(state, basePath);
-    case 'awaiting_clear':
-      return resumeAwaitingClear(state, basePath);
-    case 'awaiting_user': {
-      if (state.current_review?.stage === 'direction_drift') {
-        const driftPhaseId = state.current_review.scope_id || state.current_phase;
-        const driftPhase = state.phases?.find((phase) => phase.id === driftPhaseId) || null;
-        return {
-          success: true,
-          action: 'awaiting_user',
-          workflow_mode: 'awaiting_user',
-          phase_id: driftPhaseId,
-          drift_phase: driftPhase ? { id: driftPhase.id, name: driftPhase.name } : { id: driftPhaseId, name: null },
-          auto_unblocked: [],
-          blockers: [],
-          current_review: state.current_review,
-          message: 'Direction drift detected; user decision is required before execution can continue',
-        };
-      }
-
-      const phase = getCurrentPhase(state);
-      const autoUnblock = await tryAutoUnblock(state, phase, basePath);
-      if (autoUnblock.error) return autoUnblock;
-
-      if (autoUnblock.blockers.length === 0) {
-        const persistError = await persist(basePath, {
-          workflow_mode: 'executing_task',
-          current_task: null,
-          current_review: null,
-        });
-        if (persistError) return persistError;
-        const resumed = await resumeWorkflow({ basePath, _depth: _depth + 1 });
-        if (resumed.error) return resumed;
-        return { ...resumed, auto_unblocked: autoUnblock.autoUnblocked };
-      }
-
-      return {
-        success: true,
-        action: 'awaiting_user',
-        workflow_mode: 'awaiting_user',
-        phase_id: state.current_phase,
-        auto_unblocked: autoUnblock.autoUnblocked,
-        blockers: autoUnblock.blockers,
-        message: autoUnblock.blockers.length > 0
-          ? 'Blocked tasks still require user input'
-          : 'No blocked tasks remain',
-      };
-    }
-    case 'reviewing_phase': {
-      const phase = getCurrentPhase(state);
-      const current_review = state.current_review || { scope: 'phase', scope_id: state.current_phase };
-      const persistError = state.current_review ? null : await persist(basePath, { current_review });
-      if (persistError) return persistError;
-
-      return {
-        success: true,
-        action: 'dispatch_reviewer',
-        workflow_mode: 'reviewing_phase',
-        review_scope: 'phase',
-        phase_id: phase?.id || state.current_phase,
-        current_review,
-        review_targets: getReviewTargets(phase, 'phase', current_review.scope_id).map((task) => ({
-          id: task.id,
-          level: task.level,
-          checkpoint_commit: task.checkpoint_commit || null,
-          files_changed: task.files_changed || [],
-        })),
-        result_contract: RESULT_CONTRACTS.reviewer,
-      };
-    }
-    case 'reviewing_task': {
-      const phase = getCurrentPhase(state);
-      const current_review = state.current_review || (state.current_task
-        ? { scope: 'task', scope_id: state.current_task, stage: 'spec' }
-        : null);
-      if (!current_review?.scope_id) {
-        return { error: true, message: 'reviewing_task mode requires current_review.scope_id or current_task' };
-      }
-      const persistError = state.current_review ? null : await persist(basePath, { current_review });
-      if (persistError) return persistError;
-
-      const [task] = getReviewTargets(phase, 'task', current_review.scope_id);
-      return {
-        success: true,
-        action: 'dispatch_reviewer',
-        workflow_mode: 'reviewing_task',
-        review_scope: 'task',
-        phase_id: phase?.id || state.current_phase,
-        current_review,
-        review_target: task ? {
-          id: task.id,
-          level: task.level,
-          checkpoint_commit: task.checkpoint_commit || null,
-          files_changed: task.files_changed || [],
-        } : null,
-        result_contract: RESULT_CONTRACTS.reviewer,
-      };
-    }
-    case 'completed':
-      return {
-        success: true,
-        action: 'noop',
-        workflow_mode: state.workflow_mode,
-        completed_phases: (state.phases || []).filter((phase) => phase.lifecycle === 'accepted').length,
-        total_phases: state.total_phases,
-        message: 'Workflow already completed',
-      };
-    case 'failed': {
-      const failedPhases = [];
-      const failedTasks = [];
-      for (const phase of state.phases || []) {
-        if (phase.lifecycle === 'failed') failedPhases.push({ id: phase.id, name: phase.name });
-        for (const t of phase.todo || []) {
-          if (t.lifecycle === 'failed') {
-            failedTasks.push({
-              id: t.id,
-              name: t.name,
-              phase_id: phase.id,
-              retry_count: t.retry_count || 0,
-              last_failure_summary: t.last_failure_summary || null,
-              debug_context: t.debug_context || null,
-            });
-          }
-        }
-      }
-      return {
-        success: true,
-        action: 'await_recovery_decision',
-        workflow_mode: state.workflow_mode,
-        failed_phases: failedPhases,
-        failed_tasks: failedTasks,
-        recovery_options: ['retry_failed', 'skip_failed', 'replan'],
-        message: 'Workflow is in failed state. Recovery options available.',
-      };
-    }
-    case 'paused_by_user':
-      return {
-        success: true,
-        action: 'await_manual_intervention',
-        workflow_mode: state.workflow_mode,
-        resume_to: state.current_review?.scope === 'phase'
-          ? 'reviewing_phase'
-          : state.current_review?.scope === 'task'
-            ? 'reviewing_task'
-            : 'executing_task',
-        current_review: state.current_review || null,
-        current_task: state.current_task || null,
-        message: 'Project is paused. Confirm to resume execution.',
-      };
-    case 'planning':
-      return {
-        success: true,
-        action: 'await_manual_intervention',
-        workflow_mode: state.workflow_mode,
-        guidance: 'Complete planning and call state-init to initialize the project',
-        message: 'Project is in planning mode; complete the plan and initialize with state-init',
-      };
-    case 'reconcile_workspace': {
-      const reconGitHead = await getGitHead(basePath);
-      return {
-        success: true,
-        action: 'reconcile_workspace',
-        workflow_mode: state.workflow_mode,
-        expected_head: state.git_head,
-        actual_head: reconGitHead,
-        guidance: 'Workspace git HEAD has diverged. Verify changes and update git_head via state-update, then set workflow_mode to executing_task',
-        message: `Git HEAD mismatch: saved=${state.git_head}, current=${reconGitHead}`,
-      };
-    }
-    case 'replan_required':
-      return {
-        success: true,
-        action: 'replan_required',
-        workflow_mode: state.workflow_mode,
-        guidance: 'Plan files modified since last session. Review changes, update the plan if needed, then set workflow_mode to executing_task via state-update',
-        message: 'Plan artifacts modified since last session; review and re-align before resuming',
-      };
-    case 'research_refresh_needed': {
-      const expiredResearch = collectExpiredResearch(state);
-      return {
-        success: true,
-        action: 'dispatch_researcher',
-        workflow_mode: state.workflow_mode,
-        expired_research: expiredResearch,
-        guidance: 'Research cache expired. Dispatch researcher sub-agent to refresh, then call orchestrator-handle-researcher-result',
-        message: 'Research has expired and must be refreshed before execution can resume',
-      };
-    }
-    default:
-      return {
-        error: true,
-        message: `workflow_mode "${state.workflow_mode}" is not yet supported by the orchestrator skeleton`,
-      };
-  }
-}
-
-export async function handleExecutorResult({ result, basePath = process.cwd() } = {}) {
-  if (!result || typeof result !== 'object' || Array.isArray(result)) {
-    return { error: true, message: 'result must be an object' };
-  }
-  const validation = validateExecutorResult(result);
-  if (!validation.valid) {
-    return { error: true, message: `Invalid executor result: ${validation.errors.join('; ')}` };
-  }
-
-  const state = await read({ basePath });
-  if (state.error) return state;
-  const { phase, task } = getPhaseAndTask(state, result.task_id);
-  if (!phase || !task) {
-    return { error: true, message: `Task ${result.task_id} not found` };
-  }
-
-  const decisionEntries = buildDecisionEntries(result.decisions, phase.id, task.id, (state.decisions || []).length);
-  const allDecisions = [...(state.decisions || []), ...decisionEntries];
-  // H-1: Cap decisions to prevent unbounded growth
-  const decisions = allDecisions.length > MAX_DECISIONS ? allDecisions.slice(-MAX_DECISIONS) : allDecisions;
-
-  if (result.outcome === 'checkpointed') {
-    const reviewLevel = reclassifyReviewLevel(task, result);
-    const isL0 = reviewLevel === 'L0';
-    const autoAccept = isL0 || task.review_required === false;
-
-    const current_review = !isL0 && (reviewLevel === 'L2' || reviewLevel === 'L3') && task.review_required !== false
-      ? { scope: 'task', scope_id: task.id, stage: 'spec' }
-      : null;
-    const workflow_mode = current_review ? 'reviewing_task' : 'executing_task';
-
-    // Single atomic persist: auto-accept goes directly running → accepted,
-    // otherwise running → checkpointed (awaiting review)
-    const taskPatch = {
-      id: task.id,
-      lifecycle: autoAccept ? 'accepted' : 'checkpointed',
-      checkpoint_commit: result.checkpoint_commit,
-      files_changed: result.files_changed || [],
-      evidence_refs: result.evidence || [],
-      level: reviewLevel,
-      blocked_reason: null,
-      unblock_condition: null,
-      debug_context: null,
-    };
-    const phasePatch = { id: phase.id, todo: [taskPatch] };
-    // done is auto-recomputed by update() — no manual increment needed
-
-    // Bundle evidence into the same atomic persist to prevent inconsistency
-    const evidenceUpdates = {};
-    for (const ev of (result.evidence || [])) {
-      if (ev && typeof ev === 'object' && typeof ev.id === 'string' && typeof ev.scope === 'string') {
-        evidenceUpdates[ev.id] = ev;
-      }
-    }
-
-    const persistError = await persist(basePath, {
-      workflow_mode,
-      current_task: null,
-      current_review,
-      decisions,
-      phases: [phasePatch],
-      ...(Object.keys(evidenceUpdates).length > 0 ? { evidence: evidenceUpdates } : {}),
-    });
-    if (persistError) return persistError;
-
-    return {
-      success: true,
-      action: current_review ? 'dispatch_reviewer' : 'continue_execution',
-      workflow_mode,
-      task_id: task.id,
-      review_level: reviewLevel,
-      current_review,
-      auto_accepted: autoAccept,
-      ...(current_review ? { result_contract: RESULT_CONTRACTS.reviewer } : {}),
-    };
-  }
-
-  if (result.outcome === 'blocked') {
-    const { blocked_reason, unblock_condition } = getBlockedReasonFromResult(result);
-    const persistError = await persist(basePath, {
-      workflow_mode: 'awaiting_user',
-      current_task: null,
-      current_review: null,
-      decisions,
-      phases: [{
-        id: phase.id,
-        todo: [{
-          id: task.id,
-          lifecycle: 'blocked',
-          blocked_reason,
-          unblock_condition,
-          evidence_refs: result.evidence || [],
-        }],
-      }],
-    });
-    if (persistError) return persistError;
-
-    return {
-      success: true,
-      action: 'awaiting_user',
-      workflow_mode: 'awaiting_user',
-      task_id: task.id,
-      blockers: getBlockedTasks({ todo: [{ id: task.id, lifecycle: 'blocked', blocked_reason, unblock_condition }] }),
-    };
-  }
-
-  // Task stays in 'running' lifecycle intentionally — executor outcome 'failed' means
-  // "attempt failed, ready for retry or debugger", NOT lifecycle 'failed'. The task only
-  // transitions to lifecycle 'failed' via handleDebuggerResult when debugging is exhausted.
-  const retry_count = (task.retry_count || 0) + 1;
-  const error_fingerprint = typeof result.error_fingerprint === 'string' && result.error_fingerprint.length > 0
-    ? result.error_fingerprint
-    : buildErrorFingerprint(result);
-  const shouldDebug = retry_count >= MAX_DEBUG_RETRY;
-  const current_review = shouldDebug
-    ? {
-        scope: 'task',
-        scope_id: task.id,
-        stage: 'debugging',
-        retry_count,
-        error_fingerprint,
-        summary: result.summary,
-      }
-    : null;
-
-  const persistError = await persist(basePath, {
-    workflow_mode: 'executing_task',
-    current_task: task.id,
-    current_review,
-    decisions,
-    phases: [{
-      id: phase.id,
-      todo: [{
-        id: task.id,
-        retry_count,
-        last_error_fingerprint: error_fingerprint,
-        last_failure_summary: result.summary,
-        last_failure_blockers: result.blockers || [],
-        evidence_refs: result.evidence || [],
-      }],
-    }],
-  });
-  if (persistError) return persistError;
-
-  return {
-    success: true,
-    action: shouldDebug ? 'dispatch_debugger' : 'retry_executor',
-    workflow_mode: 'executing_task',
-    task_id: task.id,
-    retry_count,
-    current_review,
-    result_contract: shouldDebug ? RESULT_CONTRACTS.debugger : RESULT_CONTRACTS.executor,
-  };
-}
-
-export async function handleDebuggerResult({ result, basePath = process.cwd() } = {}) {
-  if (!result || typeof result !== 'object' || Array.isArray(result)) {
-    return { error: true, message: 'result must be an object' };
-  }
-  const validation = validateDebuggerResult(result);
-  if (!validation.valid) {
-    return { error: true, message: `Invalid debugger result: ${validation.errors.join('; ')}` };
-  }
-
-  const state = await read({ basePath });
-  if (state.error) return state;
-  const { phase, task } = getPhaseAndTask(state, result.task_id);
-  if (!phase || !task) {
-    return { error: true, message: `Task ${result.task_id} not found` };
-  }
-
-  const debug_context = {
-    root_cause: result.root_cause,
-    fix_direction: result.fix_direction,
-    evidence: result.evidence,
-    hypothesis_tested: result.hypothesis_tested,
-    fix_attempts: result.fix_attempts,
-    blockers: result.blockers,
-    architecture_concern: result.architecture_concern,
-  };
-
-  if (result.outcome === 'failed' || result.architecture_concern === true) {
-    const phaseFailed = result.architecture_concern === true;
-
-    // Determine effective workflow mode: if no tasks can make progress, escalate
-    let effectiveWorkflowMode;
-    if (phaseFailed) {
-      effectiveWorkflowMode = 'failed';
-    } else {
-      const hasProgressable = (phase.todo || []).some(t =>
-        t.id !== task.id && !['accepted', 'failed'].includes(t.lifecycle),
-      );
-      effectiveWorkflowMode = hasProgressable ? 'executing_task' : 'awaiting_user';
-    }
-
-    const phasePatch = { id: phase.id };
-    if (phaseFailed) {
-      phasePatch.lifecycle = 'failed';
-    }
-    phasePatch.todo = [{ id: task.id, lifecycle: 'failed', debug_context }];
-
-    const persistError = await persist(basePath, {
-      workflow_mode: effectiveWorkflowMode,
-      current_task: null,
-      current_review: null,
-      phases: [phasePatch],
-    });
-    if (persistError) return persistError;
-
-    return {
-      success: true,
-      action: phaseFailed ? 'phase_failed' : 'task_failed',
-      workflow_mode: effectiveWorkflowMode,
-      phase_id: phase.id,
-      task_id: task.id,
-    };
-  }
-
-  const persistError = await persist(basePath, {
-    workflow_mode: 'executing_task',
-    current_task: task.id,
-    current_review: null,
-    phases: [{
-      id: phase.id,
-      todo: [{
-        id: task.id,
-        debug_context,
-      }],
-    }],
-  });
-  if (persistError) return persistError;
-
-  const refreshed = await read({ basePath });
-  if (refreshed.error) return refreshed;
-  const refreshedInfo = getPhaseAndTask(refreshed, task.id);
-  return buildExecutorDispatch(refreshed, refreshedInfo.phase, refreshedInfo.task, {
-    resumed_from_debugger: true,
-    debugger_guidance: refreshedInfo.task.debug_context,
-  });
-}
-
-export async function handleReviewerResult({ result, basePath = process.cwd() } = {}) {
-  if (!result || typeof result !== 'object' || Array.isArray(result)) {
-    return { error: true, message: 'result must be an object' };
-  }
-  const validation = validateReviewerResult(result);
-  if (!validation.valid) {
-    return { error: true, message: `Invalid reviewer result: ${validation.errors.join('; ')}` };
-  }
-
-  const state = await read({ basePath });
-  if (state.error) return state;
-
-  const phase = result.scope === 'phase'
-    ? (state.phases || []).find((p) => p.id === Number(result.scope_id)) || null
-    : getCurrentPhase(state);
-  if (!phase) {
-    return { error: true, message: `Phase not found for scope_id ${result.scope_id}` };
-  }
-
-  const taskPatches = [];
-
-  // Accept tasks
-  for (const taskId of (result.accepted_tasks || [])) {
-    const task = getTaskById(phase, taskId);
-    if (!task) continue;
-    if (task.lifecycle === 'checkpointed') {
-      taskPatches.push({ id: taskId, lifecycle: 'accepted' });
-    }
-  }
-
-  // Rework tasks — persist reviewer feedback so executor knows what to fix
-  for (const taskId of (result.rework_tasks || [])) {
-    const task = getTaskById(phase, taskId);
-    if (!task) continue;
-    if (task.lifecycle === 'checkpointed' || task.lifecycle === 'accepted') {
-      const taskIssues = [
-        ...(result.critical_issues || []).filter(i => !i.task_id || i.task_id === taskId),
-        ...(result.important_issues || []).filter(i => !i.task_id || i.task_id === taskId),
-      ].map(i => i.reason ?? i.description ?? '');
-      taskPatches.push({
-        id: taskId,
-        lifecycle: 'needs_revalidation',
-        retry_count: 0,
-        evidence_refs: [],
-        last_review_feedback: taskIssues.length > 0 ? taskIssues : null,
-      });
-    }
-  }
-
-  // Propagation for critical issues with invalidates_downstream
-  for (const issue of (result.critical_issues || [])) {
-    if (issue.invalidates_downstream && issue.task_id) {
-      propagateInvalidation(phase, issue.task_id, true);
-    }
-  }
-
-  // Collect propagation-affected task patches (tasks mutated in-memory by propagateInvalidation)
-  for (const task of (phase.todo || [])) {
-    if (task.lifecycle === 'needs_revalidation' && !taskPatches.some((p) => p.id === task.id)) {
-      taskPatches.push({ id: task.id, lifecycle: 'needs_revalidation', retry_count: 0, evidence_refs: [] });
-    }
-  }
-
-  const hasCritical = (result.critical_issues || []).length > 0;
-  const reviewStatus = hasCritical ? 'rework_required' : 'accepted';
-
-  // done is auto-recomputed by update() — no manual tracking needed
-  const phaseUpdates = {
-    id: phase.id,
-    phase_review: {
-      status: reviewStatus,
-      ...(hasCritical
-        ? { retry_count: (phase.phase_review?.retry_count || 0) + 1 }
-        : { retry_count: 0 }),
-    },
-    todo: taskPatches,
-  };
-
-  // Transition phase back to active when rework is needed
-  if (hasCritical && phase.lifecycle === 'reviewing') {
-    phaseUpdates.lifecycle = 'active';
-  }
-
-  if (!hasCritical && result.scope === 'phase') {
-    phaseUpdates.phase_handoff = { required_reviews_passed: true };
-  }
-
-  const workflowMode = 'executing_task';
-
-  // Bundle evidence into the same atomic persist
-  const evidenceUpdates = {};
-  for (const ev of (result.evidence || [])) {
-    if (ev && typeof ev === 'object' && typeof ev.id === 'string' && typeof ev.scope === 'string') {
-      evidenceUpdates[ev.id] = ev;
-    }
-  }
-
-  const persistError = await persist(basePath, {
-    workflow_mode: workflowMode,
-    current_review: null,
-    phases: [phaseUpdates],
-    ...(Object.keys(evidenceUpdates).length > 0 ? { evidence: evidenceUpdates } : {}),
-  });
-  if (persistError) return persistError;
-
-  return {
-    success: true,
-    action: hasCritical ? 'rework_required' : 'review_accepted',
-    workflow_mode: workflowMode,
-    phase_id: phase.id,
-    review_status: reviewStatus,
-    accepted_count: result.accepted_tasks?.length || 0,
-    rework_count: result.rework_tasks?.length || 0,
-    critical_count: result.critical_issues?.length || 0,
-  };
-}
-
-export async function handleResearcherResult({ result, artifacts, decision_index, basePath = process.cwd() } = {}) {
-  if (!result || typeof result !== 'object' || Array.isArray(result)) {
-    return { error: true, message: 'result must be an object' };
-  }
-
-  const validation = validateResearcherResult(result);
-  if (!validation.valid) {
-    return { error: true, message: `Invalid researcher result: ${validation.errors.join('; ')}` };
-  }
-
-  const persisted = await storeResearch({ result, artifacts, decision_index, basePath });
-  if (persisted.error) return persisted;
-
-  const resumed = await resumeWorkflow({ basePath });
-  if (resumed.error) return resumed;
-
-  return {
-    ...resumed,
-    stored_files: persisted.stored_files,
-    decision_ids: persisted.decision_ids,
-    research_warnings: persisted.warnings,
-  };
-}
-
-export { getBlockedTasks, getCurrentPhase, getReviewTargets };