@polymorphism-tech/morph-spec 4.22.0 → 5.0.1

package/src/commands/state/phase-runner.js

@@ -1,215 +0,0 @@
-/**
- * MORPH-SPEC Phase Runner
- *
- * Executes an automated phase chain loop for a feature.
- * Reads eligibility at each step, auto-advances when eligible, and
- * pauses on blockers (blocked_tasks, low_pass_rate, trust_too_low).
- *
- * Usage:
- *   morph-spec phase run <feature>
- *   morph-spec phase run <feature> --dry-run
- *   morph-spec phase run <feature> --max-phases 3
- *
- * Eligibility gates:
- *   - Required outputs present on disk
- *   - No blocked tasks in validationHistory
- *   - Validation pass rate >= minPassRate (from workflow config)
- *   - Trust level meets gate requirements (or gates already approved)
- *
- * Level 3 autonomy: when run with zero-touch workflow + trust=maximum,
- * executes proposal → design → tasks → implement without human input,
- * pausing only on escalation triggers.
- */
-
-import chalk from 'chalk';
-import { join } from 'path';
-import { checkPhaseEligibility, computePassRate } from '../../lib/phase-chain/phase-validator.js';
-import { advancePhaseCommand } from './advance-phase.js';
-import { loadState } from '../../core/state/state-manager.js';
-import { derivePhase } from '../../core/state/state-manager.js';
-import { getWorkflowConfig } from '../../core/workflows/workflow-detector.js';
-
-// Phases that trigger a pause regardless of eligibility
-const PAUSE_TRIGGERS = ['blocked_tasks', 'trust_too_low'];
-
-// Maximum auto-phases before stopping (safety valve)
-const DEFAULT_MAX_PHASES = 6;
-
-/**
- * Render a decision tree for --dry-run mode.
- */
-function renderDecisionTree(featureName, eligibility, workflowConfig, dryRun) {
-  const { eligible, blockers, currentPhase, nextPhase, passRate } = eligibility;
-
-  console.log(chalk.cyan('\n╔════════════════════════════════════════════════╗'));
-  console.log(chalk.cyan('║       MORPH-SPEC PHASE CHAIN DECISION TREE     ║'));
-  if (dryRun) console.log(chalk.yellow('║               *** DRY RUN ***                  ║'));
-  console.log(chalk.cyan('╚════════════════════════════════════════════════╝\n'));
-
-  console.log(chalk.gray('Feature:'), featureName);
-  console.log(chalk.gray('Current Phase:'), chalk.cyan(currentPhase));
-  console.log(chalk.gray('Next Phase:'), nextPhase ? chalk.cyan(nextPhase) : chalk.gray('(final)'));
-  if (passRate !== null) {
-    const rateColor = passRate >= 0.95 ? chalk.green : passRate >= 0.80 ? chalk.yellow : chalk.red;
-    console.log(chalk.gray('Pass Rate:'), rateColor(`${(passRate * 100).toFixed(0)}%`));
-  }
-
-  if (workflowConfig?.phaseChain) {
-    console.log(chalk.gray('Phase Chain:'), chalk.green('enabled'));
-    console.log(chalk.gray('Max Auto Phases:'), workflowConfig.phaseChain.maxAutoPhases ?? DEFAULT_MAX_PHASES);
-  }
-
-  console.log();
-
-  if (eligible) {
-    console.log(chalk.green(`✓ ELIGIBLE — can advance from ${currentPhase} → ${nextPhase}`));
-  } else {
-    console.log(chalk.red(`✗ BLOCKED — cannot advance from ${currentPhase}`));
-    console.log(chalk.yellow('\n  Blockers:'));
-    for (const blocker of blockers) {
-      switch (blocker.type) {
-        case 'missing_outputs':
-          console.log(chalk.red(`    • missing_outputs: ${blocker.items.join(', ')}`));
-          break;
-        case 'blocked_tasks':
-          console.log(chalk.red(`    • blocked_tasks: ${blocker.items.join(', ')} (attempt ≥ 3, needs human review)`));
-          break;
-        case 'low_pass_rate':
-          console.log(chalk.red(`    • low_pass_rate: ${(blocker.current * 100).toFixed(0)}% (required: ${(blocker.required * 100).toFixed(0)}%)`));
-          break;
-        case 'trust_too_low':
-          console.log(chalk.yellow(`    • trust_too_low: ${blocker.items.join(', ')}`));
-          break;
-        default:
-          console.log(chalk.red(`    • ${blocker.type}: ${(blocker.items || []).join(', ')}`));
-      }
-    }
-  }
-
-  console.log();
-}
-
-/**
- * Main command handler for `morph-spec phase run <feature>`.
- *
- * @param {string} featureName - Feature to run
- * @param {Object} options
- * @param {boolean} [options.dryRun] - Show decision tree without executing
- * @param {number} [options.maxPhases] - Max phases to auto-advance (default: 6)
- * @param {boolean} [options.skipApproval] - Skip approval gate checks
- */
-export async function phaseRunCommand(featureName, options = {}) {
-  if (!featureName) {
-    console.error(chalk.red('Usage: morph-spec phase run <feature> [--dry-run] [--max-phases N]'));
-    process.exit(1);
-  }
-
-  const maxPhases = options.maxPhases ?? DEFAULT_MAX_PHASES;
-  const dryRun = options.dryRun ?? false;
-
-  // Load workflow config for phaseChain settings
-  const state = loadState(false);
-  const feature = state?.features?.[featureName];
-  let workflowConfig = null;
-  if (feature?.workflow && feature.workflow !== 'auto') {
-    try {
-      workflowConfig = getWorkflowConfig(feature.workflow);
-    } catch {
-      // Non-blocking
-    }
-  }
-
-  // Determine pause conditions from workflow
-  const pauseOnTypes = workflowConfig?.phaseChain?.pauseOn ?? PAUSE_TRIGGERS;
-  const autoChainMax = workflowConfig?.phaseChain?.maxAutoPhases ?? maxPhases;
-
-  if (!dryRun) {
-    console.log(chalk.cyan('\n╔════════════════════════════════════════════════╗'));
-    console.log(chalk.cyan('║         MORPH-SPEC PHASE CHAIN RUNNER          ║'));
-    console.log(chalk.cyan('╚════════════════════════════════════════════════╝\n'));
-    console.log(chalk.gray('Feature:'), featureName);
-    console.log(chalk.gray('Max auto-phases:'), autoChainMax);
-    console.log();
-  }
-
-  let phasesAdvanced = 0;
-
-  while (phasesAdvanced < autoChainMax) {
-    // ── Check eligibility ──────────────────────────────────────────────────
-    const eligibility = checkPhaseEligibility(featureName, { projectPath: process.cwd() });
-
-    // Dry-run: just show the decision tree and exit
-    if (dryRun) {
-      renderDecisionTree(featureName, eligibility, workflowConfig, true);
-      return;
-    }
-
-    // Display current state
-    console.log(chalk.gray(`[${phasesAdvanced + 1}/${autoChainMax}] Checking phase: ${eligibility.currentPhase} → ${eligibility.nextPhase || '(final)'}`));
-
-    if (!eligibility.nextPhase) {
-      console.log(chalk.green('\n✓ Feature has reached the final phase!'));
-      console.log(chalk.gray('  Consider running: morph-spec generate recap ' + featureName));
-      break;
-    }
-
-    if (!eligibility.eligible) {
-      // Check if any blocker type triggers a pause
-      const shouldPause = eligibility.blockers.some(b => pauseOnTypes.includes(b.type));
-
-      console.log(chalk.yellow(`\n⚠ Not eligible to advance (${eligibility.currentPhase} → ${eligibility.nextPhase})`));
-      for (const blocker of eligibility.blockers) {
-        switch (blocker.type) {
-          case 'missing_outputs':
-            console.log(chalk.gray(`  • Missing outputs: ${blocker.items.join(', ')}`));
-            break;
-          case 'blocked_tasks':
-            console.log(chalk.red(`  • Blocked tasks: ${blocker.items.join(', ')} — requires human review`));
-            break;
-          case 'low_pass_rate':
-            console.log(chalk.yellow(`  • Low pass rate: ${(blocker.current * 100).toFixed(0)}% < ${(blocker.required * 100).toFixed(0)}% required`));
-            break;
-          case 'trust_too_low':
-            console.log(chalk.yellow(`  • Trust too low: ${blocker.items.join(', ')}`));
-            break;
-          default:
-            console.log(chalk.gray(`  • ${blocker.type}: ${(blocker.items || []).join(', ')}`));
-        }
-      }
-
-      if (shouldPause) {
-        console.log(chalk.red('\n⛔ Pausing phase chain — human intervention required'));
-        console.log(chalk.gray('  Fix the blockers above, then re-run: morph-spec phase run ' + featureName));
-        process.exit(1);
-      }
-
-      // Non-pause blocker (e.g. missing_optional_outputs) — still stop
-      console.log(chalk.yellow('\n  Stopping chain — resolve blockers before continuing'));
-      break;
-    }
-
-    // ── Advance the phase ─────────────────────────────────────────────────
-    console.log(chalk.green(`\n✓ Eligible — advancing to ${eligibility.nextPhase}`));
-
-    try {
-      await advancePhaseCommand(featureName, {
-        skipOptional: false,
-        skipApproval: options.skipApproval,
-      });
-      phasesAdvanced++;
-    } catch (err) {
-      console.error(chalk.red(`\n✗ Phase advance failed: ${err.message}`));
-      console.log(chalk.gray('  Fix the issue and re-run: morph-spec phase run ' + featureName));
-      process.exit(1);
-    }
-  }
-
-  if (phasesAdvanced >= autoChainMax) {
-    console.log(chalk.yellow(`\n⚠ Reached max auto-phases limit (${autoChainMax})`));
-    console.log(chalk.gray('  Use --max-phases N to increase the limit'));
-  }
-
-  if (phasesAdvanced > 0 && !dryRun) {
-    console.log(chalk.cyan(`\n  ${phasesAdvanced} phase(s) advanced automatically`));
-  }
-}

