@polymorphism-tech/morph-spec 4.21.0 → 5.0.1

package/bin/task-manager.js

@@ -1,1036 +0,0 @@
-#!/usr/bin/env node
-
-/**
- * MORPH-SPEC Task Manager (Simplified — Native-First)
- *
- * Validation gates for task completion, checkpoints, and state persistence.
- * Progress tracking and dependency management are handled by Claude Code native tasks.
- */
-
-import { fileURLToPath } from 'url';
-import { join, dirname } from 'path';
-import { access } from 'fs/promises';
-import { execSync } from 'child_process';
-import chalk from 'chalk';
-
-import { loadState, saveState, resolveAgentForTask, derivePhase, withStateLock } from '../src/core/state/state-manager.js';
-import { ensureTaskList, syncCounters } from '../src/lib/tasks/task-parser.js';
-import { isTestTask, isInfrastructureTask } from '../src/lib/tasks/task-classifier.js';
-import { runTestSuite } from '../src/lib/tasks/test-runner.js';
-
-const __filename = fileURLToPath(import.meta.url);
-const __dirname = dirname(__filename);
-
-// ============================================================================
-// Breaking-Change Detection
-// ============================================================================
-
-/**
- * Detect potentially broken consumers of recently removed exports.
- *
- * Strategy:
- *   1. Parse `git diff HEAD` (staged + unstaged) for removed export declarations.
- *   2. Use `git grep` to find files that still reference each removed symbol.
- *   3. Return warnings (non-blocking) so Claude Code can review before marking done.
- *
- * Returns null when git is unavailable, not in a repo, or no removed exports found.
- * Returns [] when removed exports exist but no consumers found.
- * Returns [{export, consumers[]}] when consumers are found.
- *
- * @returns {Promise<Array<{export: string, consumers: string[]}>|null>}
- */
-export async function detectBreakingChanges(opts = {}) {
-  try {
-    const exec = opts._execSync ?? execSync;
-    const cwd = opts._cwd ?? process.cwd();
-    const execOpts = { cwd, stdio: ['pipe', 'pipe', 'pipe'], maxBuffer: 5 * 1024 * 1024 };
-
-    // Collect diff from staged + unstaged changes in source files
-    let diff = '';
-    const diffPatterns = ['*.ts', '*.tsx', '*.js', '*.jsx', '*.cs'];
-    for (const flag of ['--cached', '']) {
-      try {
-        const args = ['git', 'diff', '--unified=0', flag, '--', ...diffPatterns].filter(Boolean);
-        diff += exec(args.join(' '), execOpts).toString();
-      } catch {
-        // git not available or no changes — continue
-      }
-    }
-
-    if (!diff.trim()) return null;
-
-    // Extract source files touched by the diff
-    const sourceFiles = new Set();
-    const diffHeaderRe = /^diff --git a\/(.+?) b\//gm;
-    let m;
-    while ((m = diffHeaderRe.exec(diff)) !== null) sourceFiles.add(m[1]);
-
-    // Extract removed export symbol names (lines starting with -)
-    const removedExports = new Set();
-    const exportRe = /^-\s*export\s+(?:(?:default\s+)?(?:async\s+)?function|const|let|class|interface|type|enum)\s+(\w+)/gm;
-    let match;
-    while ((match = exportRe.exec(diff)) !== null) {
-      removedExports.add(match[1]);
-    }
-
-    if (removedExports.size === 0) return null;
-
-    // For each removed symbol, check if any tracked file still imports/uses it
-    const warnings = [];
-    const defaultExcludes = [':!.morph/archive/', ':!.morph/framework/', ':!node_modules/'];
-    const pathspecs = [...diffPatterns, ...defaultExcludes];
-
-    for (const sym of removedExports) {
-      try {
-        const grepCmd = ['git', 'grep', '-l', `"${sym}"`, '--', ...pathspecs].join(' ');
-        const result = exec(grepCmd, execOpts).toString().trim();
-        if (result) {
-          const consumers = result.split('\n').filter(Boolean).filter(f => !sourceFiles.has(f));
-          if (consumers.length > 0) {
-            warnings.push({ export: sym, consumers });
-          }
-        }
-      } catch {
-        // No match found — safe
-      }
-    }
-
-    return warnings;
-  } catch {
-    return null; // Non-blocking: any unexpected error → skip detection
-  }
-}
-
-// ============================================================================
-// TaskManager
-// ============================================================================
-
-class TaskManager {
-  /**
-   * Complete one or more tasks (runs validation first)
-   * @param {string} featureName - Feature name
-   * @param {string[]} taskIds - Task IDs to complete
-   * @param {Object} options - Options
-   * @param {boolean} options.skipValidation - Skip code validation (budget-limited)
-   * @param {string}  [options.reason] - Reason for skipping validation (required with skipValidation)
-   * @param {string}  [options.note] - Deviation note explaining why task was done differently than planned
-   * @param {boolean} options.dryRun - Dry run (no state changes)
-   * @param {Function} [options._runTestSuite] - Inject a mock runTestSuite for testing
-   */
-  async completeTasks(featureName, taskIds, options = {}) {
-    const state = loadState();
-    const feature = state.features[featureName];
-
-    if (!feature) {
-      throw new Error(`Feature '${featureName}' not found in state.json`);
-    }
-
-    const taskList = await ensureTaskList(feature, featureName);
-
-    if (taskList.length === 0) {
-      const tasksPath = join(process.cwd(), `.morph/features/${featureName}/4-tasks/tasks.md`);
-      const tasksExist = await access(tasksPath).then(() => true).catch(() => false);
-      if (!tasksExist) {
-        throw new Error(`No tasks found for '${featureName}' — tasks.md not generated yet.\n  Complete the tasks phase first: run /phase-tasks`);
-      }
-      throw new Error(`tasks.md found but no tasks could be parsed for '${featureName}'.\n  Ensure tasks use the format: ### T001 — Title  or  ### T001: Title`);
-    }
-
-    // Persist initial taskList so counters are visible in `state get` even if
-    // validation fails later and the completion save never runs.
-    syncCounters(feature);
-    feature.updatedAt = new Date().toISOString();
-    saveState(state);
-
-    const results = [];
-    const tasksToComplete = [];
-
-    for (const taskId of taskIds) {
-      const task = taskList.find(t => t.id === taskId);
-
-      if (!task) {
-        console.error(chalk.red(`❌ Task ${taskId} not found (available: ${taskList.map(t => t.id).join(', ')})`));
-        continue;
-      }
-
-      if (task.status === 'completed') {
-        console.log(chalk.yellow(`⚠️  Task ${taskId} already completed`));
-        continue;
-      }
-
-      // Auto-start if not already in_progress (BUG-007)
-      if (task.status !== 'in_progress') {
-        task.status = 'in_progress';
-        task.startedAt = new Date().toISOString();
-        const agentId = resolveAgentForTask(featureName, task.id);
-        if (agentId) task.assignedAgent = agentId;
-        console.log(chalk.gray(`  ▶ Auto-started ${task.id} (was ${task.status || 'pending'})`));
-      }
-
-      tasksToComplete.push(task);
-    }
-
-    // ─── Test Task Guard ────────────────────────────────────────────────────────
-    // When any of the tasks being completed is a test/validation task (e.g.
-    // "Testes e Validação"), run the project's test suite BEFORE code validation.
-    // The guard is skipped when --skip-validation or --dry-run is active.
-    runTestGuard(tasksToComplete, process.cwd(), options);
-
-    // ─── Skip-Validation Budget Enforcement ───────────────────────────────────
-    if (options.skipValidation && tasksToComplete.length > 0 && !options.dryRun) {
-      // Require --reason with minimum 5 characters
-      if (!options.reason || options.reason.trim().length < 5) {
-        console.error(chalk.red('❌ --skip-validation requires --reason <text> (minimum 5 characters)'));
-        console.error(chalk.gray('   Example: morph-spec task done feat T001 --skip-validation --reason "CSS-only change, no logic"'));
-        process.exit(1);
-      }
-
-      // Check budget
-      const budget = computeSkipBudget(feature);
-      const used = (feature.skipValidationLog || []).length;
-      if (used >= budget) {
-        console.error(chalk.red(`❌ Skip-validation budget exhausted (${used}/${budget})`));
-        console.error(chalk.gray('   All remaining tasks must pass Tier-4 validation.'));
-        console.error(chalk.gray('   Budget formula: min(5, ceil(totalTasks × 0.20))'));
-        process.exit(1);
-      }
-
-      console.log(chalk.yellow(`⚠ --skip-validation: using budget (${used + tasksToComplete.length}/${budget})`));
-    }
-
-    // Run validation BEFORE marking tasks as complete
-    const allInfra = tasksToComplete.every(t => isInfrastructureTask(t.title));
-    if (tasksToComplete.length > 0 && !options.skipValidation) {
-      const validationOpts = { mode: 'light' };
-      if (allInfra) validationOpts.skipContracts = true;
-      const validationResult = await this.runValidation(featureName, validationOpts);
-      if (options.dryRun) {
-        console.log(chalk.cyan('\n  ℹ️  Dry-run — tasks NOT marked as complete'));
-        return [];
-      }
-      // Score-based retry decision (falls back to pass/fail if scores unavailable)
-      const scoreAction = validationResult.scores?.action;
-      const shouldFail = scoreAction ? scoreAction !== 'approve' : !validationResult.passed;
-
-      if (shouldFail) {
-        // Reload state to ensure we have the latest (may have been modified by validation)
-        const currentState = loadState();
-        const currentFeature = currentState.features[featureName];
-        if (currentFeature) {
-          // Score-based escalation: 'escalate' action blocks immediately
-          const forceEscalate = scoreAction === 'escalate';
-
-          for (const task of tasksToComplete) {
-            this.persistValidationHistory(currentFeature, task.id, validationResult, forceEscalate);
-          }
-          saveState(currentState);
-
-          // Check escalation status
-          const blockedTasks = tasksToComplete.filter(t => {
-            const hist = currentFeature.validationHistory?.[t.id];
-            return hist?.status === 'blocked';
-          });
-          if (blockedTasks.length > 0) {
-            const scoreInfo = validationResult.scores ? ` (score: ${validationResult.scores.score}/10)` : '';
-            console.error(chalk.red(`\n⛔ ESCALATION — Task(s) ${blockedTasks.map(t => t.id).join(', ')}${scoreInfo}`));
-            if (forceEscalate) {
-              console.error(chalk.red('   Score below retry threshold — immediate escalation'));
-            } else {
-              console.error(chalk.red('   Failed 3 times — human review required'));
-            }
-            console.error(chalk.red('   Mark resolved with: morph-spec state set <feature> validationHistory.<taskId>.status passed'));
-          } else {
-            const attempt = currentFeature.validationHistory?.[tasksToComplete[0]?.id]?.attempt || 1;
-            const scoreInfo = validationResult.scores ? ` | score: ${validationResult.scores.score}/10` : '';
-            console.error(chalk.red(`\n❌ Validation failed (attempt ${attempt}/3${scoreInfo}) — tasks NOT marked as complete`));
-            console.log(chalk.gray('   Fix the issues above, then run task done again'));
-            if (attempt >= 2) {
-              console.log(chalk.yellow(`   ⚠️  Next failure will escalate to human review`));
-            }
-          }
-        } else {
-          console.error(chalk.red('\n❌ Validation failed — tasks NOT marked as complete'));
-          console.log(chalk.gray('   Fix the issues above, then run task done again'));
-        }
-        console.log(chalk.gray('   Or use --skip-validation to bypass (not recommended)\n'));
-        process.exit(1);
-      }
-
-      // Validation passed — always record passed status in validationHistory.
-      // Update in-place on `feature` (same object as state.features[featureName]) so
-      // the single saveState(state) at the end of the function persists everything
-      // atomically.  A separate saveState here would trigger a second renameSync on
-      // Windows, risking EPERM and leaving state.json without the task completions
-      // (the count bug), and would also be clobbered by the final save anyway.
-      if (!feature.validationHistory) feature.validationHistory = {};
-      for (const task of tasksToComplete) {
-        feature.validationHistory[task.id] = {
-          ...(feature.validationHistory[task.id] || {}),
-          status: 'passed',
-          updatedAt: new Date().toISOString(),
-        };
-      }
-    } else if (options.dryRun) {
-      console.log(chalk.cyan('\n  ℹ️  Dry-run — tasks NOT marked as complete (validation skipped)'));
-      return [];
-    } else if (shouldLogSkipValidationWarning(tasksToComplete, options.skipValidation, options.dryRun)) {
-      // Record skip in state: skipValidationLog + validationHistory
-      if (!feature.skipValidationLog) feature.skipValidationLog = [];
-      if (!feature.validationHistory) feature.validationHistory = {};
-      for (const task of tasksToComplete) {
-        feature.skipValidationLog.push({
-          taskId: task.id,
-          reason: options.reason,
-          timestamp: new Date().toISOString(),
-        });
-        feature.validationHistory[task.id] = {
-          ...(feature.validationHistory[task.id] || {}),
-          attempt: 0,
-          status: 'skipped',
-          reason: options.reason,
-          updatedAt: new Date().toISOString(),
-        };
-      }
-
-      console.log(chalk.yellow('\n⚠ --skip-validation: Tier-4 code validators bypassed — tasks will be marked complete without validation'));
-      console.log(chalk.gray('  Re-run without --skip-validation before committing.\n'));
-    }
-
-    // Breaking change detection (non-blocking warning)
-    if (tasksToComplete.length > 0 && !allInfra) {
-      const _detectBreaking = options._detectBreakingChanges ?? detectBreakingChanges;
-      const breakingChanges = await _detectBreaking();
-      if (breakingChanges && breakingChanges.length > 0) {
-        console.log(chalk.yellow('\n⚠️  BREAKING CHANGE DETECTION:'));
-        console.log(chalk.yellow('   Removed exports with active consumers found — review before completing:\n'));
-        for (const { export: sym, consumers } of breakingChanges) {
-          console.log(chalk.yellow(`   • "${sym}" removed — used by:`));
-          consumers.slice(0, 5).forEach(f => console.log(chalk.gray(`     - ${f}`)));
-          if (consumers.length > 5) {
-            console.log(chalk.gray(`     … and ${consumers.length - 5} more files`));
-          }
-        }
-        console.log(chalk.yellow('\n   Fix broken imports before the smoke test, or use --skip-validation to bypass.\n'));
-      }
-    }
-
-    // Mark tasks as completed with agent correlation
-    for (const task of tasksToComplete) {
-      task.status = 'completed';
-      task.completedAt = new Date().toISOString();
-
-      // Resolve agent from dispatch (falls back to 'claude')
-      const agentId = resolveAgentForTask(featureName, task.id);
-      task.completedBy = agentId || 'claude';
-
-      // Add deviation note if provided
-      if (options.note) {
-        if (!task.notes) task.notes = [];
-        task.notes.push({
-          text: options.note,
-          type: 'deviation',
-          addedAt: new Date().toISOString(),
-          addedBy: agentId || 'claude'
-        });
-      }
-
-      results.push(task);
-
-      console.log(chalk.green(`✅ Task ${task.id} completed!`));
-      if (options.note) {
-        console.log(chalk.gray(`   Note: ${options.note}`));
-      }
-
-      // Register checkpoint if task has one
-      if (task.checkpoint) {
-        this.registerCheckpoint(feature, task);
-      }
-    }
-
-    // Sync v3 counters
-    syncCounters(feature);
-
-    // Auto-checkpoint every 3 tasks (at exact multiples of 3, not after every task).
-    // Uses feature._lastAutoCheckpointNum to track which threshold already fired.
-    const activeTasks = taskList.filter(t => t.status !== 'expanded');
-    const completedCount = activeTasks.filter(t => t.status === 'completed').length;
-    if (completedCount > 0 && completedCount % 3 === 0) {
-      const checkpointNum = Math.floor(completedCount / 3);
-      const lastAutoNum = feature._lastAutoCheckpointNum || 0;
-      if (checkpointNum > lastAutoNum) {
-        const recentCompleted = this.getRecentCompleted(taskList, 3);
-        await this.autoCheckpoint(feature, recentCompleted, featureName);
-        feature._lastAutoCheckpointNum = checkpointNum;
-      }
-    }
-
-    // Persist state (atomic write via state-manager)
-    feature.updatedAt = new Date().toISOString();
-    saveState(state);
-
-    // Run TaskCompleted agent-teams hook for each completed task (non-blocking)
-    for (const task of results) {
-      try {
-        const { executeHook, formatHookResults } = await import('../src/lib/hooks/hook-executor.js');
-        const hookResult = await executeHook(process.cwd(), featureName, 'TaskCompleted', {
-          taskId: task.id
-        });
-        if (!hookResult.passed && hookResult.errors.length > 0) {
-          console.log(formatHookResults(hookResult, 'TaskCompleted'));
-        }
-      } catch {
-        // Hook executor unavailable — non-blocking
-      }
-    }
-
-    // Auto-generate metadata.json (for quick LLM access)
-    await this.generateMetadata(featureName, feature);
-
-    // Emit VALIDATION DISPATCH for PostToolUse hook (strategy 1 parsing).
-    // Skipped when --skip-validation is active (no validators needed).
-    if (!options.skipValidation && results.length > 0) {
-      try {
-        const { emitValidatorDispatch } = await import('../src/lib/validators/shared/emit-validator-dispatch.js');
-        const phase = feature.phase || 'implement';
-        await emitValidatorDispatch(featureName, phase, process.cwd());
-      } catch {
-        // Non-blocking
-      }
-    }
-
-    return results;
-  }
-
-  /**
-   * Run validation for a feature using the ValidationRunner (ESM dynamic import).
-   * Returns a structured result with per-validator breakdown for validationHistory.
-   *
-   * @param {string} featureName - Feature name
-   * @returns {{ passed: boolean, validators: Object, passRate: number }}
-   */
-  async runValidation(featureName, opts = {}) {
-    try {
-      console.log(chalk.cyan('\n🔍 Running code validation...'));
-
-      const { runValidation, formatValidationResults } = await import('../src/lib/validators/validation-runner.js');
-      const result = await runValidation('.', featureName, { verbose: true, ...opts });
-
-      formatValidationResults(result);
-
-      // Build structured validators map from result
-      const validators = {};
-      if (result.results && typeof result.results === 'object') {
-        for (const [name, vResult] of Object.entries(result.results)) {
-          const issues = (vResult.errors || []).map(e => ({
-            message: typeof e === 'string' ? e : (e.message || String(e)),
-            file: e.file,
-            line: e.line,
-            rule: e.rule,
-          }));
-          validators[name] = {
-            passed: vResult.passed ?? (issues.length === 0),
-            issues,
-          };
-        }
-      } else if (!result.passed && result.errors?.length > 0) {
-        // Flat format fallback — wrap as single 'validation' validator
-        validators['validation'] = {
-          passed: false,
-          issues: result.errors.map(e => ({
-            message: typeof e === 'string' ? e : (e.message || String(e)),
-            file: e.file,
-            line: e.line,
-            rule: e.rule || 'validation',
-          })),
-        };
-      }
-
-      const validatorEntries = Object.values(validators);
-      const passRate = validatorEntries.length > 0
-        ? validatorEntries.filter(v => v.passed).length / validatorEntries.length
-        : (result.passed ? 1.0 : 0.0);
-
-      return { passed: result.passed, validators, passRate, scores: result.scores || null };
-    } catch (error) {
-      // If validation runner fails to load, warn but don't block task completion.
-      // This is fail-open by design: a broken validator shouldn't block commits.
-      // Common cause: missing optional deps.
-      console.log(chalk.yellow(`\n⚠️  Validation skipped (${error.message})`));
-      console.log(chalk.gray(`   Run manually: morph-spec validate-feature ${featureName}`));
-      return { passed: true, validators: {}, passRate: 1.0, scores: null };
-    }
-  }
-
-  /**
-   * Persist a validation result to feature.validationHistory[taskId].
-   * Increments attempt counter and sets status to 'failed' or 'blocked' (attempt >= 3).
-   *
-   * @param {Object} feature - Mutable feature state object
-   * @param {string} taskId - Task ID
-   * @param {{ passed: boolean, validators: Object, passRate: number }} validationResult
-   */
-  persistValidationHistory(feature, taskId, validationResult, forceEscalate = false) {
-    if (!feature.validationHistory) {
-      feature.validationHistory = {};
-    }
-    const existing = feature.validationHistory[taskId] || { attempt: 0 };
-    const attempt = (existing.attempt || 0) + 1;
-    const status = forceEscalate ? 'blocked' : (attempt >= 3 ? 'blocked' : 'failed');
-
-    const entry = {
-      attempt,
-      validators: validationResult.validators || {},
-      passRate: validationResult.passRate || 0,
-      status,
-      updatedAt: new Date().toISOString(),
-    };
-
-    // Attach score data when available
-    if (validationResult.scores) {
-      entry.scores = {
-        score: validationResult.scores.score,
-        action: validationResult.scores.action,
-        breakdown: validationResult.scores.breakdown,
-      };
-    }
-
-    feature.validationHistory[taskId] = entry;
-  }
-
-  /**
-   * Register checkpoint (from task flag)
-   */
-  registerCheckpoint(feature, task) {
-    const checkpoint = {
-      id: task.checkpoint,
-      timestamp: new Date().toISOString(),
-      tasksCompleted: [task.id],
-      note: `Checkpoint: ${task.title}`,
-      passed: true  // reaching a named checkpoint means the task completed successfully
-    };
-
-    feature.checkpoints = feature.checkpoints || [];
-    feature.checkpoints.push(checkpoint);
-
-    console.log(chalk.magenta(`\n🎯 ${task.checkpoint} reached!`));
-  }
-
-  /**
-   * Auto-checkpoint every 3 tasks (includes validation summary)
-   */
-  async autoCheckpoint(feature, tasks, featureName) {
-    const tasksCompleted = feature.tasks?.completed || tasks.length;
-    const checkpointNum = Math.floor(tasksCompleted / 3);
-
-    console.log(chalk.magenta(`\n🔍 CHECKPOINT ${checkpointNum} - Running automated validation...`));
-
-    let checkpointResult = null;
-    let validationNote = '';
-
-    try {
-      const { runCheckpointHooks, shouldRunCheckpoint } = await import('../src/lib/checkpoints/checkpoint-hooks.js');
-
-      if (shouldRunCheckpoint(tasksCompleted, 3)) {
-        checkpointResult = await runCheckpointHooks(featureName, checkpointNum);
-
-        if (checkpointResult.passed) {
-          validationNote = ' | ✓ All validations passed';
-        } else {
-          validationNote = ` | ✗ ${checkpointResult.summary.errors} errors, ${checkpointResult.summary.warnings} warnings`;
-
-          const config = await this.loadCheckpointConfig();
-          if (config.checkpoints?.onFailure?.blockProgress && checkpointResult.summary.errors > 0) {
-            console.log(chalk.red('\n❌ Checkpoint FAILED - Fix violations before proceeding'));
-            throw new Error('Checkpoint validation failed');
-          }
-        }
-      }
-    } catch (error) {
-      if (error.message === 'Checkpoint validation failed') {
-        throw error;
-      }
-      // Fallback to old validation if checkpoint-hooks not available
-      console.log(chalk.yellow('⚠️  Checkpoint hooks not available, using legacy validation'));
-      try {
-        const { runValidation } = await import('../src/lib/validators/validation-runner.js');
-        const result = await runValidation('.', featureName, { verbose: false, mode: 'full' });
-        validationNote = result.passed
-          ? ' | Validation: PASSED'
-          : ` | Validation: ${result.errors} errors, ${result.warnings} warnings`;
-
-        // Persist checkpoint validation results to disk
-        try {
-          const { persistCheckpointValidation } = await import('../src/lib/validators/checkpoint-persistence.js');
-          persistCheckpointValidation(process.cwd(), featureName, {
-            checkpointNum,
-            timestamp: new Date().toISOString(),
-            passed: result.passed,
-            validators: result.results || {},
-            summary: result.summary || '',
-          });
-        } catch {
-          // Non-blocking
-        }
-      } catch {
-        // No validation available
-      }
-    }
-
-    const checkpoint = {
-      id: `CHECKPOINT_AUTO_${Date.now()}`,
-      timestamp: new Date().toISOString(),
-      tasksCompleted: tasks.map(t => t.id),
-      note: `Auto-checkpoint: ${tasks.length} tasks completed${validationNote}`,
-      passed: checkpointResult?.passed ?? true,  // null checkpointResult means no validator ran → assume passed
-      validationResults: checkpointResult?.results || null
-    };
-
-    feature.checkpoints = feature.checkpoints || [];
-    feature.checkpoints.push(checkpoint);
-
-    if (checkpointResult?.passed) {
-      console.log(chalk.green(`\n✅ Checkpoint ${checkpointNum} PASSED`));
-    } else if (checkpointResult) {
-      console.log(chalk.yellow(`\n⚠️  Checkpoint ${checkpointNum} completed with warnings`));
-    } else {
-      console.log(chalk.magenta(`\n🎉 Auto-checkpoint ${checkpointNum} reached!`));
-    }
-  }
-
-  /**
-   * Load checkpoint configuration from llm-interaction.json
-   */
-  async loadCheckpointConfig() {
-    try {
-      const { readFile } = await import('fs/promises');
-      const configPath = join(process.cwd(), '.morph/config/llm-interaction.json');
-      const content = await readFile(configPath, 'utf-8');
-      return JSON.parse(content);
-    } catch {
-      return {
-        checkpoints: {
-          frequency: 3,
-          autoValidate: true,
-          onFailure: { blockProgress: false }
-        }
-      };
-    }
-  }
-
-  /**
-   * Auto-generate metadata.json after task completion
-   */
-  async generateMetadata(featureName, feature) {
-    try {
-      const config = await this.loadCheckpointConfig();
-
-      if (!config.metadata?.autoGenerate) {
-        return;
-      }
-
-      const { extractFeatureMetadata } = await import('../src/lib/generators/metadata-extractor.js');
-      const metadata = extractFeatureMetadata(feature);
-
-      const outputPath = join(process.cwd(), `.morph/features/${featureName}/metadata.json`);
-
-      const { mkdir, writeFile } = await import('fs/promises');
-      await mkdir(dirname(outputPath), { recursive: true });
-      await writeFile(outputPath, JSON.stringify(metadata, null, 2), 'utf-8');
-
-      console.log(chalk.gray(`   📊 Metadata updated: .morph/features/${featureName}/metadata.json`));
-    } catch (error) {
-      console.log(chalk.yellow(`   ⚠️  Metadata generation failed: ${error.message}`));
-    }
-  }
-
-  /**
-   * Get recently completed tasks (last N)
-   */
-  getRecentCompleted(tasks, count) {
-    const completed = tasks
-      .filter(t => t.status === 'completed' && t.completedAt)
-      .sort((a, b) => new Date(b.completedAt) - new Date(a.completedAt));
-
-    return completed.slice(0, count);
-  }
-
-  /**
-   * Start a task (mark as in_progress).
-   * Primarily serves as dispatch enforcement gate during implement phase.
-   */
-  async startTask(featureName, taskId) {
-    const state = loadState();
-    const feature = state.features[featureName];
-
-    if (!feature) {
-      throw new Error(`Feature '${featureName}' not found`);
-    }
-
-    // Dispatch enforcement gate: block task start in implement phase
-    // unless dispatch-agents has been run (recorded in dispatchLog)
-    const featurePath = join(process.cwd(), '.morph', 'features', featureName);
-    const currentPhase = feature.phase || derivePhase(featurePath);
-    if (currentPhase === 'implement') {
-      const hasImplementDispatch = Array.isArray(feature.dispatchLog) &&
-        feature.dispatchLog.some(entry => entry.phase === 'implement');
-      if (!hasImplementDispatch) {
-        console.error(chalk.red('\n✗ Cannot start task — agent dispatch not recorded for implement phase'));
-        console.error(chalk.yellow(
-          `\n  Run this command first:\n` +
-          `    morph-spec dispatch-agents ${featureName} implement\n\n` +
-          `  This configures typed specialist agents with enriched prompts,\n` +
-          `  task assignments, and quality standards for parallel execution.\n`
-        ));
-        process.exit(1);
-      }
-    }
-
-    const taskList = await ensureTaskList(feature, featureName);
-
-    if (taskList.length === 0) {
-      const tasksPath = join(process.cwd(), `.morph/features/${featureName}/4-tasks/tasks.md`);
-      const tasksExist = await access(tasksPath).then(() => true).catch(() => false);
-      if (!tasksExist) {
-        throw new Error(`No tasks found for '${featureName}' — tasks.md not generated yet.\n  Complete the tasks phase first: run /phase-tasks`);
-      }
-      throw new Error(`tasks.md found but no tasks could be parsed for '${featureName}'.\n  Ensure tasks use the format: ### T001 — Title  or  ### T001: Title`);
-    }
-
-    const task = taskList.find(t => t.id === taskId);
-
-    if (!task) {
-      throw new Error(`Task ${taskId} not found in '${featureName}' (${taskList.length} tasks available: ${taskList.map(t => t.id).join(', ')})`);
-    }
-
-    if (task.status === 'completed') {
-      console.log(chalk.yellow(`⚠️  Task ${taskId} already completed`));
-      return;
-    }
-
-    task.status = 'in_progress';
-    task.startedAt = new Date().toISOString();
-
-    // Agent correlation: resolve which agent is assigned this task from the latest dispatch
-    const agentId = resolveAgentForTask(featureName, taskId);
-    if (agentId) {
-      task.assignedAgent = agentId;
-    }
-
-    syncCounters(feature);
-    feature.updatedAt = new Date().toISOString();
-
-    saveState(state);
-
-    console.log(chalk.blue(`▶️  Task ${taskId} started: ${task.title}`));
-  }
-
-  /**
-   * Bulk-complete tasks with a single validation pass.
-   * @param {string} featureName
-   * @param {Object} opts
-   * @param {boolean} [opts.all] - Complete all pending tasks
-   * @param {string}  [opts.from] - Start of range (e.g. T001)
-   * @param {string}  [opts.to]   - End of range (e.g. T053)
-   * @param {string}  [opts.range] - Compact range string (e.g. T001..T082)
-   * @param {boolean} [opts.skipValidation]
-   * @param {boolean} [opts.dryRun]
-   */
-  async bulkCompleteTasks(featureName, opts = {}) {
-    const state = loadState();
-    const feature = state.features[featureName];
-    if (!feature) throw new Error(`Feature '${featureName}' not found in state.json`);
-
-    const taskList = await ensureTaskList(feature, featureName);
-    if (taskList.length === 0) throw new Error(`No tasks found for '${featureName}'`);
-
-    // Resolve task IDs from range options
-    let targetIds;
-    if (opts.all) {
-      targetIds = taskList.filter(t => t.status !== 'completed' && t.status !== 'expanded').map(t => t.id);
-    } else if (opts.from && opts.to) {
-      targetIds = this.expandRange(taskList, opts.from, opts.to);
-    } else if (opts.range && opts.range.includes('..')) {
-      const [from, to] = opts.range.split('..');
-      targetIds = this.expandRange(taskList, from.trim(), to.trim());
-    } else {
-      throw new Error('bulk-done requires --all, --from/--to, or a T001..T082 range argument');
-    }
-
-    console.log(chalk.cyan(`\n📦 Bulk-done: ${targetIds.length} task(s) targeted`));
-    await this.completeTasks(featureName, targetIds, { skipValidation: opts.skipValidation, reason: opts.reason, note: opts.note, dryRun: opts.dryRun });
-  }
-
-  /**
-   * Expand a task range like T001..T053 using zero-padded numeric IDs.
-   */
-  expandRange(taskList, from, to) {
-    const numOf = id => parseInt(id.replace(/\D/g, ''), 10);
-    const prefix = from.replace(/\d+$/, '');
-    const padLen = from.replace(prefix, '').length;
-    const fromNum = numOf(from);
-    const toNum   = numOf(to);
-    const ids = [];
-    for (let n = fromNum; n <= toNum; n++) {
-      ids.push(prefix + String(n).padStart(padLen, '0'));
-    }
-    return ids.filter(id => taskList.some(t => t.id === id));
-  }
-
-  /**
-   * Add a note to a task (deviation, context, or blocker-resolved)
-   * @param {string} featureName - Feature name
-   * @param {string} taskId - Task ID
-   * @param {string} text - Note text
-   * @param {string} [type='deviation'] - Note type: deviation | context | blocker-resolved
-   */
-  async annotateTask(featureName, taskId, text, type = 'deviation', markDone = false) {
-    const validTypes = ['deviation', 'context', 'blocker-resolved'];
-    if (!validTypes.includes(type)) {
-      throw new Error(`Invalid note type '${type}'. Valid types: ${validTypes.join(', ')}`);
-    }
-
-    const state = loadState();
-    const feature = state.features[featureName];
-    if (!feature) throw new Error(`Feature '${featureName}' not found`);
-
-    const taskList = await ensureTaskList(feature, featureName);
-    const task = taskList.find(t => t.id === taskId);
-    if (!task) throw new Error(`Task ${taskId} not found in '${featureName}'`);
-
-    if (!task.notes) task.notes = [];
-    task.notes.push({
-      text,
-      type,
-      addedAt: new Date().toISOString(),
-      addedBy: 'user'
-    });
-
-    if (markDone && task.status !== 'completed') {
-      if (task.status !== 'in_progress') {
-        task.status = 'in_progress';
-        task.startedAt = new Date().toISOString();
-      }
-      task.status = 'completed';
-      task.completedAt = new Date().toISOString();
-      syncCounters(feature);
-    }
-
-    feature.updatedAt = new Date().toISOString();
-    saveState(state);
-
-    console.log(chalk.green(`Added ${type} note to ${taskId}`));
-    console.log(chalk.gray(`  "${text}"`));
-    if (markDone && task.status === 'completed') {
-      console.log(chalk.green(`✅ Task ${taskId} marked as completed`));
-    }
-  }
-}
-
-// ============================================================================
-// CLI entry point
-// ============================================================================
-
-async function main() {
-  const args = process.argv.slice(2);
-  const command = args[0];
-
-  const manager = new TaskManager();
-
-  try {
-    switch (command) {
-      case 'done':
-      case 'complete': {
-        const skipValidation = args.includes('--skip-validation');
-        const skipBuild = args.includes('--skip-build');
-        const dryRun = args.includes('--dry-run');
-        const reasonIdx = args.indexOf('--reason');
-        const reason = reasonIdx !== -1 ? args[reasonIdx + 1] : null;
-        const noteIdx = args.indexOf('--note');
-        const note = noteIdx !== -1 ? args[noteIdx + 1] : null;
-        const filteredArgs = args.filter((a, i) =>
-          !['--skip-validation', '--skip-build', '--dry-run', '--reason', '--note'].includes(a) &&
-          !(i > 0 && args[i - 1] === '--reason') &&
-          !(i > 0 && args[i - 1] === '--note'));
-        const featureName = filteredArgs[1];
-        const taskIds = filteredArgs.slice(2);
-
-        if (!featureName || taskIds.length === 0) {
-          console.error(chalk.red('Usage: morph-spec task done <feature> <task-id> [task-id...] [--note <text>] [--skip-validation] [--skip-build] [--reason <text>] [--dry-run]'));
-          process.exit(1);
-        }
-
-        await withStateLock(() => manager.completeTasks(featureName, taskIds, { skipValidation, skipBuild, reason, note, dryRun }));
-        break;
-      }
-
-      case 'bulk-done': {
-        const skipValidation = args.includes('--skip-validation');
-        const dryRun = args.includes('--dry-run');
-        const allFlag = args.includes('--all');
-        const fromIdx = args.indexOf('--from');
-        const toIdx = args.indexOf('--to');
-        const reasonIdx = args.indexOf('--reason');
-        const reason = reasonIdx !== -1 ? args[reasonIdx + 1] : null;
-        const noteIdx = args.indexOf('--note');
-        const note = noteIdx !== -1 ? args[noteIdx + 1] : null;
-        const filteredArgs = args.filter((a, i) => !['--skip-validation', '--dry-run', '--all', '--reason', '--note'].includes(a)
-          && !a.startsWith('--from') && !a.startsWith('--to')
-          && !(i > 0 && args[i - 1] === '--reason')
-          && !(i > 0 && args[i - 1] === '--note'));
-        const featureName = filteredArgs[1];
-        const rangeArg = filteredArgs[2]; // e.g. T001..T082
-
-        if (!featureName) {
-          console.error(chalk.red('Usage: morph-spec task bulk-done <feature> [--all | --from T001 --to T053 | T001..T082] [--note <text>] [--skip-validation] [--reason <text>] [--dry-run]'));
-          process.exit(1);
-        }
-
-        const fromId = fromIdx !== -1 ? args[fromIdx + 1] : null;
-        const toId   = toIdx   !== -1 ? args[toIdx   + 1] : null;
-
-        await withStateLock(() => manager.bulkCompleteTasks(featureName, { all: allFlag, from: fromId, to: toId, range: rangeArg, skipValidation, reason, note, dryRun }));
-        break;
-      }
-
-      case 'start': {
-        const featureName = args[1];
-        const taskId = args[2];
-
-        if (!featureName || !taskId) {
-          console.error(chalk.red('Usage: morph-spec task start <feature> <task-id>'));
-          process.exit(1);
-        }
-
-        await withStateLock(() => manager.startTask(featureName, taskId));
-
-        // Generate sprint contract for evaluator
-        try {
-          const { generateSprintContract } = await import('../src/lib/contracts/sprint-contract-generator.js');
-          const contract = generateSprintContract(process.cwd(), featureName, taskId);
-          if (contract) {
-            console.log(chalk.gray(`  Sprint contract: .morph/features/${featureName}/5-implement/contracts/${taskId}-contract.yaml`));
-          }
-        } catch {
-          // Non-blocking — contract generation is optional
-        }
-
-        break;
-      }
-
-      case 'annotate': {
-        const featureName = args[1];
-        const taskId = args[2];
-        const text = args[3];
-        const typeIdx = args.indexOf('--type');
-        const type = typeIdx !== -1 ? args[typeIdx + 1] : 'deviation';
-        const markDone = args.includes('--mark-done');
-
-        if (!featureName || !taskId || !text) {
-          console.error(chalk.red('Usage: morph-spec task annotate <feature> <task-id> <text> [--type deviation|context|blocker-resolved] [--mark-done]'));
-          process.exit(1);
-        }
-
-        await manager.annotateTask(featureName, taskId, text, type, markDone);
-        break;
-      }
-
-      default:
-        console.error(chalk.red(`Unknown command: ${command}`));
-        console.log(chalk.gray('\nAvailable commands:'));
-        console.log(chalk.gray('  done      <feature> <task-id...>              - Mark tasks as completed (validation gate)'));
-        console.log(chalk.gray('  bulk-done <feature> --all                     - Mark all pending tasks as completed'));
-        console.log(chalk.gray('  bulk-done <feature> --from T001 --to T053     - Mark range as completed'));
-        console.log(chalk.gray('  bulk-done <feature> T001..T082                - Mark range as completed'));
-        console.log(chalk.gray('  start     <feature> <task-id>                 - Start a task (dispatch gate + state tracking)'));
-        console.log(chalk.gray('  annotate  <feature> <task-id> <text>          - Add a note to a task'));
-        console.log(chalk.gray('\nFlags: --skip-validation --reason <text>, --note <text>, --dry-run'));
-        process.exit(1);
-    }
-  } catch (error) {
-    console.error(chalk.red(`\n❌ Error: ${error.message}`));
-    process.exit(1);
-  }
-}
-
-// ESM equivalent of `if (require.main === module)`
-if (process.argv[1] === fileURLToPath(import.meta.url)) {
-  main();
-}
-
-/**
- * Pure predicate: should a --skip-validation bypass warning be logged?
- *
- * @param {Array} tasksToComplete - Tasks that will be marked complete
- * @param {boolean} skipValidation - Whether --skip-validation flag is active
- * @param {boolean} dryRun - Whether --dry-run is active (has its own message)
- * @returns {boolean}
- */
-export function shouldLogSkipValidationWarning(tasksToComplete, skipValidation, dryRun) {
-  return tasksToComplete.length > 0 && !!skipValidation && !dryRun;
-}
-
-/**
- * Compute the skip-validation budget for a feature.
- * Formula: clamp(ceil(totalTasks * 0.20), 1, 5)
- *
- * @param {Object} feature - Feature state object
- * @returns {number} Maximum allowed skip-validation uses
- */
-export function computeSkipBudget(feature) {
-  const total = feature.tasks?.total || 0;
-  if (total === 0) return 1;
-  const isMigration = feature.workflow === 'migration' || feature.workflow === 'refactor'
-    || (feature.tags || []).some(t => ['migration', 'refactor'].includes(t));
-  const cap = isMigration ? 20 : 5;
-  const rate = isMigration ? 0.40 : 0.20;
-  return Math.max(1, Math.min(cap, Math.ceil(total * rate)));
-}
-
-/**
- * Test Task Guard — run project test suite before completing test-keyword tasks.
- *
- * Extracted as a pure, injectable function so it can be unit-tested without
- * spawning a full TaskManager or writing state to disk.
- *
- * @param {Array}  tasksToComplete - Tasks about to be marked complete
- * @param {string} projectPath     - Project root (process.cwd() in production)
- * @param {object} [opts]
- * @param {boolean}  [opts.skipValidation] - Skip the guard entirely
- * @param {boolean}  [opts.dryRun]         - Skip the guard entirely
- * @param {Function} [opts._runTestSuite]  - Override runTestSuite for testing
- * @param {Function} [opts._exit]          - Override process.exit for testing
- * @returns {void}  Calls _exit/process.exit(1) on failure; returns normally otherwise
- */
-export function runTestGuard(tasksToComplete, projectPath, opts = {}) {
-  if (!tasksToComplete.length || opts.skipValidation || opts.skipBuild || opts.dryRun) return;
-
-  const _runTS = opts._runTestSuite ?? runTestSuite;
-  const hasTestTask = tasksToComplete.some(t => isTestTask(t.title));
-  if (!hasTestTask) return;
-
-  const suiteResult = _runTS(projectPath);
-
-  if (suiteResult.passed === false && suiteResult.buildFailed) {
-    console.log(chalk.yellow('\n⚠️  Test build failed — skipping test guard'));
-    console.log(chalk.gray('   Ensure the project builds before running tests'));
-    if (suiteResult.output) {
-      console.log(chalk.gray(suiteResult.output.slice(-500)));
-    }
-  } else if (suiteResult.passed === false) {
-    console.error(chalk.red('\n❌ Test suite FAILED — tasks NOT marked as complete'));
-    if (suiteResult.output) {
-      console.error(chalk.gray(suiteResult.output.slice(-2000)));
-    }
-    console.log(chalk.gray('   Fix failing tests, then run task done again'));
-    console.log(chalk.gray('   Or use --skip-validation to bypass (not recommended)\n'));
-    (opts._exit ?? process.exit)(1);
-  } else if (suiteResult.skipped) {
-    console.log(chalk.yellow('\n⚠️  Test suite skipped — no testCommand configured'));
-    console.log(chalk.gray(`   Reason: ${suiteResult.reason}`));
-    console.log(chalk.gray('   Set project.testCommand in .morph/config/config.json to enable auto-run\n'));
-  } else {
-    console.log(chalk.green('\n✅ Test suite passed'));
-  }
-}
-
-export default TaskManager;