@polymorphism-tech/morph-spec 4.11.0 → 4.12.0

package/bin/task-manager.js

@@ -13,7 +13,7 @@ import { access } from 'fs/promises';
 import { execSync } from 'child_process';
 import chalk from 'chalk';
 
-import { loadState, saveState, resolveAgentForTask, updateDispatchAgentTiming } from '../src/core/state/state-manager.js';
+import { loadState, saveState, resolveAgentForTask, updateDispatchAgentTiming, derivePhase } from '../src/core/state/state-manager.js';
 import { parseTasksMd, 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';
@@ -40,9 +40,11 @@ const __dirname = dirname(__filename);
  *
  * @returns {Promise<Array<{export: string, consumers: string[]}>|null>}
  */
-async function detectBreakingChanges() {
+export async function detectBreakingChanges(opts = {}) {
   try {
-    const execOpts = { cwd: process.cwd(), stdio: ['pipe', 'pipe', 'pipe'], maxBuffer: 5 * 1024 * 1024 };
+    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 = '';
@@ -50,7 +52,7 @@ async function detectBreakingChanges() {
     for (const flag of ['--cached', '']) {
       try {
         const args = ['git', 'diff', '--unified=0', flag, '--', ...diffPatterns].filter(Boolean);
-        diff += execSync(args.join(' '), execOpts).toString();
+        diff += exec(args.join(' '), execOpts).toString();
       } catch {
         // git not available or no changes — continue
       }
@@ -58,6 +60,12 @@ async function detectBreakingChanges() {
 
     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;
@@ -70,12 +78,18 @@ async function detectBreakingChanges() {
 
     // 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 result = execSync(`git grep -l "${sym}"`, execOpts).toString().trim();
+        const grepCmd = ['git', 'grep', '-l', `"${sym}"`, '--', ...pathspecs].join(' ');
+        const result = exec(grepCmd, execOpts).toString().trim();
         if (result) {
-          const consumers = result.split('\n').filter(Boolean);
-          warnings.push({ export: sym, consumers });
+          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
@@ -98,7 +112,9 @@ class TaskManager {
    * @param {string} featureName - Feature name
    * @param {string[]} taskIds - Task IDs to complete
    * @param {Object} options - Options
-   * @param {boolean} options.skipValidation - Skip code validation
+   * @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
    */
@@ -159,6 +175,28 @@ class TaskManager {
     // 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' });
@@ -200,24 +238,42 @@ class TaskManager {
         process.exit(1);
       }
 
-      // Validation passed — mark any pending history as passed.
+      // 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) {
-        for (const task of tasksToComplete) {
-          if (feature.validationHistory[task.id]) {
-            feature.validationHistory[task.id].status = 'passed';
-            feature.validationHistory[task.id].updatedAt = new Date().toISOString();
-          }
-        }
+      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'));
     }
@@ -250,9 +306,23 @@ class TaskManager {
       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) {
@@ -333,16 +403,24 @@ class TaskManager {
       }
     }
 
-    // Suggest next task
+    // Suggest next task(s)
     const activeTasks = taskList.filter(t => t.status !== 'expanded');
     const allCompleted = activeTasks.length > 0 && activeTasks.every(t => t.status === 'completed');
-    const nextTask = this.getNextTask(taskList);
+    const readyTasks = this.getReadyTasks(taskList);
 
     if (allCompleted) {
       console.log(chalk.green('\n🎉 All tasks completed!'));
-    } else if (nextTask) {
+    } else if (readyTasks.length > 1) {
+      const first = readyTasks[0];
+      console.log(chalk.cyan(`\n⏭️  Next: ${first.id} - ${first.title}`));
+      if (first.dependencies?.length > 0) {
+        console.log(chalk.gray(`   Dependencies: ${first.dependencies.join(', ')}`));
+      }
+      console.log(chalk.magenta(`🔀 Parallelizable (${readyTasks.length} tasks ready): ${readyTasks.map(t => t.id).join(', ')}`));
+    } else if (readyTasks.length === 1) {
+      const nextTask = readyTasks[0];
       console.log(chalk.cyan(`\n⏭️  Next: ${nextTask.id} - ${nextTask.title}`));
-      if (nextTask.dependencies && nextTask.dependencies.length > 0) {
+      if (nextTask.dependencies?.length > 0) {
         console.log(chalk.gray(`   Dependencies: ${nextTask.dependencies.join(', ')}`));
       }
     } else {
@@ -650,6 +728,22 @@ class TaskManager {
     return null;
   }
 
+  /**
+   * Get ALL tasks that are currently ready (no unmet dependencies).
+   */
+  getReadyTasks(tasks) {
+    const isEffectivelyAvailable = (t) => {
+      if (t.status === 'expanded') return false;
+      if (t.status === 'pending') return true;
+      if (t.status === 'in_progress') return isStaleTask(t);
+      return false;
+    };
+
+    return tasks.filter(t =>
+      isEffectivelyAvailable(t) && this.checkDependencies(t, tasks).length === 0
+    );
+  }
+
   /**
    * Display progress
    */
@@ -683,6 +777,25 @@ class TaskManager {
       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) {
@@ -743,6 +856,115 @@ class TaskManager {
     console.log(chalk.blue(`▶️  Task ${taskId} started: ${task.title}`));
   }
 
+  /**
+   * Bulk-start tasks (mark as in_progress in a single operation).
+   * @param {string} featureName
+   * @param {Object} opts
+   * @param {boolean} [opts.all] - Start all pending tasks with met dependencies
+   * @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)
+   */
+  async bulkStartTasks(featureName, opts = {}) {
+    const state = loadState();
+    const feature = state.features[featureName];
+    if (!feature) throw new Error(`Feature '${featureName}' not found in state.json`);
+
+    // Dispatch enforcement gate (same as startTask)
+    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 tasks — agent dispatch not recorded for implement phase'));
+        console.error(chalk.yellow(
+          `\n  Run this command first:\n` +
+          `    morph-spec dispatch-agents ${featureName} implement\n`
+        ));
+        process.exit(1);
+      }
+    }
+
+    const taskList = await ensureTaskList(feature, featureName);
+    if (taskList.length === 0) throw new Error(`No tasks found for '${featureName}'`);
+
+    // Resolve target IDs from range options
+    let targetIds;
+    if (opts.all) {
+      targetIds = taskList.filter(t => t.status === 'pending').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-start requires --all, --from/--to, or a T001..T014 range argument');
+    }
+
+    if (targetIds.length === 0) {
+      console.log(chalk.yellow('⚠️  No tasks matched the given range'));
+      return;
+    }
+
+    // Reset stale siblings ONCE upfront
+    for (const t of taskList) {
+      if (!targetIds.includes(t.id) && isStaleTask(t)) {
+        t.status = 'pending';
+        delete t.startedAt;
+        console.log(chalk.yellow(`⚠️  Task ${t.id} auto-reset to pending (stale from previous session)`));
+      }
+    }
+
+    let started = 0;
+    let skipped = 0;
+    for (const id of targetIds) {
+      const task = taskList.find(t => t.id === id);
+      if (!task) continue;
+
+      if (task.status === 'completed') {
+        console.log(chalk.gray(`   ⏩ ${id} already completed — skipping`));
+        skipped++;
+        continue;
+      }
+
+      if (task.status === 'in_progress' && !isStaleTask(task)) {
+        console.log(chalk.gray(`   ⏩ ${id} already in_progress — skipping`));
+        skipped++;
+        continue;
+      }
+
+      const missingDeps = this.checkDependencies(task, taskList);
+      if (missingDeps.length > 0) {
+        console.log(chalk.yellow(`   ⚠️  ${id} blocked by: ${missingDeps.join(', ')} — skipping`));
+        skipped++;
+        continue;
+      }
+
+      task.status = 'in_progress';
+      task.startedAt = new Date().toISOString();
+
+      // Agent correlation
+      const agentId = resolveAgentForTask(featureName, id);
+      if (agentId) {
+        task.assignedAgent = agentId;
+        const lastDispatch = feature.dispatchLog?.[feature.dispatchLog.length - 1];
+        const dispatchAgent = lastDispatch?.agents?.find(a => a.id === agentId);
+        if (dispatchAgent && !dispatchAgent.startedAt) {
+          updateDispatchAgentTiming(featureName, agentId, { startedAt: task.startedAt });
+        }
+      }
+
+      started++;
+    }
+
+    syncCounters(feature);
+    feature.updatedAt = new Date().toISOString();
+    saveState(state);
+
+    console.log(chalk.blue(`\n▶️  Bulk-start: ${started} task(s) started` + (skipped ? `, ${skipped} skipped` : '')));
+  }
+
   /**
    * Bulk-complete tasks with a single validation pass.
    * @param {string} featureName
@@ -776,7 +998,7 @@ class TaskManager {
     }
 
     console.log(chalk.cyan(`\n📦 Bulk-done: ${targetIds.length} task(s) targeted`));
-    await this.completeTasks(featureName, targetIds, { skipValidation: opts.skipValidation, dryRun: opts.dryRun });
+    await this.completeTasks(featureName, targetIds, { skipValidation: opts.skipValidation, reason: opts.reason, note: opts.note, dryRun: opts.dryRun });
   }
 
   /**
@@ -809,24 +1031,91 @@ class TaskManager {
     const taskList = await ensureTaskList(feature, featureName);
     const activeTasks = taskList.filter(t => t.status !== 'expanded');
     const allCompleted = activeTasks.length > 0 && activeTasks.every(t => t.status === 'completed');
-    const nextTask = this.getNextTask(taskList);
+    const readyTasks = this.getReadyTasks(taskList);
 
     if (allCompleted) {
       console.log(chalk.green('🎉 All tasks completed!'));
-    } else if (nextTask) {
+    } else if (readyTasks.length > 1) {
+      const first = readyTasks[0];
+      console.log(chalk.cyan(`\n⏭️  Next task: ${first.id} - ${first.title}`));
+      if (first.dependencies?.length > 0) {
+        console.log(chalk.gray(`   Dependencies: ${first.dependencies.join(', ')}`));
+      }
+      if (first.files?.length > 0) {
+        console.log(chalk.gray(`   Files:`));
+        first.files.forEach(f => console.log(chalk.gray(`     - ${f}`)));
+      }
+      this._showDependencyDeviations(first, taskList);
+      console.log(chalk.magenta(`🔀 Parallelizable (${readyTasks.length} tasks ready): ${readyTasks.map(t => t.id).join(', ')}`));
+    } else if (readyTasks.length === 1) {
+      const nextTask = readyTasks[0];
       console.log(chalk.cyan(`\n⏭️  Next task: ${nextTask.id} - ${nextTask.title}`));
-      if (nextTask.dependencies && nextTask.dependencies.length > 0) {
+      if (nextTask.dependencies?.length > 0) {
         console.log(chalk.gray(`   Dependencies: ${nextTask.dependencies.join(', ')}`));
       }
-      if (nextTask.files && nextTask.files.length > 0) {
+      if (nextTask.files?.length > 0) {
         console.log(chalk.gray(`   Files:`));
         nextTask.files.forEach(f => console.log(chalk.gray(`     - ${f}`)));
       }
+      this._showDependencyDeviations(nextTask, taskList);
     } else {
       const remaining = activeTasks.filter(t => t.status !== 'completed');
       console.log(chalk.yellow(`\n⏸️  No tasks available — ${remaining.length} task(s) have unmet dependencies`));
     }
   }
+
+  /**
+   * Show deviation notes from completed dependencies (context for next agent)
+   * @param {Object} task - The next task
+   * @param {Object[]} taskList - Full task list
+   */
+  _showDependencyDeviations(task, taskList) {
+    const deps = task.dependencies || [];
+    const completedWithNotes = taskList.filter(t =>
+      deps.includes(t.id) && t.status === 'completed' && t.notes?.length > 0
+    );
+    for (const t of completedWithNotes) {
+      for (const n of t.notes.filter(n => n.type === 'deviation')) {
+        console.log(chalk.yellow(`   ⚠ ${t.id} deviation: ${n.text}`));
+      }
+    }
+  }
+
+  /**
+   * 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}"`));
+  }
 }
 
 // ============================================================================
@@ -845,16 +1134,23 @@ async function main() {
       case 'complete': {
         const skipValidation = args.includes('--skip-validation');
         const dryRun = args.includes('--dry-run');
-        const filteredArgs = args.filter(a => !['--skip-validation', '--dry-run'].includes(a));
+        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...] [--skip-validation] [--dry-run]'));
+          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, dryRun });
+        await manager.completeTasks(featureName, taskIds, { skipValidation, reason, note, dryRun });
         break;
       }
 
@@ -864,20 +1160,26 @@ async function main() {
         const allFlag = args.includes('--all');
         const fromIdx = args.indexOf('--from');
         const toIdx = args.indexOf('--to');
-        const filteredArgs = args.filter(a => !['--skip-validation', '--dry-run', '--all'].includes(a)
-          && !a.startsWith('--from') && !a.startsWith('--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] [--skip-validation] [--dry-run]'));
+          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, dryRun });
+        await manager.bulkCompleteTasks(featureName, { all: allFlag, from: fromId, to: toId, range: rangeArg, skipValidation, reason, note, dryRun });
         break;
       }
 
@@ -894,6 +1196,27 @@ async function main() {
         break;
       }
 
+      case 'bulk-start': {
+        const allFlag = args.includes('--all');
+        const fromIdx = args.indexOf('--from');
+        const toIdx = args.indexOf('--to');
+        const filteredArgs = args.filter(a => !['--all'].includes(a)
+          && !a.startsWith('--from') && !a.startsWith('--to'));
+        const featureName = filteredArgs[1];
+        const rangeArg = filteredArgs[2]; // e.g. T007..T014
+
+        if (!featureName) {
+          console.error(chalk.red('Usage: morph-spec task bulk-start <feature> [--all | --from T001 --to T014 | T007..T014]'));
+          process.exit(1);
+        }
+
+        const fromId = fromIdx !== -1 ? args[fromIdx + 1] : null;
+        const toId   = toIdx   !== -1 ? args[toIdx   + 1] : null;
+
+        await manager.bulkStartTasks(featureName, { all: allFlag, from: fromId, to: toId, range: rangeArg });
+        break;
+      }
+
       case 'next': {
         const featureName = args[1];
 
@@ -906,6 +1229,22 @@ async function main() {
         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:'));
@@ -913,9 +1252,13 @@ async function main() {
         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 (mark as in_progress)'));
-        console.log(chalk.gray('  next      <feature>                           - Show next suggested task'));
-        console.log(chalk.gray('\nFlags: --skip-validation, --dry-run'));
+        console.log(chalk.gray('  start      <feature> <task-id>                 - Start a task (mark as in_progress)'));
+        console.log(chalk.gray('  bulk-start <feature> --all                     - Start all pending tasks'));
+        console.log(chalk.gray('  bulk-start <feature> --from T007 --to T014     - Start range of tasks'));
+        console.log(chalk.gray('  bulk-start <feature> T007..T014                - Start range of tasks'));
+        console.log(chalk.gray('  next       <feature>                           - Show next suggested task'));
+        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) {
@@ -941,6 +1284,19 @@ export function shouldLogSkipValidationWarning(tasksToComplete, skipValidation,
   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.
  *

package/claude-plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "morph-spec",
-  "version": "4.11.0",
+  "version": "4.12.0",
   "displayName": "MORPH-SPEC Framework",
   "description": "Spec-driven development with 38 agents and 8-phase workflow for .NET/Blazor/Next.js/Azure",
   "publisher": "polymorphism-tech",

package/docs/CHEATSHEET.md

@@ -198,4 +198,4 @@ These files are never edited directly. Use CLI commands or `morph-spec update` i
 
 ---
 
-*morph-spec v4.11.0 by Polymorphism Tech*
+*morph-spec v4.12.0 by Polymorphism Tech*

package/docs/QUICKSTART.md

@@ -197,4 +197,4 @@ morph-spec doctor
 
 ---
 
-*morph-spec v4.11.0 by Polymorphism Tech*
+*morph-spec v4.12.0 by Polymorphism Tech*