gsd-lite 0.5.10 → 0.5.13

package/src/tools/{state.js → state/crud.js}

@@ -1,82 +1,26 @@
-// State CRUD tools
+// State CRUD operations
 
-import { join, dirname } from 'node:path';
-import { stat, writeFile, rename, unlink } from 'node:fs/promises';
-import { ensureDir, readJson, writeJson, writeAtomic, getStatePath, getGitHead, isPlainObject, clearGsdDirCache, withFileLock } from '../utils.js';
+import { dirname, join } from 'node:path';
+import { stat } from 'node:fs/promises';
+import { ensureDir, readJson, writeJson, writeAtomic, getStatePath, getGitHead, isPlainObject, clearGsdDirCache } from '../../utils.js';
 import {
   CANONICAL_FIELDS,
-  TASK_LIFECYCLE,
-  validateResearchArtifacts,
-  validateResearchDecisionIndex,
-  validateResearcherResult,
+  TASK_LEVELS,
   validateState,
   validateStateUpdate,
   validateTransition,
   createInitialState,
   migrateState,
-} from '../schema.js';
-import { runAll } from './verify.js';
-
-const RESEARCH_FILES = ['STACK.md', 'ARCHITECTURE.md', 'PITFALLS.md', 'SUMMARY.md'];
-const MAX_EVIDENCE_ENTRIES = 200;
-const MAX_ARCHIVE_ENTRIES = 1000;
-
-// M-10: Structured error codes
-export const ERROR_CODES = {
-  NO_PROJECT_DIR: 'NO_PROJECT_DIR',
-  INVALID_INPUT: 'INVALID_INPUT',
-  VALIDATION_FAILED: 'VALIDATION_FAILED',
-  STATE_EXISTS: 'STATE_EXISTS',
-  NOT_FOUND: 'NOT_FOUND',
-  TERMINAL_STATE: 'TERMINAL_STATE',
-  TRANSITION_ERROR: 'TRANSITION_ERROR',
-  HANDOFF_GATE: 'HANDOFF_GATE',
-};
-
-// C-1: Serialize all state mutations to prevent TOCTOU races
-// C-2: Layer cross-process advisory file lock on top of in-process queue
-let _mutationQueue = Promise.resolve();
-let _fileLockPath = null;
-
-export function setLockPath(lockPath) {
-  _fileLockPath = lockPath;
-}
-
-/**
- * Ensure _fileLockPath is set from a known state path.
- * Must be called before withStateLock in all mutation paths.
- */
-function ensureLockPathFromStatePath(statePath) {
-  if (!_fileLockPath && statePath) {
-    _fileLockPath = join(dirname(statePath), 'state.lock');
-  }
-}
-
-function withStateLock(fn) {
-  const p = _mutationQueue.then(() => {
-    if (_fileLockPath) {
-      return withFileLock(_fileLockPath, fn);
-    }
-    return fn();
-  });
-  _mutationQueue = p.catch(() => {});
-  return p;
-}
-
-function inferWorkflowModeAfterResearch(state) {
-  if (state.current_review?.scope === 'phase') return 'reviewing_phase';
-  if (state.current_review?.scope === 'task') return 'reviewing_task';
-  return 'executing_task';
-}
-
-function normalizeResearchArtifacts(artifacts) {
-  const normalized = {};
-  for (const fileName of RESEARCH_FILES) {
-    const content = artifacts[fileName];
-    normalized[fileName] = content.endsWith('\n') ? content : `${content}\n`;
-  }
-  return normalized;
-}
+} from '../../schema.js';
+import { runAll } from '../verify.js';
+import {
+  ERROR_CODES,
+  MAX_EVIDENCE_ENTRIES,
+  MAX_ARCHIVE_ENTRIES,
+  ensureLockPathFromStatePath,
+  withStateLock,
+} from './constants.js';
+import { propagateInvalidation } from './logic.js';
 
 /**
  * Initialize a new GSD project: creates .gsd/, state.json, plan.md, phases/
@@ -202,7 +146,7 @@ export async function read({ fields, basePath = process.cwd(), validate = false
 /**
  * Update state.json with canonical field guard and full validation.
  */
