@polymorphism-tech/morph-spec 4.10.8 → 4.10.10

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/lib/agents/metrics-aggregator.js

@@ -0,0 +1,56 @@
+/**
+ * Project-level metrics aggregator
+ *
+ * Aggregates feature-level data from state.json into a project-wide
+ * metrics summary. Pure computation — no I/O.
+ */
+
+/**
+ * Aggregate project-level metrics from state.json data.
+ *
+ * @param {Object} state - Parsed state.json content
+ * @returns {Object} Aggregated metrics
+ */
+export function aggregateProjectMetrics(state) {
+  const features = state?.features || {};
+  const featureNames = Object.keys(features);
+
+  const featureMetrics = featureNames.map(name => {
+    const f = features[name];
+    const tasks = f.tasks || {};
+    const taskIds = Object.keys(tasks);
+    const completedTasks = taskIds.filter(id => tasks[id]?.status === 'completed').length;
+    const dispatchLog = f.dispatchLog || [];
+
+    return {
+      name,
+      phase: f.phase || f.currentPhase || 'unknown',
+      taskCount: taskIds.length,
+      completedTasks,
+      dispatchCount: dispatchLog.length,
+    };
+  });
+
+  const totalFeatures = featureMetrics.length;
+  const completedFeatures = featureMetrics.filter(f => f.phase === 'archived' || f.phase === 'done').length;
+  const totalTasks = featureMetrics.reduce((sum, f) => sum + f.taskCount, 0);
+  const completedTasks = featureMetrics.reduce((sum, f) => sum + f.completedTasks, 0);
+  const totalDispatches = featureMetrics.reduce((sum, f) => sum + f.dispatchCount, 0);
+  const completionRate = totalTasks > 0 ? Math.round((completedTasks / totalTasks) * 100) : 0;
+  const avgTasksPerFeature = totalFeatures > 0 ? Math.round((totalTasks / totalFeatures) * 10) / 10 : 0;
+
+  return {
+    version: state?.version || 'unknown',
+    updatedAt: new Date().toISOString(),
+    summary: {
+      totalFeatures,
+      completedFeatures,
+      avgTasksPerFeature,
+      totalTasks,
+      completedTasks,
+      completionRate,
+      totalDispatches,
+    },
+    features: featureMetrics,
+  };
+}

package/src/lib/detectors/design-system-detector.js

@@ -7,9 +7,42 @@
  * @module design-system-detector
  */
 
-import { existsSync, readFileSync } from 'fs';
+import { existsSync, readFileSync, readdirSync } from 'fs';
 import { join } from 'path';
 
+const SKIP_DIRS = new Set(['node_modules', '.git', '.morph', 'dist', 'build', '.next', 'obj', 'bin', '.vs']);
+const CSS_SCAN_MAX_DEPTH = 6;
+
+/**
+ * Recursively walk a directory collecting files with given extensions.
+ * @param {string} dir - Directory to walk
+ * @param {string[]} extensions - File extensions to collect (e.g. ['.css', '.scss'])
+ * @param {string[]} files - Accumulator array (mutated in-place)
+ * @param {number} depth - Current recursion depth
+ * @param {number} maxDepth - Maximum recursion depth
+ */
+function walkDirForCss(dir, extensions, files, depth, maxDepth) {
+  if (depth > maxDepth) return;
+  let entries;
+  try {
+    entries = readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return;
+  }
+  for (const entry of entries) {
+    if (entry.isDirectory()) {
+      if (!SKIP_DIRS.has(entry.name)) {
+        walkDirForCss(join(dir, entry.name), extensions, files, depth + 1, maxDepth);
+      }
+    } else if (entry.isFile()) {
+      const lower = entry.name.toLowerCase();
+      if (extensions.some(ext => lower.endsWith(ext))) {
+        files.push(join(dir, entry.name));
+      }
+    }
+  }
+}
+
 /**
  * Detect design system for project or feature
  * @param {string} projectPath - Root path of the project
@@ -70,37 +103,46 @@ export function detectDesignSystem(projectPath, featureName = null) {
     };
   }
 
-  // Priority 4: Check common CSS locations for design system variables
-  const commonCssLocations = [
-    'wwwroot/css/site.css',
-    'wwwroot/css/app.css',
-    'styles/globals.css',
-    'src/styles/globals.css'
-  ];
-
-  for (const cssPath of commonCssLocations) {
-    const fullPath = join(projectPath, cssPath);
-    if (existsSync(fullPath)) {
-      // Check if file contains design system variables (CSS custom properties)
-      try {
-        const content = readFileSync(fullPath, 'utf8');
-
-        // Look for CSS custom properties that indicate a design system
-        // Match :root { ... --variable ... } (with newlines)
-        const hasDesignTokens = /:root\s*\{[\s\S]*?--/.test(content);
-
-        if (hasDesignTokens) {
-          return {
-            hasDesignSystem: true,
-            path: fullPath,
-            isProjectLevel: true,
-            isFeatureLevel: false,
-            source: 'existing-css-variables'
-          };
-        }
-      } catch {
-        // Continue checking other locations
+  // Priority 4: Recursively scan frontend root directories for CSS/SCSS with design tokens
+  const frontendRoots = ['wwwroot', 'styles', 'src/styles', 'src', 'public'];
+  const extensions = ['.css', '.scss'];
+  const collected = [];
+
+  for (const root of frontendRoots) {
+    const rootPath = join(projectPath, root);
+    if (existsSync(rootPath)) {
+      walkDirForCss(rootPath, extensions, collected, 0, CSS_SCAN_MAX_DEPTH);
+    }
+  }
+
+  // Deduplicate by resolved path
+  const seen = new Set();
+  const cssFiles = [];
+  for (const file of collected) {
+    if (!seen.has(file)) {
+      seen.add(file);
+      cssFiles.push(file);
+    }
+  }
+
+  // Sort for deterministic first-match across platforms
+  cssFiles.sort();
+
+  for (const cssFile of cssFiles) {
+    try {
+      const content = readFileSync(cssFile, 'utf8');
+      const hasDesignTokens = /:root\s*\{[\s\S]*?--/.test(content);
+      if (hasDesignTokens) {
+        return {
+          hasDesignSystem: true,
+          path: cssFile,
+          isProjectLevel: true,
+          isFeatureLevel: false,
+          source: 'existing-css-variables'
+        };
       }
+    } catch {
+      // Continue checking other files
     }
   }