@polymorphism-tech/morph-spec 4.9.0 → 4.10.1

package/src/commands/scope/escalate.js

@@ -0,0 +1,215 @@
+/**
+ * MORPH-SPEC Scope Escalate Command
+ *
+ * Handles mid-implementation scope discovery by analyzing impact,
+ * regressing phase or expanding tasks, and creating an audit trail.
+ *
+ * Usage:
+ *   morph-spec scope escalate <feature> --task <id> --reason "..."
+ *   morph-spec scope escalate <feature> --task <id> --reason "..." --dry-run
+ *   morph-spec scope escalate <feature> --task <id> --reason "..." --target design
+ */
+
+import chalk from 'chalk';
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'fs';
+import { join } from 'path';
+import { loadState, saveState } from '../../core/state/state-manager.js';
+import { analyzeImpact } from '../../lib/scope/impact-analyzer.js';
+
+/**
+ * Core escalation logic — exported for testing.
+ *
+ * @param {string} featureName
+ * @param {Object} options
+ * @param {string} options.task - Trigger task ID
+ * @param {string} options.reason - Reason for escalation
+ * @param {string} [options.target] - Override target phase
+ * @param {boolean} [options.dryRun] - Don't execute, just recommend
+ * @returns {Promise<{ success: boolean, error?: string, recommendation?: Object }>}
+ */
+export async function escalateScope(featureName, options) {
+  const state = loadState();
+  const feature = state.features[featureName];
+
+  if (!feature) {
+    return { success: false, error: `Feature "${featureName}" not found in state.json` };
+  }
+
+  if (feature.phase !== 'implement') {
+    return { success: false, error: `Scope escalation only available during implement phase (current: ${feature.phase})` };
+  }
+
+  // Read tasks.md
+  const tasksPath = join(process.cwd(), '.morph', 'features', featureName, '4-tasks', 'tasks.md');
+  let tasksMd = '';
+  try {
+    tasksMd = readFileSync(tasksPath, 'utf-8');
+  } catch {
+    return { success: false, error: 'tasks.md not found' };
+  }
+
+  // Read spec.md (optional — not all features have it)
+  const specPath = join(process.cwd(), '.morph', 'features', featureName, '1-design', 'spec.md');
+  let specMd = '';
+  try { specMd = readFileSync(specPath, 'utf-8'); } catch { /* ok */ }
+
+  // Analyze impact
+  const analysis = analyzeImpact({
+    triggerTaskId: options.task,
+    tasksMd,
+    specMd,
+    reason: options.reason
+  });
+
+  // Apply target override
+  if (options.target) {
+    analysis.recommendation = `regress-${options.target}`;
+    analysis.targetPhase = options.target;
+    if (analysis.targetPhase === 'design') analysis.impact = 'high';
+    else if (analysis.targetPhase === 'tasks') analysis.impact = 'medium';
+  }
+
+  // Dry-run: return recommendation without modifying state
+  if (options.dryRun) {
+    return { success: true, recommendation: analysis };
+  }
+
+  // Build escalation record
+  const escId = `ESC-${String((feature.escalations?.length || 0) + 1).padStart(3, '0')}`;
+  const record = {
+    id: escId,
+    triggerTask: options.task,
+    reason: options.reason,
+    impact: analysis.impact,
+    action: analysis.recommendation,
+    affectedTasks: analysis.affectedTasks,
+    reviewedTasks: [],
+    targetPhase: analysis.targetPhase || 'tasks',
+    previousPhase: 'implement',
+    createdAt: new Date().toISOString(),
+    resolvedAt: null
+  };
+
+  // Execute based on recommendation
+  if (analysis.recommendation.startsWith('regress')) {
+    const targetPhase = analysis.targetPhase || 'tasks';
+
+    // Flag completed tasks as needsReview (supports both v2 'done' and v3 'completed')
+    if (feature.taskList) {
+      for (const task of feature.taskList) {
+        if (task.status === 'done' || task.status === 'completed') {
+          task.needsReview = true;
+        }
+      }
+    }
+
+    // Reset phase
+    feature.phase = targetPhase;
+
+    // Reset relevant approval gates
+    if (feature.approvalGates) {
+      if (targetPhase === 'tasks' && feature.approvalGates.tasks) {
+        feature.approvalGates.tasks = { approved: false, timestamp: null, approvedBy: null };
+      }
+      if (targetPhase === 'design') {
+        if (feature.approvalGates.design) {
+          feature.approvalGates.design = { approved: false, timestamp: null, approvedBy: null };
+        }
+        if (feature.approvalGates.tasks) {
+          feature.approvalGates.tasks = { approved: false, timestamp: null, approvedBy: null };
+        }
+      }
+    }
+  }
+
+  // Write escalation record to state
+  if (!feature.escalations) feature.escalations = [];
+  feature.escalations.push(record);
+  feature.updatedAt = new Date().toISOString();
+
+  saveState(state);
+
+  // Create/append escalation-log.md
+  writeEscalationLog(featureName, record);
+
+  return { success: true, recommendation: analysis, escalationId: escId };
+}
+
+/**
+ * Write escalation log entry to 4-tasks/escalation-log.md
+ */
+function writeEscalationLog(featureName, record) {
+  const logDir = join(process.cwd(), '.morph', 'features', featureName, '4-tasks');
+  mkdirSync(logDir, { recursive: true });
+  const logPath = join(logDir, 'escalation-log.md');
+
+  const doneTasks = record.reviewedTasks?.length > 0
+    ? record.reviewedTasks.join(', ')
+    : '(all completed tasks flagged)';
+
+  const entry = `
+## ${record.id} — ${record.createdAt.split('T')[0]}
+- **Trigger:** ${record.triggerTask}
+- **Discovery:** ${record.reason}
+- **Impact:** ${record.impact} (${record.affectedTasks.length} tasks affected: ${record.affectedTasks.join(', ')})
+- **Action:** ${record.action} → ${record.targetPhase} phase
+- **Affected completed tasks flagged for review:** ${doneTasks}
+`;
+
+  let existing = '';
+  try { existing = readFileSync(logPath, 'utf-8'); } catch { /* new file */ }
+
+  if (!existing) {
+    writeFileSync(logPath, `# Scope Escalation Log\n${entry}`);
+  } else {
+    writeFileSync(logPath, existing + entry);
+  }
+}
+
+/**
+ * CLI command handler
+ */
+export async function scopeEscalateCommand(feature, options) {
+  console.log(chalk.cyan('\n========================================'));
+  console.log(chalk.cyan('  MORPH-SPEC SCOPE ESCALATION'));
+  console.log(chalk.cyan('========================================\n'));
+
+  if (!options.task) {
+    console.error(chalk.red('--task <id> is required'));
+    process.exit(1);
+  }
+  if (!options.reason) {
+    console.error(chalk.red('--reason "..." is required'));
+    process.exit(1);
+  }
+
+  const result = await escalateScope(feature, options);
+
+  if (!result.success) {
+    console.error(chalk.red(`\n  ${result.error}`));
+    process.exit(1);
+  }
+
+  const rec = result.recommendation;
+  console.log(chalk.gray('Trigger task:'), rec.triggerTask);
+  console.log(chalk.gray('Impact:'), rec.impact);
+  console.log(chalk.gray('Affected tasks:'), rec.affectedTasks.join(', '));
+  console.log(chalk.gray('Recommendation:'), rec.recommendation);
+  if (rec.targetPhase) console.log(chalk.gray('Target phase:'), rec.targetPhase);
+
+  if (options.dryRun) {
+    console.log(chalk.cyan('\n  Dry-run — no changes made'));
+    process.exit(2);
+  }
+
+  if (rec.recommendation === 'expand') {
+    console.log(chalk.green(`\n  Escalation ${result.escalationId} recorded (low impact)`));
+    console.log(chalk.yellow(`  Action: Use task expand to split the task:`));
+    console.log(chalk.gray(`    morph-spec task expand ${feature} ${options.task} --into "ID: Title" ...`));
+  } else {
+    console.log(chalk.green(`\n  Escalation ${result.escalationId} executed`));
+    console.log(chalk.yellow(`  Phase regressed to: ${rec.targetPhase || 'tasks'}`));
+  }
+  console.log(chalk.gray(`  Escalation log: .morph/features/${feature}/4-tasks/escalation-log.md`));
+  console.log('');
+}

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

