@polymorphism-tech/morph-spec 4.10.6 → 4.10.8

package/src/core/state/phase-state-machine.js

@@ -1,217 +1,217 @@
-/**
- * Phase State Machine - Enforces valid phase transitions
- *
- * Prevents invalid workflow jumps and ensures sequential phase progression.
- * Based on the MORPH 5-phase workflow.
- */
-
-/**
- * Valid phase transitions map
- * Each phase can only transition to specific next phases
- */
-const VALID_TRANSITIONS = {
-  'proposal': ['setup'],
-  'setup': ['uiux', 'design'], // Can skip UI/UX if no frontend
-  'uiux': ['design'],
-  'design': ['clarify'],
-  'clarify': ['plan'],
-  'plan': ['tasks'],
-  'tasks': ['implement'],
-  'implement': ['sync', 'archived'], // Can skip sync
-  'sync': ['archived']
-};
-
-/**
- * Phase display names for error messages
- */
-const PHASE_NAMES = {
-  'proposal': 'Proposal (Phase 0)',
-  'setup': 'Setup (Phase 1)',
-  'uiux': 'UI/UX Design (Phase 1.5)',
-  'design': 'Design (Phase 2)',
-  'clarify': 'Clarify (Phase 3)',
-  'plan': 'Plan (Phase 4)',
-  'tasks': 'Tasks (Phase 5)',
-  'implement': 'Implement (Phase 6)',
-  'sync': 'Sync (Phase 7)',
-  'archived': 'Archived'
-};
-
-/**
- * Optional phases that can be skipped
- */
-const OPTIONAL_PHASES = ['uiux', 'sync'];
-
-/**
- * Validate if a phase transition is allowed
- * @param {string} fromPhase - Current phase
- * @param {string} toPhase - Target phase
- * @returns {boolean} True if transition is valid
- */
-export function isValidTransition(fromPhase, toPhase) {
-  if (!fromPhase || !toPhase) {
-    return false;
-  }
-
-  const validNextPhases = VALID_TRANSITIONS[fromPhase];
-  return validNextPhases ? validNextPhases.includes(toPhase) : false;
-}
-
-/**
- * Get list of valid next phases for a given phase
- * @param {string} currentPhase - Current phase
- * @returns {string[]} Array of valid next phase names
- */
-export function getValidNextPhases(currentPhase) {
-  return VALID_TRANSITIONS[currentPhase] || [];
-}
-
-/**
- * Get display name for a phase
- * @param {string} phase - Phase identifier
- * @returns {string} Human-readable phase name
- */
-export function getPhaseDisplayName(phase) {
-  return PHASE_NAMES[phase] || phase;
-}
-
-/**
- * Check if a phase is optional
- * @param {string} phase - Phase identifier
- * @returns {boolean} True if phase is optional
- */
-export function isOptionalPhase(phase) {
-  return OPTIONAL_PHASES.includes(phase);
-}
-
-/**
- * Validate transition and throw error if invalid
- * @param {string} fromPhase - Current phase
- * @param {string} toPhase - Target phase
- * @throws {Error} If transition is invalid
- */
-export function validateTransition(fromPhase, toPhase) {
-  if (!fromPhase) {
-    throw new Error('Current phase is undefined. Cannot validate transition.');
-  }
-
-  if (!toPhase) {
-    throw new Error('Target phase is undefined. Cannot validate transition.');
-  }
-
-  if (!isValidTransition(fromPhase, toPhase)) {
-    const validPhases = getValidNextPhases(fromPhase);
-    const fromDisplay = getPhaseDisplayName(fromPhase);
-    const toDisplay = getPhaseDisplayName(toPhase);
-
-    throw new Error(
-      `Invalid phase transition: ${fromDisplay} → ${toDisplay}\n\n` +
-      `Valid next phases from ${fromDisplay}:\n` +
-      validPhases.map(p => `  • ${getPhaseDisplayName(p)}`).join('\n') +
-      '\n\n' +
-      'You cannot skip phases in the MORPH workflow.\n' +
-      'To override this check, use the --force flag (not recommended).'
-    );
-  }
-}
-
-/**
- * Get the sequential order of phases
- * @returns {string[]} Ordered list of phases
- */
-export function getPhaseSequence() {
-  return [
-    'proposal',
-    'setup',
-    'uiux',     // optional
-    'design',
-    'clarify',
-    'plan',
-    'tasks',
-    'implement',
-    'sync',     // optional
-    'archived'
-  ];
-}
-
-/**
- * Get phase order index (for comparison)
- * @param {string} phase - Phase identifier
- * @returns {number} Index in sequence (-1 if not found)
- */
-export function getPhaseOrder(phase) {
-  return getPhaseSequence().indexOf(phase);
-}
-
-/**
- * Check if target phase is ahead of current phase
- * @param {string} currentPhase - Current phase
- * @param {string} targetPhase - Target phase
- * @returns {boolean} True if target is ahead
- */
-export function isPhaseAhead(currentPhase, targetPhase) {
-  return getPhaseOrder(targetPhase) > getPhaseOrder(currentPhase);
-}
-
-/**
- * Check if target phase is behind current phase (rollback scenario)
- * @param {string} currentPhase - Current phase
- * @param {string} targetPhase - Target phase
- * @returns {boolean} True if target is behind
- */
-export function isPhaseRollback(currentPhase, targetPhase) {
-  return getPhaseOrder(targetPhase) < getPhaseOrder(currentPhase);
-}
-
-/**
- * Get all skipped phases between two phases
- * @param {string} fromPhase - Starting phase
- * @param {string} toPhase - Ending phase
- * @returns {string[]} Array of skipped phases
- */
-export function getSkippedPhases(fromPhase, toPhase) {
-  const sequence = getPhaseSequence();
-  const fromIndex = sequence.indexOf(fromPhase);
-  const toIndex = sequence.indexOf(toPhase);
-
-  if (fromIndex === -1 || toIndex === -1 || toIndex <= fromIndex) {
-    return [];
-  }
-
-  return sequence.slice(fromIndex + 1, toIndex);
-}
-
-/**
- * Validate that no required phases were skipped
- * @param {string} fromPhase - Starting phase
- * @param {string} toPhase - Ending phase
- * @throws {Error} If required phases were skipped
- */
-export function validateNoRequiredPhasesSkipped(fromPhase, toPhase) {
-  const skipped = getSkippedPhases(fromPhase, toPhase);
-  const requiredSkipped = skipped.filter(p => !isOptionalPhase(p));
-
-  if (requiredSkipped.length > 0) {
-    throw new Error(
-      `Cannot skip required phases:\n` +
-      requiredSkipped.map(p => `  • ${getPhaseDisplayName(p)}`).join('\n') +
-      '\n\nYou must complete each required phase in sequence.'
-    );
-  }
-}
-
-/**
- * Get comprehensive phase information
- * @param {string} phase - Phase identifier
- * @returns {Object} Phase metadata
- */
-export function getPhaseInfo(phase) {
-  return {
-    id: phase,
-    displayName: getPhaseDisplayName(phase),
-    order: getPhaseOrder(phase),
-    isOptional: isOptionalPhase(phase),
-    validNextPhases: getValidNextPhases(phase),
-    canTransitionTo: (targetPhase) => isValidTransition(phase, targetPhase)
-  };
-}
+/**
+ * Phase State Machine - Enforces valid phase transitions
+ *
+ * Prevents invalid workflow jumps and ensures sequential phase progression.
+ * Based on the MORPH 5-phase workflow.
+ */
+
+/**
+ * Valid phase transitions map
+ * Each phase can only transition to specific next phases
+ */
+const VALID_TRANSITIONS = {
+  'proposal': ['setup'],
+  'setup': ['uiux', 'design'], // Can skip UI/UX if no frontend
+  'uiux': ['design'],
+  'design': ['clarify'],
+  'clarify': ['plan'],
+  'plan': ['tasks'],
+  'tasks': ['implement'],
+  'implement': ['sync', 'archived'], // Can skip sync
+  'sync': ['archived']
+};
+
+/**
+ * Phase display names for error messages
+ */
+const PHASE_NAMES = {
+  'proposal': 'Proposal (Phase 0)',
+  'setup': 'Setup (Phase 1)',
+  'uiux': 'UI/UX Design (Phase 1.5)',
+  'design': 'Design (Phase 2)',
+  'clarify': 'Clarify (Phase 3)',
+  'plan': 'Plan (Phase 4)',
+  'tasks': 'Tasks (Phase 5)',
+  'implement': 'Implement (Phase 6)',
+  'sync': 'Sync (Phase 7)',
+  'archived': 'Archived'
+};
+
+/**
+ * Optional phases that can be skipped
+ */
+const OPTIONAL_PHASES = ['uiux', 'sync'];
+
+/**
+ * Validate if a phase transition is allowed
+ * @param {string} fromPhase - Current phase
+ * @param {string} toPhase - Target phase
+ * @returns {boolean} True if transition is valid
+ */
+export function isValidTransition(fromPhase, toPhase) {
+  if (!fromPhase || !toPhase) {
+    return false;
+  }
+
+  const validNextPhases = VALID_TRANSITIONS[fromPhase];
+  return validNextPhases ? validNextPhases.includes(toPhase) : false;
+}
+
+/**
+ * Get list of valid next phases for a given phase
+ * @param {string} currentPhase - Current phase
+ * @returns {string[]} Array of valid next phase names
+ */
+export function getValidNextPhases(currentPhase) {
+  return VALID_TRANSITIONS[currentPhase] || [];
+}
+
+/**
+ * Get display name for a phase
+ * @param {string} phase - Phase identifier
+ * @returns {string} Human-readable phase name
+ */
+export function getPhaseDisplayName(phase) {
+  return PHASE_NAMES[phase] || phase;
+}
+
+/**
+ * Check if a phase is optional
+ * @param {string} phase - Phase identifier
+ * @returns {boolean} True if phase is optional
+ */
+export function isOptionalPhase(phase) {
+  return OPTIONAL_PHASES.includes(phase);
+}
+
+/**
+ * Validate transition and throw error if invalid
+ * @param {string} fromPhase - Current phase
+ * @param {string} toPhase - Target phase
+ * @throws {Error} If transition is invalid
+ */
+export function validateTransition(fromPhase, toPhase) {
+  if (!fromPhase) {
+    throw new Error('Current phase is undefined. Cannot validate transition.');
+  }
+
+  if (!toPhase) {
+    throw new Error('Target phase is undefined. Cannot validate transition.');
+  }
+
+  if (!isValidTransition(fromPhase, toPhase)) {
+    const validPhases = getValidNextPhases(fromPhase);
+    const fromDisplay = getPhaseDisplayName(fromPhase);
+    const toDisplay = getPhaseDisplayName(toPhase);
+
+    throw new Error(
+      `Invalid phase transition: ${fromDisplay} → ${toDisplay}\n\n` +
+      `Valid next phases from ${fromDisplay}:\n` +
+      validPhases.map(p => `  • ${getPhaseDisplayName(p)}`).join('\n') +
+      '\n\n' +
+      'You cannot skip phases in the MORPH workflow.\n' +
+      'To override this check, use the --force flag (not recommended).'
+    );
+  }
+}
+
+/**
+ * Get the sequential order of phases
+ * @returns {string[]} Ordered list of phases
+ */
+export function getPhaseSequence() {
+  return [
+    'proposal',
+    'setup',
+    'uiux',     // optional
+    'design',
+    'clarify',
+    'plan',
+    'tasks',
+    'implement',
+    'sync',     // optional
+    'archived'
+  ];
+}
+
+/**
+ * Get phase order index (for comparison)
+ * @param {string} phase - Phase identifier
+ * @returns {number} Index in sequence (-1 if not found)
+ */
+export function getPhaseOrder(phase) {
+  return getPhaseSequence().indexOf(phase);
+}
+
+/**
+ * Check if target phase is ahead of current phase
+ * @param {string} currentPhase - Current phase
+ * @param {string} targetPhase - Target phase
+ * @returns {boolean} True if target is ahead
+ */
+export function isPhaseAhead(currentPhase, targetPhase) {
+  return getPhaseOrder(targetPhase) > getPhaseOrder(currentPhase);
+}
+
+/**
+ * Check if target phase is behind current phase (rollback scenario)
+ * @param {string} currentPhase - Current phase
+ * @param {string} targetPhase - Target phase
+ * @returns {boolean} True if target is behind
+ */
+export function isPhaseRollback(currentPhase, targetPhase) {
+  return getPhaseOrder(targetPhase) < getPhaseOrder(currentPhase);
+}
+
+/**
+ * Get all skipped phases between two phases
+ * @param {string} fromPhase - Starting phase
+ * @param {string} toPhase - Ending phase
+ * @returns {string[]} Array of skipped phases
+ */
+export function getSkippedPhases(fromPhase, toPhase) {
+  const sequence = getPhaseSequence();
+  const fromIndex = sequence.indexOf(fromPhase);
+  const toIndex = sequence.indexOf(toPhase);
+
+  if (fromIndex === -1 || toIndex === -1 || toIndex <= fromIndex) {
+    return [];
+  }
+
+  return sequence.slice(fromIndex + 1, toIndex);
+}
+
+/**
+ * Validate that no required phases were skipped
+ * @param {string} fromPhase - Starting phase
+ * @param {string} toPhase - Ending phase
+ * @throws {Error} If required phases were skipped
+ */
+export function validateNoRequiredPhasesSkipped(fromPhase, toPhase) {
+  const skipped = getSkippedPhases(fromPhase, toPhase);
+  const requiredSkipped = skipped.filter(p => !isOptionalPhase(p));
+
+  if (requiredSkipped.length > 0) {
+    throw new Error(
+      `Cannot skip required phases:\n` +
+      requiredSkipped.map(p => `  • ${getPhaseDisplayName(p)}`).join('\n') +
+      '\n\nYou must complete each required phase in sequence.'
+    );
+  }
+}
+
+/**
+ * Get comprehensive phase information
+ * @param {string} phase - Phase identifier
+ * @returns {Object} Phase metadata
+ */
+export function getPhaseInfo(phase) {
+  return {
+    id: phase,
+    displayName: getPhaseDisplayName(phase),
+    order: getPhaseOrder(phase),
+    isOptional: isOptionalPhase(phase),
+    validNextPhases: getValidNextPhases(phase),
+    canTransitionTo: (targetPhase) => isValidTransition(phase, targetPhase)
+  };
+}

