@polymorphism-tech/morph-spec 4.16.0 → 4.17.0

package/bin/task-manager.js

@@ -1,962 +1,999 @@
-#!/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 } from '../src/core/state/state-manager.js';
-import { ensureTaskList, syncCounters } from '../src/lib/tasks/task-parser.js';
-import { isTestTask } 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;
-      }
-
-      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
-    if (tasksToComplete.length > 0 && !options.skipValidation) {
-      const validationResult = await this.runValidation(featureName, { mode: 'light' });
-      if (options.dryRun) {
-        console.log(chalk.cyan('\n  ℹ️  Dry-run — tasks NOT marked as complete'));
-        return [];
-      }
-      if (!validationResult.passed) {
-        // Reload state to ensure we have the latest (may have been modified by validation)
-        const currentState = loadState();
-        const currentFeature = currentState.features[featureName];
-        if (currentFeature) {
-          for (const task of tasksToComplete) {
-            this.persistValidationHistory(currentFeature, task.id, validationResult);
-          }
-          saveState(currentState);
-
-          // Check escalation status
-          const blockedTasks = tasksToComplete.filter(t => {
-            const hist = currentFeature.validationHistory?.[t.id];
-            return hist?.status === 'blocked';
-          });
-          if (blockedTasks.length > 0) {
-            console.error(chalk.red(`\n⛔ ESCALATION — Task(s) ${blockedTasks.map(t => t.id).join(', ')} have failed 3 times`));
-            console.error(chalk.red('   Human review required. Mark resolved with: morph-spec state set <feature> validationHistory.<taskId>.status passed'));
-          } else {
-            const attempt = currentFeature.validationHistory?.[tasksToComplete[0]?.id]?.attempt || 1;
-            console.error(chalk.red(`\n❌ Validation failed (attempt ${attempt}/3) — 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) {
-      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 };
-    } 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 };
-    }
-  }
-
-  /**
-   * 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) {
-    if (!feature.validationHistory) {
-      feature.validationHistory = {};
-    }
-    const existing = feature.validationHistory[taskId] || { attempt: 0 };
-    const attempt = (existing.attempt || 0) + 1;
-    const status = attempt >= 3 ? 'blocked' : 'failed';
-
-    feature.validationHistory[taskId] = {
-      attempt,
-      validators: validationResult.validators || {},
-      passRate: validationResult.passRate || 0,
-      status,
-      updatedAt: new Date().toISOString(),
-    };
-  }
-
-  /**
-   * 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') {
-    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'
-    });
-
-    feature.updatedAt = new Date().toISOString();
-    saveState(state);
-
-    console.log(chalk.green(`Added ${type} note to ${taskId}`));
-    console.log(chalk.gray(`  "${text}"`));
-  }
-}
-
-// ============================================================================
-// 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 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', '--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] [--reason <text>] [--dry-run]'));
-          process.exit(1);
-        }
-
-        await manager.completeTasks(featureName, taskIds, { skipValidation, 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 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 manager.startTask(featureName, taskId);
-        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';
-
-        if (!featureName || !taskId || !text) {
-          console.error(chalk.red('Usage: morph-spec task annotate <feature> <task-id> <text> [--type deviation|context|blocker-resolved]'));
-          process.exit(1);
-        }
-
-        await manager.annotateTask(featureName, taskId, text, type);
-        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;
-  return Math.max(1, Math.min(5, Math.ceil(total * 0.2)));
-}
-
-/**
- * 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.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) {
-    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;
+#!/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 [];
+      }
+      if (!validationResult.passed) {
+        // Reload state to ensure we have the latest (may have been modified by validation)
+        const currentState = loadState();
+        const currentFeature = currentState.features[featureName];
+        if (currentFeature) {
+          for (const task of tasksToComplete) {
+            this.persistValidationHistory(currentFeature, task.id, validationResult);
+          }
+          saveState(currentState);
+
+          // Check escalation status
+          const blockedTasks = tasksToComplete.filter(t => {
+            const hist = currentFeature.validationHistory?.[t.id];
+            return hist?.status === 'blocked';
+          });
+          if (blockedTasks.length > 0) {
+            console.error(chalk.red(`\n⛔ ESCALATION — Task(s) ${blockedTasks.map(t => t.id).join(', ')} have failed 3 times`));
+            console.error(chalk.red('   Human review required. Mark resolved with: morph-spec state set <feature> validationHistory.<taskId>.status passed'));
+          } else {
+            const attempt = currentFeature.validationHistory?.[tasksToComplete[0]?.id]?.attempt || 1;
+            console.error(chalk.red(`\n❌ Validation failed (attempt ${attempt}/3) — 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 };
+    } 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 };
+    }
+  }
+
+  /**
+   * 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) {
+    if (!feature.validationHistory) {
+      feature.validationHistory = {};
+    }
+    const existing = feature.validationHistory[taskId] || { attempt: 0 };
+    const attempt = (existing.attempt || 0) + 1;
+    const status = attempt >= 3 ? 'blocked' : 'failed';
+
+    feature.validationHistory[taskId] = {
+      attempt,
+      validators: validationResult.validators || {},
+      passRate: validationResult.passRate || 0,
+      status,
+      updatedAt: new Date().toISOString(),
+    };
+  }
+
+  /**
+   * 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));
+        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;