-export async function update({ updates, basePath = process.cwd() } = {}) {
+export async function update({ updates, basePath = process.cwd(), _append_decisions, _propagation_tasks } = {}) {
   if (!updates || typeof updates !== 'object' || Array.isArray(updates)) {
     return { error: true, code: ERROR_CODES.INVALID_INPUT, message: 'updates must be a non-null object' };
   }
@@ -229,7 +173,7 @@ export async function update({ updates, basePath = process.cwd() } = {}) {
     if (!result.ok) {
       return { error: true, code: ERROR_CODES.NO_PROJECT_DIR, message: result.error };
     }
-    const state = result.data;
+    const state = migrateState(result.data);
 
     // Guard: reject workflow_mode changes FROM terminal states
     if (updates.workflow_mode) {
@@ -308,8 +252,29 @@ export async function update({ updates, basePath = process.cwd() } = {}) {
       }
     }
 
+    // Atomic decisions append: accumulate inside the lock against fresh state
+    if (Array.isArray(_append_decisions) && _append_decisions.length > 0) {
+      const existing = Array.isArray(merged.decisions) ? merged.decisions : [];
+      merged.decisions = [...existing, ..._append_decisions];
+      // Cap to prevent unbounded growth (same MAX_DECISIONS as orchestrator)
+      if (merged.decisions.length > 200) {
+        merged.decisions = merged.decisions.slice(-200);
+      }
+    }
+
+    // Atomic propagation: run invalidation inside the lock on freshly-merged state
+    if (Array.isArray(_propagation_tasks) && _propagation_tasks.length > 0) {
+      for (const { phase_id, task_id, contract_changed } of _propagation_tasks) {
+        if (!contract_changed) continue;
+        const targetPhase = merged.phases.find(p => p.id === phase_id);
+        if (targetPhase) {
+          propagateInvalidation(targetPhase, task_id, true);
+        }
+      }
+    }
+
     // Recompute `done` from actual accepted tasks (prevents counter drift)
-    if (updates.phases && Array.isArray(updates.phases)) {
+    if ((updates.phases && Array.isArray(updates.phases)) || _propagation_tasks?.length > 0) {
       for (const phase of merged.phases) {
         if (Array.isArray(phase.todo)) {
           phase.done = phase.todo.filter(t => t.lifecycle === 'accepted').length;
@@ -336,7 +301,7 @@ export async function update({ updates, basePath = process.cwd() } = {}) {
     }
 
     await writeJson(statePath, merged);
-    return { success: true };
+    return { success: true, state: merged };
   });
 }
 
@@ -643,487 +608,305 @@ export async function pruneEvidence({ currentPhase, basePath = process.cwd() })
 }
 
 /**
- * Parse phase number from scope string like "task:X.Y" → X.
- * Returns null if scope is missing or doesn't match.
+ * Incrementally patch the plan: add/remove/reorder tasks, update task fields, add dependencies.
+ * Runs inside withStateLock for atomicity. Validates schema + circular deps after patching.
  */
-function parseScopePhase(scope) {
-  if (typeof scope !== 'string') return null;
-  const match = scope.match(/^task:(\d+)\./);
-  return match ? parseInt(match[1], 10) : null;
-}
-
-// ── Automation functions ──
-
-const DEFAULT_MAX_RETRY = 3;
-
-/**
- * Select the next runnable task from a phase, respecting dependency gates.
- * Returns { task } if a runnable task is found,
- * { mode: 'trigger_review' } if all remaining are checkpointed,
- * { mode: 'awaiting_user', blockers } if all are blocked,
- * { task: undefined } if nothing can run.
- * @param {object} phase - Phase object with todo array
- * @param {object} state - Full state object
- * @param {object} [options] - Options
- * @param {number} [options.maxRetry=3] - Maximum retry count before skipping a task
- */
-export function selectRunnableTask(phase, state, { maxRetry = DEFAULT_MAX_RETRY } = {}) {
-  if (!phase || !Array.isArray(phase.todo)) {
-    return { error: true, message: 'Phase todo must be an array' };
-  }
-  // D-4: Zero-task phase — immediately trigger review so phase can advance
-  if (phase.todo.length === 0) {
-    return { mode: 'trigger_review' };
+export async function patchPlan({ operations, basePath = process.cwd() } = {}) {
+  if (!Array.isArray(operations) || operations.length === 0) {
+    return { error: true, code: ERROR_CODES.INVALID_INPUT, message: 'operations must be a non-empty array' };
   }
 
-  const runnableTasks = [];
-
-  for (const task of phase.todo) {
-    if (!['pending', 'needs_revalidation'].includes(task.lifecycle)) continue;
-    if (task.retry_count >= maxRetry) continue;
-    if (task.blocked_reason) continue;
-
-    let depsOk = true;
-    for (const dep of (task.requires || [])) {
-      if (dep.kind === 'task') {
-        const depTask = phase.todo.find(t => t.id === dep.id);
-        if (!depTask) { depsOk = false; break; }
-        const gate = dep.gate || 'accepted';
-        if (gate === 'checkpoint' && !['checkpointed', 'accepted'].includes(depTask.lifecycle)) { depsOk = false; break; }
-        if (gate === 'accepted' && depTask.lifecycle !== 'accepted') { depsOk = false; break; }
-        if (gate === 'phase_complete') { depsOk = false; break; } // phase_complete is only valid on phase-kind deps
-      } else if (dep.kind === 'phase') {
-        const depPhaseId = Number(dep.id);
-        const depPhase = (state.phases || []).find(p => p.id === depPhaseId);
-        if (!depPhase || depPhase.lifecycle !== 'accepted') { depsOk = false; break; }
-      }
+  const validOps = ['add_task', 'remove_task', 'reorder_tasks', 'update_task', 'add_dependency'];
+  for (const op of operations) {
+    if (!op || typeof op !== 'object' || !validOps.includes(op.op)) {
+      return { error: true, code: ERROR_CODES.INVALID_INPUT, message: `Invalid operation: ${JSON.stringify(op?.op)}. Must be one of: ${validOps.join(', ')}` };
     }
-    if (depsOk) runnableTasks.push(task);
   }
 
-  if (runnableTasks.length > 0) {
-    return { task: runnableTasks[0] };
+  const statePath = await getStatePath(basePath);
+  if (!statePath) {
+    return { error: true, code: ERROR_CODES.NO_PROJECT_DIR, message: 'No .gsd directory found' };
   }
+  ensureLockPathFromStatePath(statePath);
 
-  const awaitingReview = phase.todo.filter(t => t.lifecycle === 'checkpointed');
-  if (awaitingReview.length > 0) {
-    return { mode: 'trigger_review' };
-  }
+  return withStateLock(async () => {
+    const result = await readJson(statePath);
+    if (!result.ok) {
+      return { error: true, code: ERROR_CODES.NO_PROJECT_DIR, message: result.error };
+    }
+    const state = migrateState(result.data);
 
-  // All tasks accepted → trigger phase review if not already reviewed
-  const allAccepted = phase.todo.length > 0 && phase.todo.every(t => t.lifecycle === 'accepted');
-  if (allAccepted && phase.phase_review?.status !== 'accepted') {
-    return { mode: 'trigger_review' };
-  }
+    // Guard: only allow patching in non-terminal states
+    if (state.workflow_mode === 'completed' || state.workflow_mode === 'failed') {
+      return { error: true, code: ERROR_CODES.TERMINAL_STATE, message: `Cannot patch plan in terminal state '${state.workflow_mode}'` };
+    }
 
-  const blockedTasks = phase.todo.filter(t => t.lifecycle === 'blocked');
-  if (blockedTasks.length > 0) {
-    return { mode: 'awaiting_user', blockers: blockedTasks.map(t => ({ id: t.id, reason: t.blocked_reason })) };
-  }
+    const applied = [];
+    const errors = [];
 
-  // Diagnose why no task is runnable
-  const diagnostics = [];
-  for (const task of phase.todo) {
-    if (task.lifecycle === 'accepted' || task.lifecycle === 'failed') continue;
-    const reasons = [];
-    if (!['pending', 'needs_revalidation'].includes(task.lifecycle)) {
-      reasons.push(`lifecycle=${task.lifecycle}`);
-    }
-    if (task.retry_count >= maxRetry) {
-      reasons.push(`retry_count=${task.retry_count} >= max=${maxRetry}`);
-    }
-    if (task.blocked_reason) {
-      reasons.push(`blocked: ${task.blocked_reason}`);
-    }
-    for (const dep of (task.requires || [])) {
-      if (dep.kind === 'task') {
-        const depTask = phase.todo.find(t => t.id === dep.id);
-        const gate = dep.gate || 'accepted';
-        if (!depTask) {
-          reasons.push(`dep ${dep.id} not found`);
-        } else if (gate === 'checkpoint' && !['checkpointed', 'accepted'].includes(depTask.lifecycle)) {
-          reasons.push(`dep ${dep.id} needs checkpoint (is ${depTask.lifecycle})`);
-        } else if (gate === 'accepted' && depTask.lifecycle !== 'accepted') {
-          reasons.push(`dep ${dep.id} needs accepted (is ${depTask.lifecycle})`);
-        } else if (gate === 'phase_complete') {
-          reasons.push(`dep ${dep.id} has phase_complete gate (invalid for task-kind dependency)`);
-        }
-      } else if (dep.kind === 'phase') {
-        const depPhaseId = Number(dep.id);
-        const depPhase = (state.phases || []).find(p => p.id === depPhaseId);
-        if (!depPhase || depPhase.lifecycle !== 'accepted') {
-          reasons.push(`phase dep ${dep.id} not accepted`);
-        }
+    for (const op of operations) {
+      const opResult = _applyPatchOp(state, op);
+      if (opResult.error) {
+        errors.push(`${op.op}: ${opResult.message}`);
+      } else {
+        applied.push(opResult.summary);
       }
     }
-    if (reasons.length > 0) {
-      diagnostics.push({ id: task.id, reasons });
+
+    if (errors.length > 0) {
+      return { error: true, code: ERROR_CODES.VALIDATION_FAILED, message: `Patch failed: ${errors.join('; ')}` };
     }
-  }
 
-  return { task: undefined, diagnostics };
-}
+    // Detect circular dependencies after all patches
+    const cycleError = _detectCycles(state);
+    if (cycleError) {
+      return { error: true, code: ERROR_CODES.VALIDATION_FAILED, message: cycleError };
+    }
 
-/**
- * Propagate invalidation to downstream dependents when a task is reworked.
- * If contractChanged is true, all transitive dependents get needs_revalidation
- * and their evidence_refs are cleared.
- */
-export function propagateInvalidation(phase, reworkTaskId, contractChanged) {
-  if (!contractChanged) return;
-
-  const affected = new Set();
-  const queue = [reworkTaskId];
-
-  while (queue.length > 0) {
-    const currentId = queue.shift();
-    for (const task of phase.todo) {
-      if (affected.has(task.id)) continue;
-      const dependsOnCurrent = (task.requires || []).some(dep =>
-        dep.kind === 'task' && dep.id === currentId
-      );
-      if (dependsOnCurrent) {
-        affected.add(task.id);
-        queue.push(task.id);
+    // Recompute done counts
+    for (const phase of state.phases) {
+      if (Array.isArray(phase.todo)) {
+        phase.tasks = phase.todo.length;
+        phase.done = phase.todo.filter(t => t.lifecycle === 'accepted').length;
       }
     }
-  }
+    state.total_phases = state.phases.length;
 
-  // C-2: Only transition tasks whose lifecycle allows needs_revalidation
-  const canInvalidate = new Set(
-    Object.entries(TASK_LIFECYCLE)
-      .filter(([, targets]) => targets.includes('needs_revalidation'))
-      .map(([state]) => state),
-  );
-  for (const task of phase.todo) {
-    if (affected.has(task.id) && canInvalidate.has(task.lifecycle)) {
-      task.lifecycle = 'needs_revalidation';
-      task.evidence_refs = [];
+    // Increment plan version
+    state.plan_version = (state.plan_version || 0) + 1;
+
+    // Full validation
+    const validation = validateState(state);
+    if (!validation.valid) {
+      return { error: true, code: ERROR_CODES.VALIDATION_FAILED, message: `Validation failed: ${validation.errors.join('; ')}` };
     }
-  }
+
+    await writeJson(statePath, state);
+    return { success: true, applied, plan_version: state.plan_version };
+  });
 }
 
-/**
- * Build executor context for a task: 6-field protocol.
- * Returns { task_spec, research_decisions, predecessor_outputs, project_conventions, workflows, constraints }.
- */
-export function buildExecutorContext(state, taskId, phaseId) {
-  const phase = state.phases.find(p => p.id === phaseId);
-  if (!phase) {
-    return { error: true, message: `Phase ${phaseId} not found` };
-  }
-  if (!Array.isArray(phase.todo)) {
-    return { error: true, message: `Phase ${phaseId} has invalid todo list` };
-  }
-  const task = phase.todo.find(t => t.id === taskId);
-  if (!task) {
-    return { error: true, message: `Task ${taskId} not found in phase ${phaseId}` };
-  }
+function _applyPatchOp(state, op) {
+  switch (op.op) {
+    case 'add_task': {
+      const { phase_id, task } = op;
+      if (typeof phase_id !== 'number') return { error: true, message: 'phase_id must be a number' };
+      if (!task || typeof task.name !== 'string' || task.name.length === 0) return { error: true, message: 'task.name must be a non-empty string' };
 
-  const task_spec = `phases/phase-${phaseId}.md`;
+      const phase = state.phases.find(p => p.id === phase_id);
+      if (!phase) return { error: true, message: `Phase ${phase_id} not found` };
 
-  const research_decisions = (task.research_basis || []).map(id => {
-    const decision = state.research?.decision_index?.[id];
-    return decision ? { id, ...decision } : { id, summary: 'not found' };
-  });
+      // Cannot add tasks to accepted phases
+      if (phase.lifecycle === 'accepted') return { error: true, message: `Cannot add tasks to accepted phase ${phase_id}` };
 
-  const predecessor_outputs = (task.requires || [])
-    .filter(dep => dep.kind === 'task')
-    .map(dep => {
-      const depTask = phase.todo.find(t => t.id === dep.id);
-      return depTask ? { files_changed: depTask.files_changed || [], checkpoint_commit: depTask.checkpoint_commit } : null;
-    })
-    .filter(Boolean);
-
-  const project_conventions = 'CLAUDE.md';
-  const workflows = ['workflows/tdd-cycle.md', 'workflows/deviation-rules.md'];
-  if ((task.retry_count || 0) > 0) workflows.push('workflows/debugging.md');
-  if ((task.research_basis || []).length > 0) workflows.push('workflows/research.md');
-  const constraints = {
-    retry_count: task.retry_count || 0,
-    level: task.level || 'L1',
-    review_required: task.review_required !== false,
-  };
-
-  const debugger_guidance = task.debug_context ? {
-    root_cause: task.debug_context.root_cause,
-    fix_direction: task.debug_context.fix_direction,
-    fix_attempts: task.debug_context.fix_attempts,
-    evidence: task.debug_context.evidence || [],
-  } : null;
-
-  const rework_feedback = Array.isArray(task.last_review_feedback) && task.last_review_feedback.length > 0
-    ? task.last_review_feedback
-    : null;
-
-  return {
-    task_spec,
-    research_decisions,
-    predecessor_outputs,
-    project_conventions,
-    workflows,
-    constraints,
-    debugger_guidance,
-    rework_feedback,
-  };
-}
+      // Compute next task index
+      const existingIndices = phase.todo.map(t => {
+        const parts = t.id.split('.');
+        return parseInt(parts[1], 10);
+      });
+      const nextIndex = existingIndices.length > 0 ? Math.max(...existingIndices) + 1 : 1;
+      const taskId = `${phase_id}.${task.index ?? nextIndex}`;
 
-const SENSITIVE_KEYWORDS = /\b(auth|payment|security|public.?api|login|token|credential|session|oauth)\b/i;
+      // Check for duplicate ID
+      if (phase.todo.some(t => t.id === taskId)) {
+        return { error: true, message: `Task ID ${taskId} already exists` };
+      }
 
-/**
- * Reclassify review level at runtime based on executor results.
- * Upgrades L1→L2 when contract_changed + sensitive keywords or [LEVEL-UP].
- * Never downgrades.
- */
-export function reclassifyReviewLevel(task, executorResult) {
-  const currentLevel = task.level || 'L1';
+      const level = task.level || 'L1';
+      if (!TASK_LEVELS.includes(level)) {
+        return { error: true, message: `level must be one of ${TASK_LEVELS.join(', ')} (got "${level}")` };
+      }
 
-  // Never downgrade
-  if (currentLevel === 'L2' || currentLevel === 'L3') {
-    return currentLevel;
-  }
+      const newTask = {
+        id: taskId,
+        name: task.name,
+        lifecycle: 'pending',
+        level,
+        requires: task.requires || [],
+        retry_count: 0,
+        review_required: task.review_required !== false,
+        verification_required: task.verification_required !== false,
+        checkpoint_commit: null,
+        research_basis: task.research_basis || [],
+        evidence_refs: [],
+      };
 
-  // Check for explicit [LEVEL-UP] in decisions
-  const hasLevelUp = (executorResult.decisions || []).some(d =>
-    (typeof d === 'string' && d.includes('[LEVEL-UP]'))
-    || (d && typeof d === 'object' && typeof d.summary === 'string' && d.summary.includes('[LEVEL-UP]'))
-  );
-  if (hasLevelUp) return 'L2';
+      // Insert after specified task or at end
+      if (task.after) {
+        const afterIdx = phase.todo.findIndex(t => t.id === task.after);
+        if (afterIdx === -1) return { error: true, message: `after task ${task.after} not found` };
+        phase.todo.splice(afterIdx + 1, 0, newTask);
+      } else {
+        phase.todo.push(newTask);
+      }
 
-  // Check for contract change + sensitive keyword in task name
-  if (executorResult.contract_changed && SENSITIVE_KEYWORDS.test(task.name || '')) {
-    return 'L2';
-  }
+      return { summary: `Added task ${taskId} "${task.name}" to phase ${phase_id}` };
+    }
 
-  return currentLevel;
-}
+    case 'remove_task': {
+      const { task_id } = op;
+      if (typeof task_id !== 'string') return { error: true, message: 'task_id must be a string' };
 
-const MIN_TOKEN_LENGTH = 2;
-const MIN_OVERLAP = 2;
+      const phase = state.phases.find(p => p.todo?.some(t => t.id === task_id));
+      if (!phase) return { error: true, message: `Task ${task_id} not found` };
 
-// High-frequency words too generic for meaningful keyword matching
-const STOPWORDS = new Set([
-  'the', 'and', 'for', 'with', 'this', 'that', 'from', 'have', 'not',
-  'but', 'are', 'was', 'been', 'will', 'can', 'should', 'would', 'could',
-  'use', 'using', 'need', 'needs', 'into', 'also', 'when', 'then',
-  'than', 'more', 'some', 'does', 'did', 'its', 'has', 'all', 'any',
-  'error', 'data', 'type', 'value', 'file', 'code', 'function',
-  'return', 'null', 'true', 'false', 'undefined', 'object', 'string',
-  'number', 'array', 'list', 'map', 'set', 'key', 'name',
-]);
+      const task = phase.todo.find(t => t.id === task_id);
+      // Cannot remove running or accepted tasks
+      if (['running', 'accepted', 'checkpointed'].includes(task.lifecycle)) {
+        return { error: true, message: `Cannot remove task ${task_id} in '${task.lifecycle}' state` };
+      }
 
-/**
- * Tokenize a string into lowercase tokens, splitting on whitespace and punctuation.
- * Filters out short tokens (< MIN_TOKEN_LENGTH) and stopwords.
- */
-function tokenize(text) {
-  if (!text) return [];
-  return text
-    .toLowerCase()
-    .split(/[\s,.:;!?()[\]{}<>/\\|@#$%^&*+=~`'"，。：；！？（）【】、]+/)
-    .filter(t => t.length >= MIN_TOKEN_LENGTH && !STOPWORDS.has(t));
-}
+      // Check if any other task depends on this one
+      for (const p of state.phases) {
+        for (const t of (p.todo || [])) {
+          const depOnRemoved = (t.requires || []).some(d => d.kind === 'task' && d.id === task_id);
+          if (depOnRemoved) {
+            return { error: true, message: `Cannot remove task ${task_id}: task ${t.id} depends on it` };
+          }
+        }
+      }
 
-/**
- * Match a blocked reason against research decisions by keyword overlap.
- * Returns the best-matching decision or null if no sufficient overlap.
- */
-export function matchDecisionForBlocker(decisions, blockedReason) {
-  const reasonTokens = new Set(tokenize(blockedReason));
-  if (reasonTokens.size === 0) return null;
-
-  let bestMatch = null;
-  let bestOverlap = 0;
-
-  for (const decision of decisions) {
-    const summaryTokens = tokenize(decision.summary);
-    let overlap = 0;
-    for (const token of summaryTokens) {
-      if (reasonTokens.has(token)) {
-        overlap++;
+      // Remove current_task reference if it points to this task
+      if (state.current_task === task_id) {
+        state.current_task = null;
       }
+
+      phase.todo = phase.todo.filter(t => t.id !== task_id);
+      return { summary: `Removed task ${task_id} from phase ${phase.id}` };
     }
-    if (overlap >= MIN_OVERLAP && overlap > bestOverlap) {
-      bestOverlap = overlap;
-      bestMatch = decision;
-    }
-  }
 
-  return bestMatch;
-}
+    case 'reorder_tasks': {
+      const { phase_id, order } = op;
+      if (typeof phase_id !== 'number') return { error: true, message: 'phase_id must be a number' };
+      if (!Array.isArray(order)) return { error: true, message: 'order must be an array of task IDs' };
 
-/**
- * Apply research refresh: compare new research decisions against existing state.
- * 4 rules:
- *   1. Same ID + same summary → update metadata (e.g. expires_at), keep task lifecycle
- *   2. Same ID + changed summary → invalidate dependent tasks (needs_revalidation)
- *   3. Old ID missing from new → invalidate dependent tasks + warning
- *   4. Brand new ID → add to index, no impact on existing tasks
- * Returns { warnings: string[] }.
- */
-export function applyResearchRefresh(state, newResearch) {
-  const warnings = [];
-  const oldIndex = state.research?.decision_index || {};
-  const newIndex = newResearch?.decision_index || {};
-
-  // Copy-on-write: build merged index without mutating oldIndex
-  const mergedIndex = { ...oldIndex };
-
-  // Collect IDs of decisions that changed or were removed
-  const invalidatedIds = new Set();
-
-  // Check existing decisions against new
-  for (const [id, oldDecision] of Object.entries(oldIndex)) {
-    if (id in newIndex) {
-      const newDecision = newIndex[id];
-      if (oldDecision.summary === newDecision.summary) {
-        // Rule 1: same conclusion — update metadata
-        mergedIndex[id] = { ...oldDecision, ...newDecision };
-      } else {
-        // Rule 2: changed conclusion — replace and invalidate
-        mergedIndex[id] = newDecision;
-        invalidatedIds.add(id);
+      const phase = state.phases.find(p => p.id === phase_id);
+      if (!phase) return { error: true, message: `Phase ${phase_id} not found` };
+
+      const taskMap = new Map(phase.todo.map(t => [t.id, t]));
+      const existing = new Set(taskMap.keys());
+      const ordered = new Set(order);
+
+      // Must contain exactly the same task IDs
+      if (ordered.size !== existing.size || ![...ordered].every(id => existing.has(id))) {
+        return { error: true, message: `order must contain exactly the same task IDs as phase ${phase_id}` };
       }
-    } else {
-      // Rule 3: old ID missing from new research
-      invalidatedIds.add(id);
-      warnings.push(`Decision "${id}" removed in new research — dependent tasks invalidated`);
-    }
-  }
 
-  // Rule 4: brand new IDs — just add them
-  for (const [id, newDecision] of Object.entries(newIndex)) {
-    if (!(id in oldIndex)) {
-      mergedIndex[id] = newDecision;
+      phase.todo = order.map(id => taskMap.get(id));
+      return { summary: `Reordered tasks in phase ${phase_id}` };
     }
-  }
 
-  // Assign merged index to state (atomic replacement)
-  if (!state.research) state.research = {};
-  state.research.decision_index = mergedIndex;
+    case 'update_task': {
+      const { task_id, ...fields } = op;
+      if (typeof task_id !== 'string') return { error: true, message: 'task_id must be a string' };
 
-  // C-3: Only invalidate tasks whose lifecycle allows needs_revalidation
-  if (invalidatedIds.size > 0) {
-    const canInvalidate = new Set(
-      Object.entries(TASK_LIFECYCLE)
-        .filter(([, targets]) => targets.includes('needs_revalidation'))
-        .map(([s]) => s),
-    );
-    for (const phase of (state.phases || [])) {
-      for (const task of (phase.todo || [])) {
-        const basis = task.research_basis || [];
-        const affected = basis.some(id => invalidatedIds.has(id));
-        if (affected && canInvalidate.has(task.lifecycle)) {
-          task.lifecycle = 'needs_revalidation';
-          if (task.evidence_refs) task.evidence_refs = [];
+      const phase = state.phases.find(p => p.todo?.some(t => t.id === task_id));
+      if (!phase) return { error: true, message: `Task ${task_id} not found` };
+
+      const task = phase.todo.find(t => t.id === task_id);
+      const allowedFields = ['name', 'level', 'review_required', 'verification_required', 'research_basis'];
+      const updates = {};
+      for (const key of allowedFields) {
+        if (key in fields) {
+          updates[key] = fields[key];
         }
       }
-    }
-  }
-
-  return { warnings };
-}
-
-export async function storeResearch({ result, artifacts, decision_index, basePath = process.cwd() } = {}) {
-  const resultValidation = validateResearcherResult(result || {});
-  if (!resultValidation.valid) {
-    return { error: true, code: ERROR_CODES.VALIDATION_FAILED, message: `Invalid researcher result: ${resultValidation.errors.join('; ')}` };
-  }
 
-  const artifactsValidation = validateResearchArtifacts(artifacts);
-  if (!artifactsValidation.valid) {
-    return { error: true, code: ERROR_CODES.VALIDATION_FAILED, message: `Invalid research artifacts: ${artifactsValidation.errors.join('; ')}` };
-  }
+      if (Object.keys(updates).length === 0) {
+        return { error: true, message: `No valid fields to update. Allowed: ${allowedFields.join(', ')}` };
+      }
+      if (updates.level && !TASK_LEVELS.includes(updates.level)) {
+        return { error: true, message: `level must be one of ${TASK_LEVELS.join(', ')} (got "${updates.level}")` };
+      }
 
-  const decisionIndexValidation = validateResearchDecisionIndex(decision_index, result.decision_ids);
-  if (!decisionIndexValidation.valid) {
-    return { error: true, code: ERROR_CODES.VALIDATION_FAILED, message: `Invalid research decision_index: ${decisionIndexValidation.errors.join('; ')}` };
-  }
+      Object.assign(task, updates);
+      return { summary: `Updated task ${task_id}: ${Object.keys(updates).join(', ')}` };
+    }
 
-  const statePath = await getStatePath(basePath);
-  if (!statePath) {
-    return { error: true, code: ERROR_CODES.NO_PROJECT_DIR, message: 'No .gsd directory found' };
-  }
-  ensureLockPathFromStatePath(statePath);
+    case 'add_dependency': {
+      const { task_id, requires } = op;
+      if (typeof task_id !== 'string') return { error: true, message: 'task_id must be a string' };
+      if (!requires || typeof requires !== 'object') return { error: true, message: 'requires must be an object with kind and id' };
 
-  return withStateLock(async () => {
-    const current = await readJson(statePath);
-    if (!current.ok) {
-      return { error: true, code: ERROR_CODES.NO_PROJECT_DIR, message: current.error };
-    }
+      const phase = state.phases.find(p => p.todo?.some(t => t.id === task_id));
+      if (!phase) return { error: true, message: `Task ${task_id} not found` };
 
-    const state = current.data;
-    const gsdDir = dirname(statePath);
-    const researchDir = join(gsdDir, 'research');
-    await ensureDir(researchDir);
-
-    // Atomic multi-file write: write all artifacts first, then rename in batch
-    const normalizedArtifacts = normalizeResearchArtifacts(artifacts);
-    const tmpSuffix = `.${process.pid}-${Date.now()}.tmp`;
-    const tmpPaths = [];
-    try {
-      for (const fileName of RESEARCH_FILES) {
-        const finalPath = join(researchDir, fileName);
-        const tmpFile = finalPath + tmpSuffix;
-        tmpPaths.push({ tmp: tmpFile, final: finalPath });
-        await writeFile(tmpFile, normalizedArtifacts[fileName], 'utf-8');
+      if (!['task', 'phase'].includes(requires.kind)) {
+        return { error: true, message: `requires.kind must be "task" or "phase"` };
       }
-      // All writes succeeded — rename in batch
-      for (const { tmp, final: finalPath } of tmpPaths) {
-        await rename(tmp, finalPath);
+
+      const validGates = ['checkpoint', 'accepted', 'phase_complete'];
+      if (requires.gate && !validGates.includes(requires.gate)) {
+        return { error: true, message: `requires.gate must be one of ${validGates.join(', ')}` };
       }
-    } catch (err) {
-      // Cleanup any temp files on failure
-      for (const { tmp } of tmpPaths) {
-        try { await unlink(tmp); } catch {}
+
+      // Validate target exists
+      if (requires.kind === 'task') {
+        const targetExists = state.phases.some(p => p.todo?.some(t => t.id === requires.id));
+        if (!targetExists) return { error: true, message: `Dependency target task ${requires.id} not found` };
+      } else {
+        const phaseId = Number(requires.id);
+        if (!state.phases.some(p => p.id === phaseId)) {
+          return { error: true, message: `Dependency target phase ${requires.id} not found` };
+        }
       }
-      throw err;
-    }
 
-    const nextResearchBase = {
-      volatility: result.volatility,
-      expires_at: result.expires_at,
-      sources: result.sources,
-      files: RESEARCH_FILES,
-      updated_at: new Date().toISOString(),
-    };
+      const task = phase.todo.find(t => t.id === task_id);
+      // Check for duplicate dependency
+      const isDupe = task.requires.some(d => d.kind === requires.kind && String(d.id) === String(requires.id));
+      if (isDupe) return { error: true, message: `Task ${task_id} already depends on ${requires.kind}:${requires.id}` };
 
-    const refreshResult = state.research
-      ? applyResearchRefresh(state, { ...nextResearchBase, decision_index })
-      : { warnings: [] };
+      task.requires.push(requires);
+      return { summary: `Added dependency ${requires.kind}:${requires.id} to task ${task_id}` };
+    }
 
-    // After applyResearchRefresh, state.research.decision_index is the merged result
-    const mergedDecisionIndex = state.research?.decision_index || decision_index;
-    state.research = {
-      ...(state.research || {}),
-      ...nextResearchBase,
-      decision_index: mergedDecisionIndex,
-    };
+    default:
+      return { error: true, message: `Unknown operation: ${op.op}` };
+  }
+}
 
-    if (state.workflow_mode === 'research_refresh_needed') {
-      state.workflow_mode = inferWorkflowModeAfterResearch(state);
+function _detectCycles(state) {
+  for (const phase of state.phases) {
+    const tasks = phase.todo || [];
+    const taskIds = tasks.map(t => t.id);
+    const inDegree = new Map(taskIds.map(id => [id, 0]));
+    const adj = new Map(taskIds.map(id => [id, []]));
+
+    for (const task of tasks) {
+      for (const dep of (task.requires || [])) {
+        if (dep.kind === 'task' && inDegree.has(dep.id)) {
+          adj.get(dep.id).push(task.id);
+          inDegree.set(task.id, inDegree.get(task.id) + 1);
+        }
+      }
     }
 
-    // Recompute done after applyResearchRefresh may have invalidated tasks
-    for (const phase of (state.phases || [])) {
-      if (Array.isArray(phase.todo)) {
-        phase.done = phase.todo.filter(t => t.lifecycle === 'accepted').length;
+    const queue = [...inDegree.entries()].filter(([, d]) => d === 0).map(([id]) => id);
+    let sorted = 0;
+    while (queue.length > 0) {
+      const node = queue.shift();
+      sorted++;
+      for (const neighbor of adj.get(node)) {
+        const d = inDegree.get(neighbor) - 1;
+        inDegree.set(neighbor, d);
+        if (d === 0) queue.push(neighbor);
       }
     }
 
-    const validation = validateState(state);
-    if (!validation.valid) {
-      return { error: true, code: ERROR_CODES.VALIDATION_FAILED, message: `State validation failed: ${validation.errors.join('; ')}` };
+    if (sorted < taskIds.length) {
+      const cycleNodes = [...inDegree.entries()].filter(([, d]) => d > 0).map(([id]) => id);
+      return `Circular dependency detected in phase ${phase.id}: ${cycleNodes.join(', ')}`;
     }
+  }
+  return null;
+}
 
-    await writeJson(statePath, state);
-    return {
-      success: true,
-      workflow_mode: state.workflow_mode,
-      stored_files: RESEARCH_FILES,
-      decision_ids: result.decision_ids,
-      warnings: refreshResult.warnings,
-      research: state.research,
-    };
-  });
+/**
+ * Parse phase number from scope string like "task:X.Y" -> X.
+ * Returns null if scope is missing or doesn't match.
+ */
+function parseScopePhase(scope) {
+  if (typeof scope !== 'string') return null;
+  const match = scope.match(/^task:(\d+)\./);
+  return match ? parseInt(match[1], 10) : null;
 }