@@ -16,18 +16,19 @@ import { detectDesignSystem, hasUIAgentsActive } from '../../lib/detectors/desig
 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.
@@ -36,6 +37,7 @@ const PHASE_ORDER = ['proposal', 'setup', 'uiux', 'design', 'clarify', 'tasks',
  */
 export const APPROVAL_GATE_MAP = {
   'design': 'design',
+  'plan': 'plan',
   'tasks': 'tasks',
   'uiux': 'uiux'
 };
@@ -78,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
@@ -332,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());
@@ -470,6 +488,11 @@ function getPhaseGuidance(phase, feature) {
       `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',
@@ -528,55 +551,6 @@ 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.
- * Non-blocking — fails silently.
- *
- * @param {string} featureName
- * @param {string} phase
- * @param {string} cwd
- */
-async function emitValidatorDispatch(featureName, phase, 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
-      };
-    });
-
-    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.'
-    };
-
-    console.log(chalk.cyan('\n--- VALIDATION DISPATCH ---'));
-    console.log(JSON.stringify(dispatch, null, 2));
-    console.log(chalk.cyan('--- END VALIDATION DISPATCH ---\n'));
-  } catch {
-    // Non-blocking — fail silently
-  }
-}
-
 /**
  * Emit a SKILL DISPATCH block when advancing to a phase that has requiredSkills.
  * Outputs structured JSON for the LLM to read and follow.

package/src/commands/state/state.js

@@ -224,7 +224,7 @@ async function setCommand(featureName, key, value, options) {
       } 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/, 3-tasks/, 4-implement/). This sets a state.json`);
