@polymorphism-tech/morph-spec 4.11.1 → 4.13.0

package/src/core/paths/output-schema.js

@@ -17,26 +17,25 @@ import { join } from 'path';
  *
  * Fields:
  *   filename     - The file's basename (e.g. 'spec.md')
- *   phaseDir     - Subdirectory within .morph/features/{feature}/ (e.g. '1-design')
+ *   phaseDir     - Subdirectory within .morph/features/{feature}/ (e.g. '2-design')
  *   phase        - The morph-spec phase that produces this output
  *   protected    - Whether the file requires an approval gate before editing
  *   approvalGate - (optional) Which gate protects this file
  */
 export const OUTPUT_SCHEMA = {
   proposal:      { filename: 'proposal.md',        phaseDir: '0-proposal',  phase: 'proposal',  protected: false },
-  schemaAnalysis:{ filename: 'schema-analysis.md', phaseDir: '1-design',    phase: 'design',    protected: true,  approvalGate: 'design' },
-  spec:          { filename: 'spec.md',             phaseDir: '1-design',    phase: 'design',    protected: true,  approvalGate: 'design' },
-  clarifications:{ filename: 'clarifications.md',  phaseDir: '1-design',    phase: 'clarify',   protected: false },
-  contracts:     { filename: 'contracts.cs',        phaseDir: '1-design',    phase: 'design',    protected: true,  approvalGate: 'design' },
-  contractsTs:   { filename: 'contracts.ts',        phaseDir: '1-design',    phase: 'design',    protected: true,  approvalGate: 'design' },
-  contractsVsa:  { filename: 'contracts-vsa.cs',    phaseDir: '1-design',    phase: 'design',    protected: true,  approvalGate: 'design' },
+  schemaAnalysis:{ filename: 'schema-analysis.md', phaseDir: '2-design',    phase: 'design',    protected: true,  approvalGate: 'design' },
+  spec:          { filename: 'spec.md',             phaseDir: '2-design',    phase: 'design',    protected: true,  approvalGate: 'design' },
+  contracts:     { filename: 'contracts.cs',        phaseDir: '2-design',    phase: 'design',    protected: true,  approvalGate: 'design' },
+  contractsTs:   { filename: 'contracts.ts',        phaseDir: '2-design',    phase: 'design',    protected: true,  approvalGate: 'design' },
+  contractsVsa:  { filename: 'contracts-vsa.cs',    phaseDir: '2-design',    phase: 'design',    protected: true,  approvalGate: 'design' },
   plan:          { filename: 'plan.md',             phaseDir: '3-plan',      phase: 'plan',      protected: true,  approvalGate: 'plan' },
   tasks:         { filename: 'tasks.md',            phaseDir: '4-tasks',     phase: 'tasks',     protected: true,  approvalGate: 'tasks' },
-  uiDesignSystem:{ filename: 'design-system.md',   phaseDir: '2-ui',        phase: 'uiux',      protected: true,  approvalGate: 'uiux' },
-  uiMockups:     { filename: 'mockups.md',          phaseDir: '2-ui',        phase: 'uiux',      protected: true,  approvalGate: 'uiux' },
-  uiComponents:  { filename: 'components.md',       phaseDir: '2-ui',        phase: 'uiux',      protected: true,  approvalGate: 'uiux' },
-  uiFlows:       { filename: 'flows.md',            phaseDir: '2-ui',        phase: 'uiux',      protected: true,  approvalGate: 'uiux' },
-  decisions:     { filename: 'decisions.md',        phaseDir: '1-design',    phase: 'design',    protected: false },
+  uiDesignSystem:{ filename: 'design-system.md',   phaseDir: '1-ui',        phase: 'uiux',      protected: true,  approvalGate: 'uiux' },
+  uiMockups:     { filename: 'mockups.md',          phaseDir: '1-ui',        phase: 'uiux',      protected: true,  approvalGate: 'uiux' },
+  uiComponents:  { filename: 'components.md',       phaseDir: '1-ui',        phase: 'uiux',      protected: true,  approvalGate: 'uiux' },
+  uiFlows:       { filename: 'flows.md',            phaseDir: '1-ui',        phase: 'uiux',      protected: true,  approvalGate: 'uiux' },
+  decisions:     { filename: 'decisions.md',        phaseDir: '2-design',    phase: 'design',    protected: false },
   recap:         { filename: 'recap.md',            phaseDir: '5-implement', phase: 'implement', protected: false },
 };
 
