gsd-lite 0.5.10 → 0.5.13

package/src/server.js

@@ -3,7 +3,7 @@ import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
 import { CallToolRequestSchema, ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js';
 import { pathToFileURL } from 'node:url';
 import { createRequire } from 'node:module';
-import { init, read, update, phaseComplete } from './tools/state.js';
+import { init, read, update, phaseComplete, patchPlan } from './tools/state/index.js';
 
 const _require = createRequire(import.meta.url);
 const PKG_VERSION = _require('../package.json').version;
@@ -41,7 +41,7 @@ import {
   handleResearcherResult,
   handleReviewerResult,
   resumeWorkflow,
-} from './tools/orchestrator.js';
+} from './tools/orchestrator/index.js';
 
 const server = new Server(
   { name: 'gsd', version: PKG_VERSION },
@@ -154,6 +154,32 @@ const TOOLS = [
       required: ['phase_id'],
     },
   },
+  {
+    name: 'state-patch',
+    description: 'Incrementally patch the plan: add/remove/reorder tasks, update fields, add dependencies — without full replan',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        operations: {
+          type: 'array',
+          description: 'Array of patch operations. Each: {op: "add_task"|"remove_task"|"reorder_tasks"|"update_task"|"add_dependency", ...params}',
+          items: {
+            type: 'object',
+            properties: {
+              op: { type: 'string', description: 'Operation type' },
+              phase_id: { type: 'number', description: 'Phase ID (for add_task, reorder_tasks)' },
+              task_id: { type: 'string', description: 'Task ID (for remove_task, update_task, add_dependency)' },
+              task: { type: 'object', description: 'Task definition (for add_task): {name, level?, requires?, after?, review_required?, verification_required?}' },
+              order: { type: 'array', items: { type: 'string' }, description: 'Ordered task IDs (for reorder_tasks)' },
+              requires: { type: 'object', description: 'Dependency (for add_dependency): {kind: "task"|"phase", id, gate?}' },
+            },
+            required: ['op'],
+          },
+        },
+      },
+      required: ['operations'],
+    },
+  },
   {
     name: 'orchestrator-resume',
     description: 'Resume the minimal orchestration loop from workflow_mode/current_phase state',
@@ -265,6 +291,9 @@ async function dispatchToolCall(name, args) {
     case 'phase-complete':
       result = await phaseComplete(args);
       break;
+    case 'state-patch':
+      result = await patchPlan(args);
+      break;
     case 'orchestrator-resume':
       result = await resumeWorkflow(args || {});
       break;

package/src/tools/orchestrator/debugger.js

@@ -0,0 +1,94 @@
+import { read } from '../state/index.js';
+import { validateDebuggerResult } from '../../schema.js';
+import {
+  getPhaseAndTask,
+  persist,
+  persistAndRead,
+  buildExecutorDispatch,
+} from './helpers.js';
+
+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,
+    };
+  }
+
+  // Reset retry_count after successful debugging so executor gets fresh attempts
+  const refreshed = await persistAndRead(basePath, {
+    workflow_mode: 'executing_task',
+    current_task: task.id,
+    current_review: null,
+    phases: [{
+      id: phase.id,
+      todo: [{
+        id: task.id,
+        retry_count: 0,
+        debug_context,
+      }],
+    }],
+  });
+  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,
+  });
+}

package/src/tools/orchestrator/executor.js

@@ -0,0 +1,162 @@
+import { read, reclassifyReviewLevel } from '../state/index.js';
+import { validateExecutorResult } from '../../schema.js';
+import {
+  MAX_DEBUG_RETRY,
+  RESULT_CONTRACTS,
+  getPhaseAndTask,
+  getBlockedTasks,
+  buildDecisionEntries,
+  buildErrorFingerprint,
+  getBlockedReasonFromResult,
+  persist,
+} from './helpers.js';
+
+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` };
+  }
+
+  // Build new decision entries — actual append happens atomically inside update()'s lock
+  const newDecisions = buildDecisionEntries(result.decisions, phase.id, task.id, (state.decisions || []).length);
+
+  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,
+      phases: [phasePatch],
+      ...(Object.keys(evidenceUpdates).length > 0 ? { evidence: evidenceUpdates } : {}),
+    }, { _append_decisions: newDecisions });
+    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,
+      phases: [{
+        id: phase.id,
+        todo: [{
+          id: task.id,
+          lifecycle: 'blocked',
+          blocked_reason,
+          unblock_condition,
+          evidence_refs: result.evidence || [],
+        }],
+      }],
+    }, { _append_decisions: newDecisions });
+    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,
+    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 || [],
+      }],
+    }],
+  }, { _append_decisions: newDecisions });
+  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,
+  };
+}