@polymorphism-tech/morph-spec 4.21.0 → 5.0.1

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

@@ -1,600 +0,0 @@
-/**
- * MORPH-SPEC Phase Advance Command
- *
- * Validates current phase → advances to next → shows requirements.
- * Replaces the two-step `state set` + `validate-phase` dance.
- *
- * Usage:
- *   morph-spec phase advance <feature>
- *   morph-spec phase advance <feature> --skip-optional
- */
-
-import chalk from 'chalk';
-import { loadState, saveState, getFeature, getApprovalGate, derivePhase } from '../../core/state/state-manager.js';
-import { PHASES, validatePhase } from '../../lib/phase-chain/phase-validator.js';
-import { detectDesignSystem, hasUIAgentsActive } from '../../lib/detectors/design-system-detector.js';
-import { getOutputPath, getAbsoluteOutputPath } from '../../core/paths/output-schema.js';
-import { shouldAutoApprove } from '../../lib/trust/trust-manager.js';
-import { validateSpec } from '../../lib/validators/spec-validator.js';
-import { validateTransition } from '../../core/state/phase-state-machine.js';
-import { validateSpecContent, validateTasksContent } from '../../lib/validators/content/content-validator.js';
-import { getWorkflowConfig } from '../../core/workflows/workflow-detector.js';
-import { getStackProfile } from '../../lib/stack/stack-profile.js';
-import { readFileSync, existsSync, mkdirSync } from 'fs';
-import { join, dirname } from 'path';
-import { fileURLToPath } from 'url';
-import { emitValidatorDispatch } from '../../lib/validators/shared/emit-validator-dispatch.js';
-
-const __dirname = dirname(fileURLToPath(import.meta.url));
-
-// Phase order for advancing (skips optional phases unless active)
-const PHASE_ORDER = ['proposal', 'uiux', 'design', 'plan', 'tasks', 'implement', 'sync'];
-
-/**
- * Phases that require an explicit approval gate before advancing.
- * When --skip-approval is passed, these gates are bypassed and a warning is logged.
- * Exported for use in tests and in phase-runner warnings.
- */
-export const APPROVAL_GATE_MAP = {
-  'design': 'design',
-  'plan': 'plan',
-  'tasks': 'tasks',
-  'uiux': 'uiux'
-};
-
-/**
- * Get the next phase after the current one.
- * Returns { nextPhase, skippedPhases } so callers can persist skipped phases in state.
- */
-function getNextPhase(currentPhase, feature, skipOptional, featureName) {
-  // Load workflow config if workflow is set
-  let workflowConfig = null;
-  if (feature.workflow && feature.workflow !== 'auto') {
-    workflowConfig = getWorkflowConfig(feature.workflow);
-  }
-
-  const currentIndex = PHASE_ORDER.indexOf(currentPhase);
-  if (currentIndex === -1 || currentIndex >= PHASE_ORDER.length - 1) {
-    return { nextPhase: null, skippedPhases: [] };
-  }
-
-  // Agents that justify the uiux phase (wireframes, design system).
-  // Implementation-only agents (nextjs-expert) are NOT included —
-  // they build components from existing designs but don't create the design artifacts.
-  const uiDesignAgents = ['uiux-designer', 'ui-ux-designer', 'ui-designer'];
-
-  const skippedPhases = [];
-
-  for (let i = currentIndex + 1; i < PHASE_ORDER.length; i++) {
-    const candidate = PHASE_ORDER[i];
-    const phaseDef = PHASES[candidate];
-
-    // === Workflow-Based Phase Skipping ===
-    if (workflowConfig && workflowConfig.phases) {
-      // Check if workflow explicitly skips this phase
-      if (workflowConfig.phases.skip && workflowConfig.phases.skip.includes(candidate)) {
-        console.log(chalk.gray(`  ⏩ Skipping ${candidate}: workflow ${feature.workflow} skips this phase`));
-        skippedPhases.push(candidate);
-        continue;
-      }
-
-      // Check if this phase is part of a combined phase
-      if (workflowConfig.phases.combined) {
-        let isCombined = false;
-        for (const [combinedName, phases] of Object.entries(workflowConfig.phases.combined)) {
-          if (phases.includes(candidate) && candidate !== combinedName) {
-            console.log(chalk.gray(`  ⏩ Skipping ${candidate}: combined into ${combinedName} phase`));
-            skippedPhases.push(candidate);
-            isCombined = true;
-            break;
-          }
-        }
-        if (isCombined) continue;
-      }
-
-      // Check if workflow only runs specific phases
-      if (workflowConfig.phases.run && !workflowConfig.phases.run.includes(candidate)) {
-        // Also check if it's not a combined phase
-        const isCombinedPhase = workflowConfig.phases.combined &&
-          Object.keys(workflowConfig.phases.combined).includes(candidate);
-        if (!isCombinedPhase) {
-          console.log(chalk.gray(`  ⏩ Skipping ${candidate}: not in workflow run list`));
-          skippedPhases.push(candidate);
-          continue;
-        }
-      }
-
-      // Check conditional skips
-      if (workflowConfig.phases.skipIfCondition) {
-        const condition = workflowConfig.phases.skipIfCondition[candidate];
-        if (condition) {
-          // Evaluate condition (simple conditions for now)
-          if (condition === '!hasUIAgents' && !hasUIAgentsActive(process.cwd(), featureName)) {
-            console.log(chalk.gray(`  ⏩ Skipping ${candidate}: no UI agents active`));
-            skippedPhases.push(candidate);
-            continue;
-          }
-        }
-      }
-    }
-
-    // === Legacy Phase Skipping (fallback when no workflow config) ===
-    if (!workflowConfig) {
-      // Skip optional phases if flag set or no relevant agents/outputs
-      if (phaseDef?.optional && skipOptional) {
-        skippedPhases.push(candidate);
-        continue;
-      }
-
-      // Skip uiux if no UI design agents are active
-      if (candidate === 'uiux') {
-        if (feature.workflow === 'migration' || feature.workflow === 'refactor') {
-          console.log(chalk.gray(`  ⏩ Skipping ${candidate}: ${feature.workflow} workflow — no visual changes`));
-          skippedPhases.push(candidate);
-          continue;
-        }
-        const hasUiDesignAgent = feature.activeAgents?.some(a => uiDesignAgents.includes(a));
-        if (!hasUiDesignAgent && skipOptional !== false) {
-          console.log(chalk.gray(`  ⏩ Skipping ${candidate}: no UI design agents active`));
-          skippedPhases.push(candidate);
-          continue;
-        }
-      }
-
-      // sync is optional — only skip if --skip-optional is set
-      if (candidate === 'sync' && skipOptional) {
-        console.log(chalk.gray(`  ⏩ Skipping ${candidate}: optional phase`));
-        skippedPhases.push(candidate);
-        continue;
-      }
-    }
-
-    return { nextPhase: candidate, skippedPhases };
-  }
-
-  return { nextPhase: null, skippedPhases };
-}
-
-/**
- * Main command handler
- */
-export async function advancePhaseCommand(feature, options = {}) {
-  console.log(chalk.cyan('\n╔════════════════════════════════════════════════╗'));
-  console.log(chalk.cyan('║     MORPH-SPEC PHASE ADVANCE                   ║'));
-  console.log(chalk.cyan('╚════════════════════════════════════════════════╝\n'));
-
-  // Get current feature state
-  const featureData = getFeature(feature);
-  if (!featureData) {
-    console.log(chalk.red(`✗ Feature not found: ${feature}`));
-    console.log(chalk.yellow(`  Run: morph-spec state set ${feature} phase proposal`));
-    process.exit(1);
-  }
-
-  const featureFolderPath = join(process.cwd(), '.morph', 'features', feature);
-  const currentPhase = featureData.phase || derivePhase(featureFolderPath);
-  const currentPhaseDef = PHASES[currentPhase];
-
-  console.log(chalk.gray('Feature:'), feature);
-  console.log(chalk.gray('Current Phase:'), currentPhaseDef?.name || currentPhase);
-  console.log(chalk.gray('Workflow:'), featureData.workflow || 'auto');
-
-  // Determine next phase
-  const { nextPhase, skippedPhases } = getNextPhase(currentPhase, featureData, options.skipOptional, feature);
-
-  if (!nextPhase) {
-    console.log(chalk.green('\n✓ Feature is at the final phase!'));
-    if (currentPhase === 'implement' || currentPhase === 'sync') {
-      console.log(chalk.green('  Consider running: morph-spec generate recap ' + feature));
-    }
-    return;
-  }
-
-  const nextPhaseDef = PHASES[nextPhase];
-  console.log(chalk.gray('Next Phase:'), nextPhaseDef.name);
-
-  // === GATE 1: State Machine Validation ===
-  // When a workflow config defines which phases to run, getNextPhase()
-  // is authoritative for phase navigation. The state machine's
-  // adjacent-only transitions would reject legitimate workflow skips
-  // (e.g., fast-track: proposal → tasks).
-  const activeWorkflowConfig = featureData.workflow && featureData.workflow !== 'auto'
-    ? getWorkflowConfig(featureData.workflow)
-    : null;
-
-  if (!options.force && !activeWorkflowConfig) {
-    try {
-      validateTransition(currentPhase, nextPhase);
-    } catch (error) {
-      console.log(chalk.red('\n✗ Invalid phase transition'));
-      console.log(chalk.yellow(error.message));
-      console.log(chalk.gray('\nUse --force to override (not recommended)\n'));
-      process.exit(1);
-    }
-  }
-
-  // === GATE 2: Approval Gate Check ===
-  // Check if current phase requires approval before advancing
-  // Track gates that get approved implicitly so we can persist them after state load.
-  let gateApprovedImplicitly = null;   // { gate, approvedBy, reason }
-
-  const requiredGate = APPROVAL_GATE_MAP[currentPhase];
-  if (requiredGate && options.skipApproval) {
-    console.log(chalk.yellow(`\n⚠ --skip-approval: Approval gate "${requiredGate}" bypassed for phase "${currentPhase}"`));
-    console.log(chalk.gray('  Intended for CI/automation only. Run without --skip-approval for normal workflow.\n'));
-    gateApprovedImplicitly = { gate: requiredGate, approvedBy: 'skip-approval' };
-  }
-  if (requiredGate && !options.skipApproval) {
-    const gateStatus = getApprovalGate(feature, requiredGate);
-
-    // Check trust-based auto-approval before blocking
-    if (!gateStatus || !gateStatus.approved) {
-      try {
-        const trustResult = shouldAutoApprove(feature, requiredGate);
-        if (trustResult.autoApprove) {
-          console.log(chalk.green(`\n✓ Auto-approved gate "${requiredGate}" (${trustResult.reason})`));
-          // Proceed — trust bypasses manual gate requirement
-          gateApprovedImplicitly = { gate: requiredGate, approvedBy: `trust:${trustResult.level}` };
-        } else {
-          console.log(chalk.red(`\n✗ Phase "${currentPhase}" requires approval before advancing`));
-          console.log(chalk.gray(`   Trust level: ${trustResult.level} (${trustResult.reason})`));
-          console.log(chalk.yellow(`\nRun: morph-spec approve ${feature} ${requiredGate}`));
-          console.log(chalk.gray('Or use --skip-approval to bypass (not recommended)\n'));
-          process.exit(1);
-        }
-      } catch {
-        // Trust manager unavailable — fall through to manual gate check
-        console.log(chalk.red(`\n✗ Phase "${currentPhase}" requires approval before advancing`));
-        console.log(chalk.yellow(`\nRun: morph-spec approve ${feature} ${requiredGate}`));
-        console.log(chalk.gray('Or use --skip-approval to bypass (not recommended)\n'));
-        process.exit(1);
-      }
-    } else {
-      console.log(chalk.green(`✓ Approval gate "${requiredGate}" passed`));
-    }
-  }
-
-  // === GATE 3: Output Requirements ===
-  // Validate that current phase requirements are met before advancing
-  const validation = validatePhase(feature, nextPhase);
-
-  if (!validation.valid) {
-    console.log(chalk.red('\n✗ Cannot advance — missing requirements:'));
-    validation.missingOutputs.forEach(output => {
-      console.log(chalk.red(`  - ${output}`));
-    });
-    console.log(chalk.yellow(`\n  Complete these before advancing to ${nextPhaseDef.name}`));
-    process.exit(1);
-  }
-
-  if (validation.stateWarning) {
-    console.log(chalk.yellow(`\n⚠️  ${validation.stateWarning}`));
-  }
-
-  // === GATE 4: Content Validation ===
-  // Validate spec.md and contracts.cs when advancing from design phase
-  if (currentPhase === 'design' && nextPhase === 'plan') {
-    // Check spec.md structure and content (filesystem-based)
-    const specAbsPath = getAbsoluteOutputPath(process.cwd(), feature, 'spec');
-    if (existsSync(specAbsPath)) {
-      const specContentValidation = validateSpecContent(specAbsPath);
-
-      if (!specContentValidation.valid) {
-        console.log(chalk.red('\n✗ Spec content validation failed:'));
-        specContentValidation.errors.forEach(error => {
-          console.log(chalk.red(`  - ${error}`));
-        });
-        console.log('');
-        process.exit(1);
-      }
-
-      if (specContentValidation.warnings?.length > 0 && !options.skipWarnings) {
-        console.log(chalk.yellow('\n⚠️  Spec content warnings:'));
-        specContentValidation.warnings.forEach(warning => {
-          console.log(chalk.yellow(`  - ${warning}`));
-        });
-      }
-    }
-
-    // Run existing spec validator (anti-patterns, IaC checks)
-    const specValidation = await validateSpec('.', feature);
-
-    if (specValidation.errors > 0) {
-      console.log(chalk.red('\n✗ Spec validation failed — fix errors before advancing:'));
-      specValidation.issues.filter(i => i.level === 'error').forEach(issue => {
-        console.log(chalk.red(`  - ${issue.message}`));
-        console.log(chalk.yellow(`    → ${issue.solution}`));
-      });
-      console.log('');
-      process.exit(1);
-    }
-
-    if (specValidation.warnings > 0 && !options.skipWarnings) {
-      console.log(chalk.yellow('\n⚠️  Spec validation warnings:'));
-      specValidation.issues.filter(i => i.level === 'warning').forEach(issue => {
-        console.log(chalk.yellow(`  - ${issue.message}`));
-      });
-      console.log(chalk.gray('\n  (Use --skip-warnings to ignore warnings)\n'));
-    }
-  }
-
-  // === GATE 5: Tasks Content Validation ===
-  // Validate tasks.md structure when advancing to implement
-  if (currentPhase === 'tasks' && nextPhase === 'implement') {
-    const tasksAbsPath = getAbsoluteOutputPath(process.cwd(), feature, 'tasks');
-    if (existsSync(tasksAbsPath)) {
-      const tasksContentValidation = validateTasksContent(tasksAbsPath);
-
-      if (!tasksContentValidation.valid) {
-        console.log(chalk.red('\n✗ Tasks content validation failed:'));
-        tasksContentValidation.errors.forEach(error => {
-          console.log(chalk.red(`  - ${error}`));
-        });
-        console.log('');
-        process.exit(1);
-      }
-
-      if (tasksContentValidation.warnings?.length > 0 && !options.skipWarnings) {
-        console.log(chalk.yellow('\n⚠️  Tasks content warnings:'));
-        tasksContentValidation.warnings.forEach(warning => {
-          console.log(chalk.yellow(`  - ${warning}`));
-        });
-      }
-
-      // Show tasks stats
-      console.log(chalk.green(`\n✓ Tasks validated: ${tasksContentValidation.stats.totalTasks} total (${tasksContentValidation.stats.regularTasks} tasks + ${tasksContentValidation.stats.checkpoints} checkpoints)`));
-    }
-  }
-
-  // Gate: Check design system when advancing to implement with UI agents
-  if (nextPhase === 'implement') {
-    const gateResult = designSystemGate(feature, process.cwd());
-
-    if (gateResult.blocked) {
-      console.log(chalk.red(`\n✗ ${gateResult.message}`));
-      console.log('');
-      gateResult.solution.forEach(line => {
-        if (line === '') {
-          console.log('');
-        } else {
-          console.log(chalk.yellow(`  ${line}`));
-        }
-      });
-      console.log('');
-      process.exit(1);
-    }
-  }
-
-  // Advance the phase
-  const state = loadState();
-  state.features[feature].phase = nextPhase;
-  state.features[feature].updatedAt = new Date().toISOString();
-
-  // Create the target phase directory so derivePhase() reflects the new phase
-  const PHASE_DIR_MAP = {
-    'proposal': '0-proposal', 'design': '2-design', 'uiux': '1-ui',
-    'plan': '3-plan', 'tasks': '4-tasks', 'implement': '5-implement',
-  };
-  const targetDir = PHASE_DIR_MAP[nextPhase];
-  if (targetDir) {
-    const dirPath = join(featureFolderPath, targetDir);
-    if (!existsSync(dirPath)) {
-      mkdirSync(dirPath, { recursive: true });
-    }
-  }
-  if (skippedPhases.length > 0) {
-    const existingSkipped = state.features[feature].skippedPhases || [];
-    state.features[feature].skippedPhases = [...new Set([...existingSkipped, ...skippedPhases])];
-  }
-
-  // Ensure approvalGates object exists
-  if (!state.features[feature].approvalGates) {
-    state.features[feature].approvalGates = {};
-  }
-
-  const now = new Date().toISOString();
-  const gates = state.features[feature].approvalGates;
-
-  // Auto-approve proposal gate when advancing past the proposal phase.
-  // The act of advancing is itself the approval — no explicit gate check needed.
-  if (currentPhase === 'proposal' && !gates.proposal?.approved) {
-    gates.proposal = { approved: true, timestamp: now, approvedBy: 'workflow-advance' };
-  }
-
-  // Persist gates approved implicitly (trust auto-approve or --skip-approval bypass).
-  if (gateApprovedImplicitly && !gates[gateApprovedImplicitly.gate]?.approved) {
-    gates[gateApprovedImplicitly.gate] = {
-      approved: true,
-      timestamp: now,
-      approvedBy: gateApprovedImplicitly.approvedBy
-    };
-  }
-
-  // Auto-approve gates for phases that were legitimately skipped.
-  // Skipped phases never run their explicit approve step, so their gate would
-  // otherwise stay false in state — making approval-status misleading.
-  for (const skippedPhase of skippedPhases) {
-    const skippedGate = APPROVAL_GATE_MAP[skippedPhase];
-    if (skippedGate && !gates[skippedGate]?.approved) {
-      gates[skippedGate] = { approved: true, timestamp: now, approvedBy: 'phase-skipped' };
-    }
-  }
-
-  saveState(state);
-
-  // Run PhaseAdvanced agent-teams hook (non-blocking)
-  try {
-    const { executeHook, formatHookResults } = await import('../../lib/hooks/hook-executor.js');
-    const hookResult = await executeHook(process.cwd(), feature, 'PhaseAdvanced', {
-      fromPhase: currentPhase,
-      toPhase: nextPhase
-    });
-    if (!hookResult.passed && hookResult.errors.length > 0) {
-      const output = formatHookResults(hookResult, 'PhaseAdvanced');
-      console.log(output);
-    }
-  } catch {
-    // Hook executor unavailable — non-blocking
-  }
-
-  // Agent detection refresh (fail-open)
-  try {
-    const { refreshAgents, displayDetectionDiff } = await import('../agents/detect-agents.js');
-    const refreshResult = await refreshAgents(process.cwd(), feature);
-    if (refreshResult.added.length > 0) {
-      displayDetectionDiff(refreshResult, currentPhase, nextPhase);
-    }
-  } catch {
-    // Refresh is diagnostic — fail-open, phase advance already completed
-  }
-
-  // Emit Tier-4 validator dispatch when advancing into implement or sync phase
-  const phasesNeedingValidation = ['implement', 'sync'];
-  if (phasesNeedingValidation.includes(nextPhase) || phasesNeedingValidation.includes(currentPhase)) {
-    const validationPhase = phasesNeedingValidation.includes(nextPhase) ? nextPhase : currentPhase;
-    await emitValidatorDispatch(feature, validationPhase, process.cwd());
-  }
-
-  // Emit SKILL DISPATCH for any phase that has requiredSkills
-  await emitSkillDispatch(nextPhase, process.cwd());
-
-  console.log(chalk.green(`\n✓ Advanced to ${nextPhaseDef.name}`));
-
-  // Show what's needed in the new phase
-  console.log(chalk.cyan('\n📋 Phase requirements:'));
-  console.log(chalk.gray(`   ${nextPhaseDef.description}`));
-
-  if (nextPhaseDef.requiredOutputs?.length > 0) {
-    console.log(chalk.cyan('\n   Required outputs:'));
-    nextPhaseDef.requiredOutputs.forEach(output => {
-      const exists = validation.phase ? true : false; // Already validated
-      console.log(chalk.gray(`   ✓ ${output} (exists)`));
-    });
-  }
-
-  // Show phase-specific guidance
-  const guidance = getPhaseGuidance(nextPhase, feature);
-  if (guidance) {
-    console.log(chalk.cyan('\n   Next steps:'));
-    guidance.forEach(step => console.log(chalk.white(`   → ${step}`)));
-  }
-
-  console.log('');
-}
-
-/**
- * Get guidance for what to do in a phase
- */
-function getPhaseGuidance(phase, feature) {
-  const guides = {
-    'uiux': [
-      `Resume spec pipeline: /morph-proposal ${feature}`,
-      'Provide layout references and preferences',
-      'Review wireframes before proceeding'
-    ],
-    'design': (() => {
-      const { isDotnet } = getStackProfile();
-      return [
-        `Resume spec pipeline: /morph-proposal ${feature}`,
-        'Review DECISION POINTS carefully',
-        isDotnet ? 'Approve spec.md and contracts.cs' : 'Approve spec.md and contracts.ts (TypeScript + Zod schemas)'
-      ];
-    })(),
-    'plan': [
-      `Resume spec pipeline: /morph-proposal ${feature}`,
-      'Review implementation plan for completeness',
-      'Approve plan before generating task breakdown'
-    ],
-    'tasks': [
-      `Resume spec pipeline: /morph-proposal ${feature}`,
-      'Review task order and dependencies',
-      'Approve task list before implementing'
-    ],
-    'implement': [
-      `Start implementing: /morph-apply ${feature}`,
-      'Complete tasks one by one with: morph-spec task done',
-      'Validators run automatically on task completion'
-    ],
-    'sync': [
-      'Review decisions.md for standards to promote',
-      `Decisions file: ${getOutputPath(feature, 'decisions')}`
-    ]
-  };
-
-  return guides[phase] || null;
-}
-
-/**
- * Gate: Check design system exists when advancing to implement with UI agents
- * @param {string} feature - Feature name
- * @param {string} projectPath - Project root path
- * @returns {Object} { blocked: boolean, message?: string, solution?: string[] }
- */
-function designSystemGate(feature, projectPath = '.') {
-  // Check if UI agents are active
-  const hasUIAgents = hasUIAgentsActive(projectPath, feature);
-
-  if (!hasUIAgents) {
-    return { blocked: false }; // No UI agents, gate doesn't apply
-  }
-
-  // Check if design system exists
-  const dsDetection = detectDesignSystem(projectPath, feature);
-
-  if (dsDetection.hasDesignSystem) {
-    return { blocked: false }; // Design system exists, gate passed
-  }
-
-  // Block advancement - no design system found with UI agents active
-  return {
-    blocked: true,
-    message: 'Cannot advance to implementation — UI agents are active but no design system found',
-    solution: [
-      'Design system is required when UI agents (ui-designer, css-specialist) are active',
-      '',
-      'Create a design system with one of these options:',
-      '  1. Project-level: .morph/context/design-system.md (shared across features)',
-      `  2. Feature-level: ${getOutputPath(feature, 'uiDesignSystem')} (feature-specific)`,
-      '  3. Run /morph-phase-uiux skill to auto-generate from existing codebase',
-      '',
-      'Or remove UI agents if they are not needed:',
-      `  morph-spec state remove-agent ${feature} css-specialist`
-    ]
-  };
-}
-
-/**
- * Emit a SKILL DISPATCH block when advancing to a phase that has requiredSkills.
- * Outputs structured JSON for the LLM to read and follow.
- * Non-blocking — fails silently.
- *
- * @param {string} nextPhase - The phase being advanced into
- * @param {string} cwd - Project root path (for locating phases.json)
- */
-async function emitSkillDispatch(nextPhase, cwd) {
-  try {
-    // Try project-local phases.json first, fall back to package-level
-    const localPath = join(cwd, 'framework', 'phases.json');
-    const packagePath = join(__dirname, '../../../framework/phases.json');
-    const resolvedPath = existsSync(localPath) ? localPath : packagePath;
-
-    if (!existsSync(resolvedPath)) return;
-
-    const phasesData = JSON.parse(readFileSync(resolvedPath, 'utf8'));
-    const skills = phasesData?.phases?.[nextPhase]?.requiredSkills;
-    if (!skills || skills.length === 0) return;
-
-    const dispatch = {
-      skillDispatch: true,
-      phase: nextPhase,
-      skills,
-      instruction: `These skills are MANDATORY for phase '${nextPhase}'. Invoke them at the specified trigger points using Skill(). Do NOT skip them.`,
-    };
-
-    console.log(chalk.cyan('\n--- SKILL DISPATCH ---'));
-    console.log(JSON.stringify(dispatch, null, 2));
-    console.log(chalk.cyan('--- END SKILL DISPATCH ---\n'));
-  } catch {
-    // Non-blocking — fail silently
-  }
-}