@@ -50,7 +49,7 @@ export const OUTPUT_SCHEMA = {
  *
  * @param {string} featureName - The feature name
  * @param {string} outputType  - camelCase output type key from OUTPUT_SCHEMA
- * @returns {string} e.g. ".morph/features/my-feature/1-design/spec.md"
+ * @returns {string} e.g. ".morph/features/my-feature/2-design/spec.md"
  */
 export function getOutputPath(featureName, outputType) {
   const entry = OUTPUT_SCHEMA[outputType];

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

@@ -1,217 +1,211 @@
-/**
- * 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': ['uiux', 'design'], // Can skip UI/UX if no frontend
+  'uiux': ['design'],
+  'design': ['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)',
+  'uiux': 'UI/UX Design (Phase 1)',
+  'design': 'Design (Phase 2)',
+  'plan': 'Plan (Phase 3)',
+  'tasks': 'Tasks (Phase 4)',
+  'implement': 'Implement (Phase 5)',
+  'sync': 'Sync (Phase 6)',
+  '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',
+    'uiux',     // optional
+    'design',
+    '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

@@ -27,21 +27,21 @@ export function getStatePath() {
  * Returns the phase corresponding to the highest-numbered folder present.
  *
  * @param {string} featurePath - Absolute path to .morph/features/{feature}/
- * @returns {string} Phase name: 'implement' | 'tasks' | 'plan' | 'uiux' | 'design' | 'proposal' | 'setup'
+ * @returns {string} Phase name: 'implement' | 'tasks' | 'plan' | 'uiux' | 'design' | 'proposal'
  */
 export function derivePhase(featurePath) {
   const phaseMap = [
     ['5-implement', 'implement'],
     ['4-tasks', 'tasks'],
     ['3-plan', 'plan'],
-    ['2-ui', 'uiux'],
-    ['1-design', 'design'],
+    ['2-design', 'design'],
+    ['1-ui', 'uiux'],
     ['0-proposal', 'proposal'],
   ];
   for (const [folder, phase] of phaseMap) {
     if (existsSync(join(featurePath, folder))) return phase;
   }
-  return 'setup';
+  return 'proposal';
 }
 
 /**
@@ -168,11 +168,11 @@ export function saveState(state) {
  * @param {Object} options - Options
  * @param {boolean} options.force - Overwrite existing file
  * @param {string} options.projectName - Project name
- * @param {string} options.projectType - Project type (e.g., 'blazor-server')
+ * @param {string} options.projectType - Project type (e.g., 'dotnet-nextjs')
  * @returns {Object} Initial state
  */
 export function initState(options = {}) {
-  const { force = false, projectName = '{PROJECT_NAME}', projectType = 'blazor-server' } = options;
+  const { force = false, projectName = '{PROJECT_NAME}', projectType = 'dotnet-nextjs' } = options;
 
   if (stateExists() && !force) {
     throw new Error('State file already exists. Use force=true to overwrite.');
@@ -362,7 +362,7 @@ export async function addCheckpoint(featureName, note) {
     passed: true,
     checkpointNum: feature.checkpoints.length + 1,
     timestamp: new Date().toISOString(),
-    phase: feature.phase || 'setup',
+    phase: feature.phase || 'proposal',
     results: [],
     summary: {
       note: note,
@@ -617,7 +617,7 @@ export async function trackFileChange(featureName, filePath, action, phase) {
   state.features[featureName].fileChanges.push({
     path: filePath,
     action,
-    phase: phase || state.features[featureName].phase || 'setup',
+    phase: phase || state.features[featureName].phase || 'proposal',
     timestamp: new Date().toISOString()
   });
 
@@ -783,7 +783,7 @@ export function isPendingApproval(featureName) {
     return false;
   }
 
-  const currentPhase = feature.phase || 'setup';
+  const currentPhase = feature.phase || 'proposal';
 
   // Check if current phase has an approval gate
   const phaseGateMap = {

package/src/lib/agents/agents-manager.js

@@ -16,8 +16,8 @@ import { dirname } from 'node:path';
 
 /** Known valid phases for active_phases validation */
 export const KNOWN_PHASES = [
-  'proposal', 'setup', 'uiux', 'design',
-  'clarify', 'plan', 'tasks', 'implement',
+  'proposal', 'uiux', 'design',
+  'plan', 'tasks', 'implement', 'sync',
 ];
 
 /** Tier labels for display and validation */

package/src/lib/agents/output-collector.js

@@ -19,7 +19,6 @@ export const SOURCE_WEIGHTS = {
   contracts:      1.0,
   contractsTs:    1.0,
   contractsVsa:   1.0,
-  clarifications: 1.0,
   decisions:      1.0,
   plan:           1.2,
   tasks:          1.3,
@@ -31,7 +30,7 @@ export const SOURCE_WEIGHTS = {
 };
 
 /** Phase order for sorting collected outputs */
-const PHASE_ORDER = ['proposal', 'uiux', 'design', 'clarify', 'plan', 'tasks', 'implement'];
+const PHASE_ORDER = ['proposal', 'uiux', 'design', 'plan', 'tasks', 'implement'];
 
 /**
  * Collect all existing phase output files for a feature.

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

@@ -64,7 +64,7 @@ export function detectDesignSystem(projectPath, featureName = null) {
       projectPath,
       '.morph/features',
       featureName,
-      '2-ui',
+      '1-ui',
       'design-system.md'
     );
 
@@ -179,7 +179,7 @@ export function hasUIAgentsActive(projectPath, featureName) {
     }
 
     // UI design agents that require a design system before implement phase.
-    // Implementation-only agents (blazor-builder, nextjs-expert, css-specialist)
+    // Implementation-only agents (nextjs-expert, css-specialist)
     // build from existing designs and do NOT trigger this gate.
     const uiAgents = [
       'ui-designer',
@@ -208,10 +208,10 @@ export function getRecommendedLocations(projectPath) {
       projectType = config.project?.type || 'unknown';
     }
 
-    // Default locations (Blazor)
+    // Default locations
     const locations = {
       markdown: '.morph/context/design-system.md',
-      css: 'wwwroot/css/design-system.css',
+      css: 'public/design-system.css',
       description: 'Project-level design system (shared across features)'
     };