@polymorphism-tech/morph-spec 4.8.19 → 4.10.0

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

@@ -11,22 +11,36 @@
 
 import chalk from 'chalk';
 import { loadState, saveState, getFeature, getApprovalGate, derivePhase } from '../../core/state/state-manager.js';
-import { PHASES, validatePhase } from './validate-phase.js';
+import { PHASES, validatePhase } from '../../lib/phase-chain/phase-validator.js';
 import { detectDesignSystem, hasUIAgentsActive } from '../../lib/detectors/design-system-detector.js';
-import { getOutputPath } from '../../core/paths/output-schema.js';
-import { shouldAutoApprove, autoCalculateTrust } from '../../lib/trust/trust-manager.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, getPhaseDisplayName } from '../../core/state/phase-state-machine.js';
-import { validateSpecContent, validateTasksContent, validateFeatureOutputs } from '../../lib/validators/content/content-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 } 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', 'setup', 'uiux', 'design', 'clarify', 'tasks', 'implement', 'sync'];
+const PHASE_ORDER = ['proposal', 'setup', 'uiux', 'design', 'clarify', '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.
@@ -66,13 +80,16 @@ function getNextPhase(currentPhase, feature, skipOptional, featureName) {
 
       // 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);
-            continue;
+            isCombined = true;
+            break;
           }
         }
+        if (isCombined) continue;
       }
 
       // Check if workflow only runs specific phases
@@ -119,14 +136,11 @@ function getNextPhase(currentPhase, feature, skipOptional, featureName) {
         }
       }
 
-      // Skip sync for simple workflows
-      if (candidate === 'sync') {
-        const isSimple = feature.workflow === 'fast-track';
-        if (isSimple && skipOptional !== false) {
-          console.log(chalk.gray(`  ⏩ Skipping ${candidate}: fast-track workflow`));
-          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;
       }
     }
 
@@ -189,13 +203,15 @@ export async function advancePhaseCommand(feature, options = {}) {
 
   // === GATE 2: Approval Gate Check ===
   // Check if current phase requires approval before advancing
-  const approvalGateMap = {
-    'design': 'design',
-    'tasks': 'tasks',
-    'uiux': 'uiux'
-  };
-
-  const requiredGate = approvalGateMap[currentPhase];
+  // 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);
 
@@ -206,6 +222,7 @@ export async function advancePhaseCommand(feature, options = {}) {
         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})`));
@@ -245,9 +262,10 @@ export async function advancePhaseCommand(feature, options = {}) {
   // === GATE 4: Content Validation ===
   // Validate spec.md and contracts.cs when advancing from design phase
   if (currentPhase === 'design' && (nextPhase === 'clarify' || nextPhase === 'tasks')) {
-    // Check spec.md structure and content
-    if (featureData.outputs?.spec?.created) {
-      const specContentValidation = validateSpecContent(featureData.outputs.spec.path);
+    // 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:'));
@@ -294,8 +312,9 @@ export async function advancePhaseCommand(feature, options = {}) {
   // === GATE 5: Tasks Content Validation ===
   // Validate tasks.md structure when advancing to implement
   if (currentPhase === 'tasks' && nextPhase === 'implement') {
-    if (featureData.outputs?.tasks?.created) {
-      const tasksContentValidation = validateTasksContent(featureData.outputs.tasks.path);
+    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:'));
@@ -318,6 +337,19 @@ export async function advancePhaseCommand(feature, options = {}) {
     }
   }
 
+  // === GATE 6: Clarifications Required ===
+  // When advancing FROM clarify, clarifications.md must exist.
+  // This enforces that morph:phase-clarify was actually run (not just skipped).
+  if (currentPhase === 'clarify') {
+    const clarPath = join(process.cwd(), '.morph', 'features', feature, '1-design', 'clarifications.md');
+    if (!existsSync(clarPath)) {
+      console.log(chalk.red('\n✗ Cannot advance from clarify — clarifications.md is missing'));
+      console.log(chalk.yellow('  Run the phase-clarify skill first: /morph:phase-clarify'));
+      console.log(chalk.gray('  Output expected at: .morph/features/' + feature + '/1-design/clarifications.md\n'));
+      process.exit(1);
+    }
+  }
+
   // Gate: Check design system when advancing to implement with UI agents
   if (nextPhase === 'implement') {
     const gateResult = designSystemGate(feature, process.cwd());
@@ -345,6 +377,40 @@ export async function advancePhaseCommand(feature, options = {}) {
     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)
@@ -369,6 +435,9 @@ export async function advancePhaseCommand(feature, options = {}) {
     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
@@ -407,15 +476,23 @@ function getPhaseGuidance(phase, feature) {
       'Provide layout references and preferences',
       'Review wireframes before proceeding'
     ],
-    'design': [
-      `Resume spec pipeline: /morph-proposal ${feature}`,
-      'Review DECISION POINTS carefully',
-      'Approve spec.md and contracts.cs'
-    ],
+    '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)'
+      ];
+    })(),
     'clarify': [
       `Resume spec pipeline: /morph-proposal ${feature}`,
       'Resolve edge cases and unknowns'
     ],
+    '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',
@@ -428,7 +505,7 @@ function getPhaseGuidance(phase, feature) {
     ],
     'sync': [
       'Review decisions.md for standards to promote',
-      `Sync: morph-spec sync --path ${getOutputPath(feature, 'decisions')}`
+      `Decisions file: ${getOutputPath(feature, 'decisions')}`
     ]
   };
 
@@ -466,7 +543,7 @@ function designSystemGate(feature, projectPath = '.') {
       '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. Auto-generate: morph-spec generate design-system (scans existing CSS)',
+      '  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} blazor-builder`
@@ -475,49 +552,36 @@ function designSystemGate(feature, projectPath = '.') {
 }
 
 /**
- * Emit Tier-4 validation dispatch block after phase advance.
- * Outputs a JSON block listing active Tier-4 validators for the LLM to dispatch
- * as read-only subagents before proceeding to implementation.
+ * 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} featureName
- * @param {string} phase
- * @param {string} cwd
+ * @param {string} nextPhase - The phase being advanced into
+ * @param {string} cwd - Project root path (for locating phases.json)
  */
