@polymorphism-tech/morph-spec 3.0.1 → 3.2.0

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

@@ -0,0 +1,214 @@
+/**
+ * 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': ['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)',
+  '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',
+    'setup',
+    'uiux',     // optional
+    'design',
+    'clarify',
+    '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/stack-resolver.js

@@ -0,0 +1,148 @@
+/**
+ * Stack Resolver - Centralized stack path resolution for multi-stack support.
+ *
+ * Detects the active stack and resolves all stack-relative paths.
+ * Resolution order: explicit > config.json > state.json > auto-detect > fallback
+ *
+ * @module stack-resolver
+ */
+
+import { readFileSync, existsSync, readdirSync } from 'fs';
+import { join } from 'path';
+
+const STACK_TYPE_TO_DIR = {
+  'blazor-server': 'blazor-azure',
+  'blazor-azure': 'blazor-azure',
+  'nextjs-supabase': 'nextjs-supabase',
+};
+
+// Module-level override set by CLI --stack flag via setGlobalStack()
+let _globalStackOverride = null;
+
+/**
+ * Set a global stack override (called by CLI --stack flag).
+ * Once set, all resolveStackId() calls use this value unless
+ * an explicit parameter is provided.
+ * @param {string} stackId - Stack identifier
+ */
+export function setGlobalStack(stackId) {
+  _globalStackOverride = stackId;
+}
+
+/**
+ * Detect which stack directory to use.
+ *
+ * Resolution order:
+ *   1. explicitStack parameter (from CLI --stack flag)
+ *   2. .morph/config/config.json → project.type
+ *   3. .morph/state.json → project.type
+ *   4. Auto-detect: scan stacks/ for existing directories
+ *   5. Fallback: 'blazor-azure'
+ *
+ * @param {string} projectPath - Absolute path to project root
+ * @param {string} [explicitStack] - Override from CLI --stack flag
+ * @returns {string} Stack directory name (e.g., 'blazor-azure', 'nextjs-supabase')
+ */
+export function resolveStackId(projectPath, explicitStack) {
+  // 1. Explicit parameter override
+  if (explicitStack) {
+    return STACK_TYPE_TO_DIR[explicitStack] || explicitStack;
+  }
+
+  // 1b. Global CLI --stack override
+  if (_globalStackOverride) {
+    return STACK_TYPE_TO_DIR[_globalStackOverride] || _globalStackOverride;
+  }
+
+  // 2. config.json → project.type
+  try {
+    const configPath = join(projectPath, '.morph/config/config.json');
+    if (existsSync(configPath)) {
+      const config = JSON.parse(readFileSync(configPath, 'utf8'));
+      const projectType = config?.project?.type;
+      if (projectType && STACK_TYPE_TO_DIR[projectType]) {
+        return STACK_TYPE_TO_DIR[projectType];
+      }
+    }
+  } catch { /* continue to next source */ }
+
+  // 3. state.json → project.type
+  try {
+    const statePath = join(projectPath, '.morph/state.json');
+    if (existsSync(statePath)) {
+      const state = JSON.parse(readFileSync(statePath, 'utf8'));
+      const projectType = state?.project?.type;
+      if (projectType && STACK_TYPE_TO_DIR[projectType]) {
+        return STACK_TYPE_TO_DIR[projectType];
+      }
+    }
+  } catch { /* continue to next source */ }
+
+  // 4. Auto-detect: first directory in stacks/
+  try {
+    const stacksDir = join(projectPath, 'stacks');
+    if (existsSync(stacksDir)) {
+      const dirs = readdirSync(stacksDir, { withFileTypes: true })
+        .filter(d => d.isDirectory())
+        .map(d => d.name);
+      if (dirs.length === 1) {
+        return dirs[0];
+      }
+    }
+  } catch { /* continue to fallback */ }
+
+  // 5. Fallback
+  return 'blazor-azure';
+}
+
+/**
+ * Get absolute path to the active stack's root directory.
+ * @param {string} projectPath
+ * @param {string} [explicitStack]
+ * @returns {string}
+ */
+export function resolveStackPath(projectPath, explicitStack) {
+  return join(projectPath, 'stacks', resolveStackId(projectPath, explicitStack));
+}
+
+/**
+ * Get absolute path to the active stack's agents.json.
+ * @param {string} projectPath
+ * @param {string} [explicitStack]
+ * @returns {string}
+ */
+export function resolveAgentsConfigPath(projectPath, explicitStack) {
+  return join(resolveStackPath(projectPath, explicitStack), '.morph/config/agents.json');
+}
+
+/**
+ * Get absolute path to the active stack's standards directory.
+ * @param {string} projectPath
+ * @param {string} [explicitStack]
+ * @returns {string}
+ */
+export function resolveStandardsDir(projectPath, explicitStack) {
+  return join(resolveStackPath(projectPath, explicitStack), '.morph/standards');
+}
+
+/**
+ * Get absolute path to the active stack's templates directory.
+ * @param {string} projectPath
+ * @param {string} [explicitStack]
+ * @returns {string}
+ */
+export function resolveTemplatesDir(projectPath, explicitStack) {
+  return join(resolveStackPath(projectPath, explicitStack), '.morph/templates');
+}
+
+/**
+ * Get absolute path to the active stack's config directory.
+ * @param {string} projectPath
+ * @param {string} [explicitStack]
+ * @returns {string}
+ */
+export function resolveConfigDir(projectPath, explicitStack) {
+  return join(resolveStackPath(projectPath, explicitStack), '.morph/config');
+}
+
+export { STACK_TYPE_TO_DIR };