+        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}`);
       }

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('');
+}

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

@@ -26,17 +26,18 @@ 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: '2-clarify',   phase: 'clarify',   protected: false },
+  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' },
-  tasks:         { filename: 'tasks.md',            phaseDir: '3-tasks',     phase: 'tasks',     protected: true,  approvalGate: 'tasks' },
+  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 },
-  recap:         { filename: 'recap.md',            phaseDir: '4-implement', phase: 'implement', protected: false },
+  recap:         { filename: 'recap.md',            phaseDir: '5-implement', phase: 'implement', protected: false },
 };
 
 // ============================================================================

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

@@ -14,7 +14,8 @@ const VALID_TRANSITIONS = {
   'setup': ['uiux', 'design'], // Can skip UI/UX if no frontend
   'uiux': ['design'],
   'design': ['clarify'],
-  'clarify': ['tasks'],
+  'clarify': ['plan'],
+  'plan': ['tasks'],
   'tasks': ['implement'],
   'implement': ['sync', 'archived'], // Can skip sync
   'sync': ['archived']
@@ -29,9 +30,10 @@ const PHASE_NAMES = {
   '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)',
+  'plan': 'Plan (Phase 4)',
+  'tasks': 'Tasks (Phase 5)',
+  'implement': 'Implement (Phase 6)',
+  'sync': 'Sync (Phase 7)',
   'archived': 'Archived'
 };
 
@@ -124,6 +126,7 @@ export function getPhaseSequence() {
     'uiux',     // optional
     'design',
     'clarify',
+    'plan',
     'tasks',
     'implement',
     'sync',     // optional

package/src/core/state/state-manager.js

@@ -27,12 +27,13 @@ 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' | 'uiux' | 'design' | 'proposal' | 'setup'
+ * @returns {string} Phase name: 'implement' | 'tasks' | 'plan' | 'uiux' | 'design' | 'proposal' | 'setup'
  */
 export function derivePhase(featurePath) {
   const phaseMap = [
-    ['4-implement', 'implement'],
-    ['3-tasks', 'tasks'],
+    ['5-implement', 'implement'],
+    ['4-tasks', 'tasks'],
+    ['3-plan', 'plan'],
     ['2-ui', 'uiux'],
     ['1-design', 'design'],
     ['0-proposal', 'proposal'],