gsd-lite 0.3.1 → 0.3.5

package/src/schema.js

@@ -36,10 +36,11 @@ export const PHASE_LIFECYCLE = {
   failed:     [],
 };
 
-const PHASE_REVIEW_STATUS = ['pending', 'reviewing', 'accepted', 'rework_required'];
+export const PHASE_REVIEW_STATUS = ['pending', 'reviewing', 'accepted', 'rework_required'];
 
 export const CANONICAL_FIELDS = [
   'project',
+  'schema_version',
   'workflow_mode',
   'plan_version',
   'git_head',
@@ -133,6 +134,9 @@ export function validateResearchArtifacts(artifacts, { decisionIds = [], volatil
 }
 
 export function validateTransition(entity, from, to) {
+  if (entity !== 'task' && entity !== 'phase') {
+    return { valid: false, error: `Unknown entity type: ${entity}` };
+  }
   const transitions = entity === 'task' ? TASK_LIFECYCLE : PHASE_LIFECYCLE;
   if (!transitions[from]) {
     return { valid: false, error: `Unknown ${entity} state: ${from}` };
@@ -143,25 +147,119 @@ export function validateTransition(entity, from, to) {
   return { valid: true };
 }
 
+/**
+ * Incremental validation: only validate changed fields + their relationships.
+ * Falls back to full validateState() for complex updates (phases).
+ */
+export function validateStateUpdate(state, updates) {
+  // For phases updates, fall back to full validation
+  if ('phases' in updates) {
+    return validateState({ ...state, ...updates });
+  }
+
+  const errors = [];
+
+  for (const key of Object.keys(updates)) {
+    switch (key) {
+      case 'workflow_mode':
+        if (!WORKFLOW_MODES.includes(updates.workflow_mode)) {
+          errors.push(`Invalid workflow_mode: ${updates.workflow_mode}`);
+        }
+        break;
+      case 'current_phase':
+        if (!Number.isFinite(updates.current_phase)) {
+          errors.push('current_phase must be a finite number');
+        }
+        break;
+      case 'current_task':
+        if (updates.current_task !== null && typeof updates.current_task !== 'string') {
+          errors.push('current_task must be a string or null');
+        }
+        break;
+      case 'current_review':
+        if (updates.current_review !== null && !isPlainObject(updates.current_review)) {
+          errors.push('current_review must be an object or null');
+        }
+        break;
+      case 'git_head':
+        if (updates.git_head !== null && typeof updates.git_head !== 'string') {
+          errors.push('git_head must be a string or null');
+        }
+        break;
+      case 'plan_version':
+        if (!Number.isFinite(updates.plan_version)) {
+          errors.push('plan_version must be a finite number');
+        }
+        break;
+      case 'schema_version':
+        if (!Number.isFinite(updates.schema_version)) {
+          errors.push('schema_version must be a finite number');
+        }
+        break;
+      case 'total_phases':
+        if (!Number.isFinite(updates.total_phases)) {
+          errors.push('total_phases must be a finite number');
+        }
+        break;
+      case 'project':
+        if (!updates.project || typeof updates.project !== 'string') {
+          errors.push('project must be a non-empty string');
+        }
+        break;
+      case 'decisions':
+        if (!Array.isArray(updates.decisions)) {
+          errors.push('decisions must be an array');
+        }
+        break;
+      case 'context':
+        if (!isPlainObject(updates.context)) {
+          errors.push('context must be an object');
+        } else {
+          const ctx = { ...state.context, ...updates.context };
+          if (typeof ctx.last_session !== 'string') errors.push('context.last_session must be a string');
+          if (!Number.isFinite(ctx.remaining_percentage)) errors.push('context.remaining_percentage must be a finite number');
+        }
+        break;
+      case 'evidence':
+        if (!isPlainObject(updates.evidence)) {
+          errors.push('evidence must be an object');
+        }
+        break;
+      case 'research':
+        if (updates.research !== null && !isPlainObject(updates.research)) {
+          errors.push('research must be null or an object');
+        }
+        break;
+      default:
+        errors.push(`Unknown canonical field: ${key}`);
+    }
+  }
+
+  return { valid: errors.length === 0, errors };
+}
+
 export function validateState(state) {
   const errors = [];
   if (!state.project || typeof state.project !== 'string') {
     errors.push('project must be a non-empty string');
   }
+  if (!Number.isFinite(state.schema_version)) {
+    errors.push('schema_version must be a finite number');
+  }
   if (!WORKFLOW_MODES.includes(state.workflow_mode)) {
     errors.push(`Invalid workflow_mode: ${state.workflow_mode}`);
   }
-  if (typeof state.plan_version !== 'number') {
-    errors.push('plan_version must be a number');
+  if (!Number.isFinite(state.plan_version)) {
+    errors.push('plan_version must be a finite number');
   }
-  if (typeof state.current_phase !== 'number') {
-    errors.push('current_phase must be a number');
+  if (!Number.isFinite(state.current_phase)) {
+    errors.push('current_phase must be a finite number');
   }
   if (state.git_head !== null && typeof state.git_head !== 'string') {
     errors.push('git_head must be a string or null');
   }
-  if (typeof state.total_phases !== 'number') {
-    errors.push('total_phases must be a number');
+  if (!Number.isFinite(state.total_phases)) {
+    errors.push('total_phases must be a finite number');
   }
   if (!Array.isArray(state.phases)) {
     errors.push('phases must be an array');
@@ -175,8 +273,8 @@ export function validateState(state) {
     if (typeof state.context.last_session !== 'string') {
       errors.push('context.last_session must be a string');
     }
-    if (typeof state.context.remaining_percentage !== 'number') {
-      errors.push('context.remaining_percentage must be a number');
+    if (!Number.isFinite(state.context.remaining_percentage)) {
+      errors.push('context.remaining_percentage must be a finite number');
     }
   }
   if (state.research !== null && !isPlainObject(state.research)) {
@@ -212,6 +310,12 @@ export function validateState(state) {
       errors.push(...decisionIndexValidation.errors.map((error) => `research.${error}`));
     }
   }
+  if (state.current_task !== null && typeof state.current_task !== 'string') {
+    errors.push('current_task must be a string or null');
+  }
+  if (state.current_review !== null && !isPlainObject(state.current_review)) {
+    errors.push('current_review must be an object or null');
+  }
   if (!isPlainObject(state.evidence)) {
     errors.push('evidence must be an object');
   }
@@ -224,8 +328,8 @@ export function validateState(state) {
         errors.push('phase must be an object');
         continue;
       }
-      if (typeof phase.id !== 'number') {
-        errors.push('phase.id must be a number');
+      if (!Number.isFinite(phase.id)) {
+        errors.push('phase.id must be a finite number');
       }
       if (!phase.name || typeof phase.name !== 'string') {
         errors.push(`Phase ${phase.id}: name must be a non-empty string`);
@@ -239,15 +343,15 @@ export function validateState(state) {
         if (!PHASE_REVIEW_STATUS.includes(phase.phase_review.status)) {
           errors.push(`Phase ${phase.id}: invalid phase_review.status ${phase.phase_review.status}`);
         }
-        if (typeof phase.phase_review.retry_count !== 'number') {
-          errors.push(`Phase ${phase.id}: phase_review.retry_count must be a number`);
+        if (!Number.isFinite(phase.phase_review.retry_count)) {
+          errors.push(`Phase ${phase.id}: phase_review.retry_count must be a finite number`);
         }
       }
-      if (typeof phase.tasks !== 'number') {
-        errors.push(`Phase ${phase.id}: tasks must be a number`);
+      if (!Number.isFinite(phase.tasks)) {
+        errors.push(`Phase ${phase.id}: tasks must be a finite number`);
       }
-      if (typeof phase.done !== 'number') {
-        errors.push(`Phase ${phase.id}: done must be a number`);
+      if (!Number.isFinite(phase.done)) {
+        errors.push(`Phase ${phase.id}: done must be a finite number`);
       }
       if (!Array.isArray(phase.todo)) {
         errors.push(`Phase ${phase.id}: todo must be an array`);
@@ -262,8 +366,8 @@ export function validateState(state) {
         if (typeof phase.phase_handoff.tests_passed !== 'boolean') {
           errors.push(`Phase ${phase.id}: phase_handoff.tests_passed must be boolean`);
         }
-        if (typeof phase.phase_handoff.critical_issues_open !== 'number') {
-          errors.push(`Phase ${phase.id}: phase_handoff.critical_issues_open must be a number`);
+        if (!Number.isFinite(phase.phase_handoff.critical_issues_open)) {
+          errors.push(`Phase ${phase.id}: phase_handoff.critical_issues_open must be a finite number`);
         }
         if ('direction_ok' in phase.phase_handoff && typeof phase.phase_handoff.direction_ok !== 'boolean') {
           errors.push(`Phase ${phase.id}: phase_handoff.direction_ok must be boolean when present`);
@@ -289,8 +393,8 @@ export function validateState(state) {
         if (!Array.isArray(task.requires)) {
           errors.push(`Task ${task.id}: requires must be an array`);
         }
-        if (typeof task.retry_count !== 'number') {
-          errors.push(`Task ${task.id}: retry_count must be a number`);
+        if (!Number.isFinite(task.retry_count)) {
+          errors.push(`Task ${task.id}: retry_count must be a finite number`);
         }
         if (typeof task.review_required !== 'boolean') {
           errors.push(`Task ${task.id}: review_required must be a boolean`);
@@ -318,7 +422,7 @@ export function validateState(state) {
  */
 export function validateExecutorResult(r) {
   const errors = [];
-  if (!r.task_id) errors.push('missing task_id');
+  if (typeof r.task_id !== 'string' || r.task_id.length === 0) errors.push('missing task_id');
   if (!['checkpointed', 'blocked', 'failed'].includes(r.outcome)) errors.push('invalid outcome');
   if (typeof r.summary !== 'string' || r.summary.length === 0) errors.push('summary must be non-empty string');
   if ('checkpoint_commit' in r && r.checkpoint_commit !== null && typeof r.checkpoint_commit !== 'string') {
@@ -354,6 +458,12 @@ export function validateReviewerResult(r) {
   if (!Array.isArray(r.rework_tasks)) errors.push('rework_tasks must be array');
   if (!Array.isArray(r.evidence)) errors.push('evidence must be array');
 
+  if (Array.isArray(r.accepted_tasks) && Array.isArray(r.rework_tasks)) {
+    const overlap = r.accepted_tasks.filter(id => r.rework_tasks.includes(id));
+    if (overlap.length > 0) {
+      errors.push(`accepted_tasks and rework_tasks must be disjoint; overlap: ${overlap.join(', ')}`);
+    }
+  }
   for (const issue of r.critical_issues || []) {
     if (!isPlainObject(issue)) {
       errors.push('critical_issues entries must be objects');
@@ -390,7 +500,7 @@ export function validateResearcherResult(r) {
  */
 export function validateDebuggerResult(r) {
   const errors = [];
-  if (!r.task_id) errors.push('missing task_id');
+  if (typeof r.task_id !== 'string' || r.task_id.length === 0) errors.push('missing task_id');
   if (!['root_cause_found', 'fix_suggested', 'failed'].includes(r.outcome)) errors.push('invalid outcome');
   if (typeof r.root_cause !== 'string' || r.root_cause.length === 0) errors.push('root_cause must be non-empty string');
   if (!Array.isArray(r.evidence)) errors.push('evidence must be array');
@@ -421,16 +531,26 @@ export function validateDebuggerResult(r) {
 }
 
 export function createInitialState({ project, phases }) {
-  // Validate task names before creating state
-  for (const [pi, p] of (phases || []).entries()) {
+  if (!Array.isArray(phases)) {
+    return { error: true, message: 'phases must be an array' };
+  }
+  // Validate task names and uniqueness before creating state
+  const seenIds = new Set();
+  for (const [pi, p] of phases.entries()) {
     for (const [ti, t] of (p.tasks || []).entries()) {
       if (!t.name || typeof t.name !== 'string') {
         return { error: true, message: `Phase ${pi + 1} task ${ti + 1}: name is required (got ${JSON.stringify(t.name)})` };
       }
+      const id = `${pi + 1}.${t.index ?? (ti + 1)}`;
+      if (seenIds.has(id)) {
+        return { error: true, message: `Duplicate task ID: ${id} in phase ${pi + 1}` };
+      }
+      seenIds.add(id);
     }
   }
   return {
     project,
+    schema_version: 1,
     workflow_mode: 'executing_task',
     plan_version: 1,
     git_head: null,
@@ -446,7 +566,7 @@ export function createInitialState({ project, phases }) {
       tasks: p.tasks ? p.tasks.length : 0,
       done: 0,
       todo: (p.tasks || []).map((t, ti) => ({
-        id: `${i + 1}.${t.index || ti + 1}`,
+        id: `${i + 1}.${t.index ?? (ti + 1)}`,
         name: t.name,
         lifecycle: 'pending',
         level: t.level || 'L1',

package/src/server.js

@@ -247,6 +247,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
 
   return {
     content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
+    ...(result.error ? { isError: true } : {}),
   };
 });
 
@@ -255,6 +256,12 @@ export async function main() {
   await server.connect(transport);
 }
 
+process.on('SIGINT', () => process.exit(0));
+process.on('SIGTERM', () => process.exit(0));
+process.on('unhandledRejection', (err) => {
+  if (process.env.GSD_DEBUG) console.error('[gsd] unhandledRejection', err);
+});
+
 if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
   main().catch(console.error);
 }

package/src/tools/orchestrator.js

@@ -27,7 +27,7 @@ function parseTimestamp(value) {
 }
 
 async function readContextHealth(basePath) {
-  const gsdDir = getGsdDir(basePath);
+  const gsdDir = await getGsdDir(basePath);
   if (!gsdDir) return null;
   try {
     const raw = await readFile(join(gsdDir, '.context-health'), 'utf-8');
@@ -75,7 +75,7 @@ async function detectPlanDrift(basePath, lastSession) {
   const lastSessionTs = parseTimestamp(lastSession);
   if (lastSessionTs === null) return [];
 
-  const gsdDir = getGsdDir(basePath);
+  const gsdDir = await getGsdDir(basePath);
   if (!gsdDir) return [];
 
   const candidates = [join(gsdDir, 'plan.md')];
@@ -106,41 +106,37 @@ async function evaluatePreflight(state, basePath) {
     return { override: null };
   }
 
+  const hints = [];
+
   const currentGitHead = await getGitHead(basePath);
   if (state.git_head && currentGitHead && state.git_head !== currentGitHead) {
-    return {
-      override: {
-        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',
-      },
-    };
+    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) {
-    return {
-      override: {
-        workflow_mode: 'replan_required',
-        action: 'await_manual_intervention',
-        updates: { workflow_mode: 'replan_required' },
-        changed_files,
-        message: 'Plan artifacts changed after the last recorded session',
-      },
-    };
-  }
-
-  if (state.workflow_mode === 'awaiting_user' && state.current_review?.stage === 'direction_drift') {
-    return { override: null };
+    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 driftPhase = getDirectionDriftPhase(state);
-  if (driftPhase) {
-    return {
-      override: {
+  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: {
@@ -155,24 +151,28 @@ async function evaluatePreflight(state, basePath) {
         },
         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) {
-    return {
-      override: {
-        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',
-      },
-    };
+    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',
+    });
   }
 
-  return { override: null };
+  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) {
@@ -503,6 +503,7 @@ export async function resumeWorkflow({ basePath = process.cwd() } = {}) {
       ...(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.hints && preflight.hints.length > 1 ? { pending_issues: preflight.hints.slice(1) } : {}),
     };
   }
 
@@ -700,8 +701,9 @@ export async function handleExecutorResult({ result, basePath = process.cwd() }
       }
     }
 
-    // L0 auto-accept: promote checkpointed → accepted in a second persist
-    if (isL0) {
+    // Auto-accept: L0 tasks or tasks with review_required: false
+    const autoAccept = isL0 || task.review_required === false;
+    if (autoAccept) {
       const acceptError = await persist(basePath, {
         phases: [{
           id: phase.id,
@@ -719,7 +721,7 @@ export async function handleExecutorResult({ result, basePath = process.cwd() }
       task_id: task.id,
       review_level: reviewLevel,
       current_review,
-      auto_accepted: isL0,
+      auto_accepted: autoAccept,
     };
   }
 
@@ -825,6 +827,18 @@ export async function handleDebuggerResult({ result, basePath = process.cwd() }
 
   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';
@@ -832,7 +846,7 @@ export async function handleDebuggerResult({ result, basePath = process.cwd() }
     phasePatch.todo = [{ id: task.id, lifecycle: 'failed', debug_context }];
 
     const persistError = await persist(basePath, {
-      workflow_mode: phaseFailed ? 'failed' : 'executing_task',
+      workflow_mode: effectiveWorkflowMode,
       current_task: null,
       current_review: null,
       phases: [phasePatch],
@@ -842,7 +856,7 @@ export async function handleDebuggerResult({ result, basePath = process.cwd() }
     return {
       success: true,
       action: phaseFailed ? 'phase_failed' : 'task_failed',
-      workflow_mode: phaseFailed ? 'failed' : 'executing_task',
+      workflow_mode: effectiveWorkflowMode,
       phase_id: phase.id,
       task_id: task.id,
     };
@@ -914,6 +928,11 @@ export async function handleReviewerResult({ result, basePath = process.cwd() }
     }
   }
 
+  // Snapshot accepted task IDs before propagation (for done counter adjustment)
+  const acceptedBeforePropagation = new Set(
+    (phase.todo || []).filter(t => t.lifecycle === 'accepted').map(t => t.id),
+  );
+
   // Propagation for critical issues with invalidates_downstream
   for (const issue of (result.critical_issues || [])) {
     if (issue.invalidates_downstream && issue.task_id) {
@@ -925,6 +944,9 @@ export async function handleReviewerResult({ result, basePath = process.cwd() }
   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', evidence_refs: [] });
+      if (acceptedBeforePropagation.has(task.id)) {
+        doneDecrement += 1;
+      }
     }
   }
 
@@ -936,11 +958,18 @@ export async function handleReviewerResult({ result, basePath = process.cwd() }
     done: Math.max(0, (phase.done || 0) + doneIncrement - doneDecrement),
     phase_review: {
       status: reviewStatus,
-      ...(hasCritical ? { retry_count: (phase.phase_review?.retry_count || 0) + 1 } : {}),
+      ...(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 };
   }