package/src/lib/standards-context-injector.js

@@ -9,6 +9,7 @@
 
 import { readFileSync, existsSync } from 'fs';
 import { join } from 'path';
+import { resolveStandardsDir } from './stack-resolver.js';
 
 /**
  * Agent → Standards mapping
@@ -191,8 +192,8 @@ function loadStandard(standardName, projectPath) {
   const locations = [
     // 1. Project override
     join(projectPath, '.morph/project/standards', `${standardName}.md`),
-    // 2. Content standards (AI/Agent Framework, Azure, etc.)
-    join(projectPath, 'content/.morph/standards', `${standardName}.md`),
+    // 2. Stack standards (resolved dynamically based on project type)
+    join(resolveStandardsDir(projectPath), `${standardName}.md`),
     // 3. Framework standards (Blazor, CSS, .NET)
     join(projectPath, 'framework/standards', `${standardName}.md`)
   ];
@@ -273,7 +274,7 @@ export function getStandardsListForAgent(agentId) {
 export function checkStandardExists(standardName, projectPath = '.') {
   const locations = [
     { type: 'project', path: join(projectPath, '.morph/project/standards', `${standardName}.md`) },
-    { type: 'content', path: join(projectPath, 'content/.morph/standards', `${standardName}.md`) },
+    { type: 'stack', path: join(resolveStandardsDir(projectPath), `${standardName}.md`) },
     { type: 'framework', path: join(projectPath, 'framework/standards', `${standardName}.md`) }
   ];
 

package/src/lib/state-manager.js

@@ -139,6 +139,12 @@ function ensureFeature(featureName) {
       createdAt: new Date().toISOString(),
       updatedAt: new Date().toISOString(),
       activeAgents: [],
+      approvalGates: {
+        proposal: { approved: false, timestamp: null, approvedBy: null },
+        uiux: { approved: false, timestamp: null, approvedBy: null },
+        design: { approved: false, timestamp: null, approvedBy: null },
+        tasks: { approved: false, timestamp: null, approvedBy: null }
+      },
       outputs: {
         proposal: { created: false, path: `.morph/project/outputs/${featureName}/proposal.md` },
         spec: { created: false, path: `.morph/project/outputs/${featureName}/spec.md` },
@@ -412,3 +418,117 @@ export function getSummary() {
     featuresCount: Object.keys(state.features).length
   };
 }
+
+// ============================================================================
+// Approval Gates Operations
+// ============================================================================
+
+/**
+ * Set approval gate status
+ * @param {string} featureName - Feature name
+ * @param {string} gate - Gate name (proposal, uiux, design, tasks)
+ * @param {boolean} approved - Approval status
+ * @param {Object} metadata - Additional metadata (approvedBy, reason, etc.)
+ */
+export function setApprovalGate(featureName, gate, approved, metadata = {}) {
+  const state = loadState();
+  const feature = ensureFeature(featureName);
+
+  if (!feature.approvalGates) {
+    feature.approvalGates = {
+      proposal: { approved: false, timestamp: null, approvedBy: null },
+      uiux: { approved: false, timestamp: null, approvedBy: null },
+      design: { approved: false, timestamp: null, approvedBy: null },
+      tasks: { approved: false, timestamp: null, approvedBy: null }
+    };
+  }
+
+  feature.approvalGates[gate] = {
+    approved,
+    timestamp: metadata.approvedAt || metadata.rejectedAt || new Date().toISOString(),
+    approvedBy: metadata.approvedBy || metadata.rejectedBy || null,
+    ...metadata
+  };
+
+  state.features[featureName] = feature;
+  saveState(state);
+}
+
+/**
+ * Get approval gate status
+ * @param {string} featureName - Feature name
+ * @param {string} gate - Gate name
+ * @returns {Object|null} Gate object or null
+ */
+export function getApprovalGate(featureName, gate) {
+  const state = loadState();
+  const feature = state.features[featureName];
+
+  if (!feature || !feature.approvalGates) {
+    return null;
+  }
+
+  return feature.approvalGates[gate] || null;
+}
+
+/**
+ * Check if feature is pending approval
+ * @param {string} featureName - Feature name
+ * @returns {boolean} True if any gate is pending approval
+ */
+export function isPendingApproval(featureName) {
+  const state = loadState();
+  const feature = state.features[featureName];
+
+  if (!feature || !feature.approvalGates) {
+    return false;
+  }
+
+  const currentPhase = feature.phase;
+
+  // Check if current phase has an approval gate
+  const phaseGateMap = {
+    'design': 'design',
+    'tasks': 'tasks',
+    'uiux': 'uiux'
+  };
+
+  const relevantGate = phaseGateMap[currentPhase];
+  if (!relevantGate) {
+    return false;
+  }
+
+  const gate = feature.approvalGates[relevantGate];
+  return gate && !gate.approved;
+}
+
+/**
+ * Get approval history for a feature
+ * @param {string} featureName - Feature name
+ * @returns {Array} Array of approval events
+ */
+export function getApprovalHistory(featureName) {
+  const state = loadState();
+  const feature = state.features[featureName];
+
+  if (!feature || !feature.approvalGates) {
+    return [];
+  }
+
+  const history = [];
+
+  Object.entries(feature.approvalGates).forEach(([gate, data]) => {
+    if (data.timestamp) {
+      history.push({
+        gate,
+        approved: data.approved,
+        timestamp: data.timestamp,
+        approvedBy: data.approvedBy || data.rejectedBy,
+        reason: data.reason
+      });
+    }
+  });
+
+  // Sort by timestamp
+  return history.sort((a, b) => new Date(a.timestamp) - new Date(b.timestamp));
+}

package/src/lib/team-orchestrator.js

@@ -13,6 +13,7 @@
 import fs from 'fs/promises';
 import path from 'path';
 import { fileURLToPath } from 'url';
+import { resolveAgentsConfigPath } from './stack-resolver.js';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
@@ -23,7 +24,7 @@ const __dirname = path.dirname(__filename);
  * @returns {Promise<Object>} Parsed agents configuration
  */
 async function loadAgentsConfig(projectPath) {
-  const agentsPath = path.join(projectPath, 'content/.morph/config/agents.json');
+  const agentsPath = resolveAgentsConfigPath(projectPath);
   const content = await fs.readFile(agentsPath, 'utf8');
   return JSON.parse(content);
 }