-async function emitValidatorDispatch(featureName, phase, cwd) {
+async function emitSkillDispatch(nextPhase, cwd) {
   try {
-    const { buildDispatchConfig } = await import('../agents/dispatch-agents.js');
-    const config = await buildDispatchConfig(cwd, featureName, phase, { mode: 'validate' });
-    const validators = config.agents?.filter(a => a.tier === 4);
-    if (!validators || validators.length === 0) return;
-
-    const agentsPath = join(__dirname, '../../../framework/agents.json');
-    const agentsData = JSON.parse(readFileSync(agentsPath, 'utf8'));
-    const allAgents = agentsData.agents || {};
-
-    const validatorEntries = validators.map(v => {
-      const agentData = allAgents[v.id];
-      return {
-        id: v.id,
-        title: v.title,
-        severity: agentData?.hook_behavior?.severity || 'error',
-        blocksOnFail: agentData?.hook_behavior?.blocks_on_fail ?? true,
-        checks: agentData?.hook_behavior?.validates || [],
-        taskPrompt: v.taskPrompt
-      };
-    });
+    // 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 = {
-      validationRequired: true,
-      phase,
-      feature: featureName,
-      validators: validatorEntries,
-      instruction: 'Dispatch these validators as READ-ONLY subagents before continuing. Each must output { "passed": boolean, "issues": [] }. Blocking validators (blocksOnFail: true) must pass before marking phase complete.'
+      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--- VALIDATION DISPATCH ---'));
+    console.log(chalk.cyan('\n--- SKILL DISPATCH ---'));
     console.log(JSON.stringify(dispatch, null, 2));
-    console.log(chalk.cyan('--- END VALIDATION DISPATCH ---\n'));
+    console.log(chalk.cyan('--- END SKILL DISPATCH ---\n'));
   } catch {
     // Non-blocking — fail silently
   }

package/src/commands/state/approve.js

@@ -25,7 +25,7 @@ export async function unapproveCommand(featureName, gateName, options = {}) {
       return;
     }
 
-    setApprovalGate(featureName, gateName, false, {
+    await setApprovalGate(featureName, gateName, false, {
       revokedBy: options.revoker || process.env.USER || process.env.USERNAME || 'user',
       revokedAt: new Date().toISOString(),
       reason: options.reason
@@ -85,7 +85,7 @@ export async function approveCommand(featureName, gateName, options = {}) {
     }
 
     // Set approval
-    setApprovalGate(featureName, gateName, true, {
+    await setApprovalGate(featureName, gateName, true, {
       approvedBy: options.approver || process.env.USER || process.env.USERNAME || 'user',
       approvedAt: new Date().toISOString(),
       notes: options.notes

package/src/commands/state/index.js

@@ -1,8 +1,7 @@
-/**
- * State Management Commands
- */
-export { stateCommand } from './state.js';
-export { advancePhaseCommand } from './advance-phase.js';
-export { approveCommand, unapproveCommand, approvalStatusCommand } from './approve.js';
-export { validatePhaseCommand } from './validate-phase.js';
-export { phaseRunCommand } from './phase-runner.js';
+/**
+ * State Management Commands
+ */
+export { stateCommand } from './state.js';
+export { advancePhaseCommand } from './advance-phase.js';
+export { approveCommand, unapproveCommand, approvalStatusCommand } from './approve.js';
+export { phaseRunCommand } from './phase-runner.js';

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

@@ -23,7 +23,7 @@
 
 import chalk from 'chalk';
 import { join } from 'path';
-import { checkPhaseEligibility, computePassRate } from '../../lib/phase-chain/eligibility-checker.js';
+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';

package/src/commands/state/state.js

@@ -11,6 +11,36 @@ import { logger } from '../../utils/logger.js';
 import * as StateManager from '../../core/state/state-manager.js';
 import { derivePhase } from '../../core/state/state-manager.js';
 
+// ============================================================================
+// 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, setup, clarify, 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
 // ============================================================================
@@ -174,10 +204,30 @@ async function setCommand(featureName, key, value, options) {
   }
 
   try {
-    // Warn when bypassing the validated phase advance flow
+    // Guard: block protected phases unless --force is explicitly passed
     if (key === 'phase') {
-      logger.warn(`Direct phase override — all validation gates will be bypassed.`);
-      logger.dim(`  Recommended: morph-spec phase advance ${featureName}`);
+      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/, 1-design/, 4-tasks/, 5-implement/). This sets a state.json`);
+        logger.dim(`  override used only for lightweight phases (setup, clarify, sync).`);
+        logger.dim(`  Recommended: morph-spec phase advance ${featureName}`);
+      }
       logger.blank();
     }
 
@@ -328,13 +378,18 @@ async function markOutputCommand(featureName, outputType, options) {
     logger.dim('  Usage: morph-spec state mark-output <feature> <output-type>');
     logger.blank();
     logger.dim('  Valid types:');
-    logger.dim('    Standard: proposal, spec, contracts, tasks, decisions, recap');
-    logger.dim('    UI/UX:    uiDesignSystem, uiMockups, uiComponents, uiFlows');
+    logger.dim('    Proposal:  proposal');
+    logger.dim('    Design:    schemaAnalysis, spec, contracts, contractsVsa, decisions');
+    logger.dim('    Clarify:   clarifications');
+    logger.dim('    Tasks:     tasks');
+    logger.dim('    UI/UX:     uiDesignSystem, uiMockups, uiComponents, uiFlows');
+    logger.dim('    Implement: recap');
     logger.blank();
-    logger.dim('  Note: UI types also accept kebab-case (e.g., ui-design-system)');
+    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);

package/src/commands/task/expand.js

@@ -0,0 +1,100 @@
+/**
+ * MORPH-SPEC Task Expand Command
+ *
+ * Expands a task into sub-tasks for low-impact scope escalation.
+ * The original task gets status "expanded" and sub-tasks are appended to taskList.
+ *
+ * Usage:
+ *   morph-spec task expand <feature> <task-id> --into "T017a: Title" "T017b: Title"
+ */
+
+import chalk from 'chalk';
+import { loadState, saveState } from '../../core/state/state-manager.js';
+
+/**
+ * Parse a sub-task string "T017a: Title" into { id, title }.
+ */
+function parseSubTask(str) {
+  const match = str.match(/^(T\w+)\s*[:\-\u2014]\s*(.+)$/);
+  if (match) return { id: match[1], title: match[2].trim() };
+  // Fallback: use entire string as title, no id parseable
+  return { id: str.split(/\s/)[0], title: str };
+}
+
+/**
+ * Core expansion logic — exported for testing.
+ *
+ * @param {string} featureName
+ * @param {string} taskId - ID of the task to expand
+ * @param {string[]} subTaskStrings - Sub-task definitions ("T017a: Title")
+ * @returns {{ success: boolean, error?: string }}
+ */
+export function expandTask(featureName, taskId, subTaskStrings) {
+  const state = loadState();
+  const feature = state.features[featureName];
+
+  if (!feature) {
+    return { success: false, error: `Feature "${featureName}" not found` };
+  }
+
+  if (!feature.taskList) {
+    return { success: false, error: `No taskList found for "${featureName}"` };
+  }
+
+  const task = feature.taskList.find(t => t.id === taskId);
+  if (!task) {
+    return { success: false, error: `Task "${taskId}" not found in taskList` };
+  }
+
+  if (task.status === 'done' || task.status === 'completed') {
+    return { success: false, error: `Task "${taskId}" is already completed — cannot expand` };
+  }
+
+  // Parse sub-tasks
+  const subTasks = subTaskStrings.map(parseSubTask);
+  const subTaskIds = subTasks.map(s => s.id);
+
+  // Mark original as expanded
+  task.status = 'expanded';
+  task.subTasks = subTaskIds;
+  task.expandedAt = new Date().toISOString();
+
+  // Append sub-tasks to taskList
+  for (const sub of subTasks) {
+    feature.taskList.push({
+      id: sub.id,
+      title: sub.title,
+      status: 'pending',
+      dependencies: [],
+      files: [],
+      checkpoint: null,
+      parentTask: taskId
+    });
+  }
+
+  feature.updatedAt = new Date().toISOString();
+  saveState(state);
+
+  return { success: true, subTaskIds };
+}
+
+/**
+ * CLI command handler
+ */
+export async function taskExpandCommand(feature, taskId, options) {
+  if (!options.into || options.into.length === 0) {
+    console.error(chalk.red('--into is required with at least one sub-task'));
+    process.exit(1);
+  }
+
+  const result = expandTask(feature, taskId, options.into);
+
+  if (!result.success) {
+    console.error(chalk.red(`\n  ${result.error}`));
+    process.exit(1);
+  }
+
+  console.log(chalk.green(`\n  Task ${taskId} expanded into ${result.subTaskIds.length} sub-tasks:`));
+  result.subTaskIds.forEach(id => console.log(chalk.gray(`    - ${id}`)));
+  console.log('');
+}