package/src/core/state/state-manager.js

@@ -279,6 +279,7 @@ async function ensureFeature(featureName, options = {}) {
         pending: 0
       },
       checkpoints: [],
+      dispatchLog: [],
       trustConfig: {},
       contextBundles: [],
       fileChanges: []
@@ -420,6 +421,29 @@ export function removeAgent(featureName, agentId) {
   return false;
 }
 
+/**
+ * Log a dispatch event to state.json.
+ * Appends entry to feature.dispatchLog, capped at 50 entries (oldest trimmed).
+ *
+ * @param {string} featureName - Feature name
+ * @param {{ timestamp: string, phase: string, mode: string, agents: Array<{ id: string, subagentType: string, group: string, tasks: string[] }> }} entry - Dispatch event to log
+ */
+export function logDispatch(featureName, entry) {
+  const state = loadState();
+  const feature = state.features?.[featureName];
+  if (!feature) return;
+
+  if (!Array.isArray(feature.dispatchLog)) feature.dispatchLog = [];
+  feature.dispatchLog.push(entry);
+
+  // Cap at 50 entries
+  if (feature.dispatchLog.length > 50) {
+    feature.dispatchLog = feature.dispatchLog.slice(-50);
+  }
+
+  saveState(state);
+}
+
 /**
  * Normalize output type from kebab-case to camelCase (BUG-002 fix - Enhanced)
  * Supports both kebab-case and camelCase input formats for all output types
@@ -807,3 +831,60 @@ export function getApprovalHistory(featureName) {
   // Sort by timestamp
   return history.sort((a, b) => new Date(a.timestamp) - new Date(b.timestamp));
 }
+
+/**
+ * Find which agent was assigned a specific task in the latest dispatch.
+ * Searches only the last dispatchLog entry.
+ *
+ * @param {string} featureName
+ * @param {string} taskId
+ * @returns {string|null} Agent ID or null if not found
+ */
+export function resolveAgentForTask(featureName, taskId) {
+  const state = loadState();
+  const feature = state.features?.[featureName];
+  if (!feature) return null;
+
+  const log = feature.dispatchLog;
+  if (!Array.isArray(log) || log.length === 0) return null;
+
+  const latest = log[log.length - 1];
+  for (const agent of latest.agents || []) {
+    if (Array.isArray(agent.tasks) && agent.tasks.includes(taskId)) {
+      return agent.id;
+    }
+  }
+  return null;
+}
+
+/**
+ * Update timing fields on a specific agent in the latest dispatch entry.
+ * Fail-open: returns silently if feature/dispatch/agent not found.
+ *
+ * @param {string} featureName
+ * @param {string} agentId - Agent ID to update
+ * @param {Object} updates - Fields to merge (startedAt, completedAt, tasksCompleted)
+ */
+export function updateDispatchAgentTiming(featureName, agentId, updates) {
+  const state = loadState();
+  const feature = state.features?.[featureName];
+  if (!feature) return;
+
+  const log = feature.dispatchLog;
+  if (!Array.isArray(log) || log.length === 0) return;
+
+  const latest = log[log.length - 1];
+  const agent = (latest.agents || []).find(a => a.id === agentId);
+  if (!agent) return;
+
+  Object.assign(agent, updates);
+
+  // If all agents now have completedAt, set entry.completedAt to the latest
+  const allComplete = (latest.agents || []).every(a => a.completedAt);
+  if (allComplete && latest.agents.length > 0) {
+    const timestamps = latest.agents.map(a => new Date(a.completedAt).getTime());
+    latest.completedAt = new Date(Math.max(...timestamps)).toISOString();
+  }
+
+  saveState(state);
+}