package/src/commands/state/state.js

@@ -1,444 +0,0 @@
-/**
- * MORPH-SPEC State Command
- * CLI wrapper for state management operations
- */
-
-import { join } from 'path';
-import { readFileSync, existsSync } from 'fs';
-import ora from 'ora';
-import chalk from 'chalk';
-import { logger } from '../../utils/logger.js';
-import * as StateManager from '../../core/state/state-manager.js';
-import { derivePhase } from '../../core/state/state-manager.js';
-
-// ============================================================================
-// Phase Resolution
-// ============================================================================
-
-const PHASE_ORDER_LIST = ['proposal', 'uiux', 'design', 'plan', 'tasks', 'implement', 'sync', 'archived'];
-
-/**
- * Resolve the effective phase: pick whichever is further ahead between the
- * stored phase (set by `phase advance`) and the derived phase (from filesystem).
- */
-function resolvePhase(storedPhase, derivedPhase) {
-  if (!storedPhase) return derivedPhase;
-  if (!derivedPhase) return storedPhase;
-  const storedIdx = PHASE_ORDER_LIST.indexOf(storedPhase);
-  const derivedIdx = PHASE_ORDER_LIST.indexOf(derivedPhase);
-  return storedIdx > derivedIdx ? storedPhase : derivedPhase;
-}
-
-// ============================================================================
-// Phase Protection
-// ============================================================================
-
-/**
- * Phases that have approval gates and cannot be set directly via `state set`.
- * These phases must be reached through `morph-spec phase advance` which enforces
- * all validation gates (approval, output requirements, spec content, etc.).
- *
- * Lightweight phases (proposal, sync) are not in this list
- * because they have no approval gates and are safe to set directly.
- */
-export const PROTECTED_PHASES = ['design', 'tasks', 'uiux', 'implement'];
-
-/**
- * Validate a direct phase-set request.
- *
- * @param {string} phase - The target phase value
- * @returns {{ blocked: boolean, message?: string }}
- */
-export function validatePhaseSet(phase) {
-  if (PROTECTED_PHASES.includes(phase)) {
-    return {
-      blocked: true,
-      message: `Phase "${phase}" has approval gates — use "morph-spec phase advance" instead of setting it directly.`
-    };
-  }
-  return { blocked: false };
-}
-
-// ============================================================================
-// Command Functions
-// ============================================================================
-
-/**
- * Main state command router
- */
-export async function stateCommand(action, args, options) {
-  switch (action) {
-    case 'init':
-      await initCommand(options);
-      break;
-
-    case 'get':
-      await getCommand(args[0], options);
-      break;
-
-    case 'set':
-      await setCommand(args[0], args[1], args[2], options);
-      break;
-
-    case 'list':
-      await listCommand(options);
-      break;
-
-    case 'add-agent':
-      await addAgentCommand(args[0], args[1], options);
-      break;
-
-    case 'remove-agent':
-      await removeAgentCommand(args[0], args[1], options);
-      break;
-
-    case 'mark-output':
-      await markOutputCommand(args[0], args[1], options);
-      break;
-
-    default:
-      logger.error(`Unknown action: ${action}`);
-      logger.blank();
-      logger.info('Available actions:');
-      logger.dim('  init, get, set, list, add-agent, remove-agent, mark-output');
-      logger.blank();
-      logger.dim('Run "morph-spec state --help" for more information');
-      process.exit(1);
-  }
-}
-
-/**
- * Initialize state file
- */
-async function initCommand(options) {
-  logger.header('Initialize State');
-  logger.blank();
-
-  try {
-    if (StateManager.stateExists() && !options.force) {
-      logger.warn('State file already exists.');
-      logger.dim('  Use --force to overwrite');
-      logger.blank();
-      return;
-    }
-
-    const spinner = ora('Initializing state.json...').start();
-
-    // Read project name and stack from config.json if not provided via options
-    let projectName = options.project;
-    let projectType = options.type;
-    if (!projectName || !projectType) {
-      const configPath = join(process.cwd(), '.morph', 'config', 'config.json');
-      if (existsSync(configPath)) {
-        try {
-          const config = JSON.parse(readFileSync(configPath, 'utf8'));
-          projectName = projectName || config.project?.name || 'unknown';
-          projectType = projectType || config.project?.stack || 'unknown';
-        } catch {
-          projectName = projectName || 'unknown';
-          projectType = projectType || 'unknown';
-        }
-      } else {
-        projectName = projectName || 'unknown';
-        projectType = projectType || 'unknown';
-      }
-    }
-
-    StateManager.initState({
-      force: options.force,
-      projectName,
-      projectType
-    });
-
-    spinner.succeed('State initialized!');
-    logger.blank();
-    logger.dim(`Location: ${StateManager.getStatePath()}`);
-    logger.blank();
-
-  } catch (error) {
-    logger.error(error.message);
-    process.exit(1);
-  }
-}
-
-/**
- * Get feature state
- */
-async function getCommand(featureName, options) {
-  if (!featureName) {
-    logger.error('Feature name required');
-    logger.dim('  Usage: morph-spec state get <feature>');
-    process.exit(1);
-  }
-
-  try {
-    const feature = StateManager.getFeature(featureName);
-
-    if (!feature) {
-      logger.error(`Feature '${featureName}' not found`);
-      process.exit(1);
-    }
-
-    if (options.json) {
-      console.log(JSON.stringify(feature, null, 2));
-    } else {
-      logger.header(`Feature: ${featureName}`);
-      logger.blank();
-      const featurePath = join(process.cwd(), '.morph/features', featureName);
-      const derivedPhase = derivePhase(featurePath);
-      // Use stored phase when it's ahead of derived (directory may not exist yet)
-      const phase = resolvePhase(feature.phase, derivedPhase);
-      const tasks = feature.tasks || { completed: 0, total: 0 };
-      // Prefer taskList.length as total when tasks.total is stale/zero (Problem 3 complement)
-      const total = tasks.total || (Array.isArray(feature.taskList) ? feature.taskList.length : 0);
-      const taskDisplay = total > 0
-        ? `${tasks.completed}/${total}`
-        : tasks.completed > 0 ? `${tasks.completed}/? (run task done to sync)` : '0/? (tasks not yet loaded)';
-      logger.info(`Status:  ${chalk.cyan(feature.status || 'draft')}`);
-      logger.info(`Phase:   ${chalk.cyan(phase)}`);
-      logger.info(`Tasks:   ${chalk.cyan(taskDisplay)}`);
-      logger.info(`Agents:  ${chalk.cyan((feature.activeAgents || []).join(', ') || 'None')}`);
-      const outputs = Object.keys(feature.outputs || {}).filter(k => feature.outputs[k]?.created);
-      if (outputs.length > 0) {
-        logger.info(`Outputs: ${chalk.cyan(outputs.join(', '))}`);
-      }
-      logger.blank();
-    }
-
-  } catch (error) {
-    logger.error(error.message);
-    process.exit(1);
-  }
-}
-
-/**
- * Set feature property
- */
-async function setCommand(featureName, key, value, options) {
-  if (!featureName || !key || value === undefined) {
-    logger.error('Missing required arguments');
-    logger.dim('  Usage: morph-spec state set <feature> <key> <value>');
-    logger.blank();
-    logger.dim('  Example: morph-spec state set my-feature phase implement');
-    process.exit(1);
-  }
-
-  try {
-    // Guard: block protected phases unless --force is explicitly passed
-    if (key === 'phase') {
-      const phaseValidation = validatePhaseSet(value);
-      if (phaseValidation.blocked && !options.force) {
-        logger.error(phaseValidation.message);
-        logger.blank();
-        logger.dim(`  Protected phases (have approval gates): ${PROTECTED_PHASES.join(', ')}`);
-        logger.dim(`  Use the validated advance flow instead:`);
-        logger.dim(`    morph-spec phase advance ${featureName}`);
-        logger.blank();
-        logger.dim(`  To bypass all gates (expert use only):`);
-        logger.dim(`    morph-spec state set ${featureName} phase ${value} --force`);
-        process.exit(1);
-      }
-
-      if (phaseValidation.blocked) {
-        logger.warn(`FORCED phase override to "${value}" — all approval gates bypassed.`);
-      } else {
-        logger.warn(`Direct phase override — validation gates may be bypassed.`);
-        logger.dim(`  The actual phase is derived from filesystem subdirectories`);
-        logger.dim(`  (0-proposal/, 2-design/, 4-tasks/, 5-implement/). This sets a state.json`);
-        logger.dim(`  override used only for lightweight phases (proposal, sync).`);
-        logger.dim(`  Recommended: morph-spec phase advance ${featureName}`);
-      }
-      logger.blank();
-    }
-
-    // Validate workflow values
-    if (key === 'workflow') {
-      try {
-        const { listWorkflows } = await import('../../core/workflows/workflow-detector.js');
-        const validIds = listWorkflows().map(w => w.id).concat(['auto']);
-        if (!validIds.includes(value)) {
-          logger.error(`Invalid workflow: "${value}"`);
-          logger.dim(`  Valid workflows: ${validIds.join(', ')}`);
-          logger.blank();
-          process.exit(1);
-        }
-      } catch {
-        // Workflow detector unavailable — skip validation
-      }
-    }
-
-    const spinner = ora('Updating state...').start();
-
-    // Parse value automatically (JSON, number, boolean)
-    let parsedValue = value;
-    try {
-      parsedValue = JSON.parse(value);
-    } catch {
-      // Keep as string if not valid JSON
-    }
-
-    StateManager.updateFeature(featureName, key, parsedValue);
-
-    spinner.succeed(`Updated ${chalk.cyan(featureName)}.${chalk.cyan(key)}`);
-    logger.blank();
-    logger.dim(`Value: ${JSON.stringify(parsedValue)}`);
-    logger.blank();
-
-  } catch (error) {
-    logger.error(error.message);
-    process.exit(1);
-  }
-}
-
-/**
- * List all features
- */
-async function listCommand(options) {
-  logger.header('MORPH-SPEC Project Status');
-  logger.blank();
-
-  try {
-    const summary = StateManager.getSummary();
-    const features = StateManager.listFeatures();
-
-    // Project info
-    const projectName = summary.project?.name || '(unnamed)';
-    const projectType = summary.project?.type || '(unknown)';
-    logger.info(`Project: ${chalk.cyan(projectName)}`);
-    logger.info(`Type: ${chalk.cyan(projectType)}`);
-    logger.blank();
-
-    if (features.length === 0) {
-      logger.warn('No features found');
-      logger.blank();
-      return;
-    }
-
-    // Features table
-    logger.header('Features:');
-    logger.blank();
-
-    features.forEach(([name, feature]) => {
-      const statusEmoji = {
-        draft: '📝',
-        in_review: '👀',
-        approved: '✅',
-        in_progress: '🚧',
-        done: '✔️',
-        archived: '📦'
-      }[feature.status] || '❓';
-
-      const tasks = feature.tasks || {};
-      const total = tasks.total || (Array.isArray(feature.taskList) ? feature.taskList.length : 0);
-      const progress = total > 0
-        ? `${tasks.completed || 0}/${total}`
-        : '-';
-
-      logger.info(`${statusEmoji}  ${chalk.bold(name)}`);
-      const featurePath = join(process.cwd(), '.morph/features', name);
-      const featurePhase = resolvePhase(feature.phase, derivePhase(featurePath));
-      logger.dim(`   Phase: ${featurePhase.padEnd(16)} │ Tasks: ${progress}`);
-      logger.dim(`   Agents: ${(feature.activeAgents || []).slice(0, 5).join(', ') || 'None'}`);
-      logger.blank();
-    });
-
-    // Summary
-    logger.header('Summary:');
-    logger.info(`Total Features: ${chalk.cyan(summary.metadata?.totalFeatures ?? features.length)}`);
-    logger.info(`Completed: ${chalk.cyan(summary.metadata?.completedFeatures ?? 0)}`);
-    logger.blank();
-
-  } catch (error) {
-    logger.error(error.message);
-    process.exit(1);
-  }
-}
-
-/**
- * Add agent to feature
- */
-async function addAgentCommand(featureName, agentId, options) {
-  if (!featureName || !agentId) {
-    logger.error('Missing required arguments');
-    logger.dim('  Usage: morph-spec state add-agent <feature> <agent-id>');
-    process.exit(1);
-  }
-
-  try {
-    const added = StateManager.addAgent(featureName, agentId);
-
-    if (added) {
-      logger.success(`Agent '${chalk.cyan(agentId)}' added to ${chalk.cyan(featureName)}`);
-    } else {
-      logger.warn(`Agent '${agentId}' already active`);
-    }
-    logger.blank();
-
-  } catch (error) {
-    logger.error(error.message);
-    process.exit(1);
-  }
-}
-
-/**
- * Remove agent from feature
- */
-async function removeAgentCommand(featureName, agentId, options) {
-  if (!featureName || !agentId) {
-    logger.error('Missing required arguments');
-    logger.dim('  Usage: morph-spec state remove-agent <feature> <agent-id>');
-    process.exit(1);
-  }
-
-  try {
-    const removed = StateManager.removeAgent(featureName, agentId);
-
-    if (removed) {
-      logger.success(`Agent '${chalk.cyan(agentId)}' removed from ${chalk.cyan(featureName)}`);
-    } else {
-      logger.warn(`Agent '${agentId}' not found`);
-    }
-    logger.blank();
-
-  } catch (error) {
-    logger.error(error.message);
-    process.exit(1);
-  }
-}
-
-/**
- * Mark output as created
- */
-async function markOutputCommand(featureName, outputType, options) {
-  if (!featureName || !outputType) {
-    logger.error('Missing required arguments');
-    logger.dim('  Usage: morph-spec state mark-output <feature> <output-type>');
-    logger.blank();
-    logger.dim('  Valid types:');
-    logger.dim('    Proposal:  proposal');
-    logger.dim('    Design:    schemaAnalysis, spec, contracts, contractsVsa, decisions');
-    logger.dim('    Tasks:     tasks');
-    logger.dim('    UI/UX:     uiDesignSystem, uiMockups, uiComponents, uiFlows');
-    logger.dim('    Implement: recap');
-    logger.blank();
-    logger.dim('  Note: kebab-case aliases accepted (e.g., ui-design-system, schema-analysis)');
-    logger.blank();
-    logger.dim('  Examples:');
-    logger.dim('    morph-spec state mark-output my-feature spec');
-    logger.dim('    morph-spec state mark-output my-feature schemaAnalysis');
-    logger.dim('    morph-spec state mark-output my-feature uiDesignSystem');
-    logger.dim('    morph-spec state mark-output my-feature ui-design-system');
-    process.exit(1);
-  }
-
-  try {
-    StateManager.markOutput(featureName, outputType);
-
-    logger.success(`Output '${chalk.cyan(outputType)}' marked as created for ${chalk.cyan(featureName)}`);
-    logger.blank();
-
-  } catch (error) {
-    logger.error(error.message);
-    process.exit(1);
-  }
-}