@polymorphism-tech/morph-spec 4.8.19 → 4.10.0

package/CLAUDE.md

@@ -18,6 +18,7 @@
 - Ignore standards in `.morph/framework/standards/`
 - Create infrastructure manually
 - Generate code without defined contracts
+- List questions as plain text — always use the `AskUserQuestion` tool
 
 **ALWAYS:**
 - Follow the mandatory phases
@@ -25,6 +26,7 @@
 - Document decisions in `decisions.md`
 - Checkpoint every 3 implemented tasks
 - Use Infrastructure as Code
+- Use `AskUserQuestion` tool whenever asking the user anything (1–4 questions per call; split into sequential calls if more)
 
 ---
 
@@ -48,6 +50,25 @@
 | `.morph/framework/` | **READ-ONLY** — framework files managed by morph-spec |
 | `.morph/config/config.json` | Project configuration (editable) |
 
+### mark-output types
+
+Use `morph-spec state mark-output <feature> <type>` with one of these exact type names:
+
+| Type | Phase | kebab alias |
+|------|-------|-------------|
+| `proposal` | proposal | — |
+| `schemaAnalysis` | design | `schema-analysis` |
+| `spec` | design | — |
+| `contracts` | design | — |
+| `contractsVsa` | design | `contracts-vsa` |
+| `decisions` | design | — |
+| `clarifications` | clarify | — |
+| `tasks` | tasks | — |
+| `uiDesignSystem` | uiux | `ui-design-system` |
+| `uiMockups` | uiux | `ui-mockups` |
+| `uiComponents` | uiux | `ui-components` |
+| `uiFlows` | uiux | `ui-flows` |
+| `recap` | implement | — |
 ---
 
 ## Phase Sequence

package/README.md

@@ -3,7 +3,7 @@
 > Spec-driven development framework for multi-stack projects. Turns feature requests into implementation-ready code through structured, AI-orchestrated phases.
 
 **Package:** `@polymorphism-tech/morph-spec`
-**Version:** 4.8.19  
+**Version:** 4.10.0  
 **Requires:** Node.js 18+, Claude Code
 
 ---
@@ -376,4 +376,4 @@ Code generated by morph-spec (contracts, templates, implementation output) belon
 
 ---
 
-*morph-spec v4.8.19 by [Polymorphism Tech](https://polymorphism.tech)*
+*morph-spec v4.10.0 by [Polymorphism Tech](https://polymorphism.tech)*

package/bin/morph-spec.js

@@ -12,24 +12,27 @@ import { setupInfraCommand } from '../src/commands/project/setup-infra-cmd.js';
 import { installPluginCommand } from '../src/commands/project/install-plugin-cmd.js';
 import { updateCommand } from '../src/commands/project/update.js';
 import { doctorCommand } from '../src/commands/project/doctor.js';
-import { tutorialCommand } from '../src/commands/project/tutorial.js';
 
 import { statusCommand } from '../src/commands/project/status.js';
-import { monitorCommand } from '../src/commands/project/monitor.js';
-import { checkpointSaveCommand, checkpointRestoreCommand, checkpointListCommand } from '../src/commands/project/checkpoint.js';
+import { worktreeSetupCommand } from '../src/commands/project/worktree.js';
+import { checkpointSaveCommand } from '../src/commands/project/checkpoint.js';
 
 // State commands
 import { stateCommand } from '../src/commands/state/state.js';
-import { validatePhaseCommand } from '../src/commands/state/validate-phase.js';
 import { advancePhaseCommand } from '../src/commands/state/advance-phase.js';
 import { approveCommand, approvalStatusCommand, unapproveCommand } from '../src/commands/state/approve.js';
 import { phaseRunCommand } from '../src/commands/state/phase-runner.js';
+import { phaseResetCommand } from '../src/commands/phase/phase-reset.js';
 
 // Agent commands
 import { dispatchAgentsCommand } from '../src/commands/agents/dispatch-agents.js';
 
 // Task commands
-import { taskDoneCommand, taskStartCommand, taskNextCommand, taskBulkDoneCommand } from '../src/commands/tasks/task.js';
+import { taskDoneCommand, taskStartCommand, taskNextCommand } from '../src/commands/tasks/task.js';
+
+// Scope escalation commands
+import { scopeEscalateCommand } from '../src/commands/scope/escalate.js';
+import { taskExpandCommand } from '../src/commands/task/expand.js';
 
 // Validation commands
 import { validateCommand } from './validate.js';
@@ -37,8 +40,6 @@ import { validateFeatureCommand } from '../src/commands/validation/validate-feat
 
 // Template commands
 import { templateRenderCommand } from '../src/commands/templates/template-render.js';
-import { generateContractsCommand } from '../src/commands/templates/generate-contracts.js';
-
 // MCP commands
 import { mcpSetupCommand } from '../src/commands/mcp/mcp-setup.js';
 
@@ -100,11 +101,6 @@ program
   .option('--reset', 'Remove morph-managed entries from .claude/settings.local.json')
   .action(doctorCommand);
 
-program
-  .command('tutorial')
-  .description('Learn the MORPH-SPEC workflow — phase pipeline and getting started')
-  .action(tutorialCommand);
-
 program
   .command('status <feature>')
   .description('Show comprehensive feature status dashboard')
@@ -112,18 +108,22 @@ program
   .option('-v, --verbose', 'Show detailed output')
   .action(statusCommand);
 
-program
-  .command('monitor [feature]')
-  .description('Live TUI dashboard — hooks, agents, skills, rules in real time')
-  .option('--compact', 'Minimal single-view output')
-  .option('--mode <mode>', 'Start view: overview|hooks|agents|skills|rules', 'overview')
-  .action(monitorCommand);
+// Worktree commands
+const worktreeCommand = program
+  .command('worktree')
+  .description('Manage git worktrees for feature isolation');
+
+worktreeCommand
+  .command('setup <feature>')
+  .description('Create a worktree at .worktrees/{feature}/ on branch morph/{feature}')
+  .option('--fresh', 'Create a new dated branch even if one already exists')
+  .action((feature, options) => worktreeSetupCommand(feature, options));
 
 // State management commands
 program
   .command('state <action> [args...]')
   .description('Manage state.json (init | get | set | list | add-agent | remove-agent | mark-output)')
-  .option('--force', 'Force overwrite (init command)')
+  .option('--force', 'Force overwrite (init) or bypass phase protection gates (set phase)')
   .option('--project <name>', 'Project name (init command)')
   .option('--type <type>', 'Project type (init command)')
   .option('--json', 'Output as JSON (get command)')
@@ -141,16 +141,6 @@ taskCommand
   .option('--dry-run', 'Show validation results without marking tasks as complete')
   .action((feature, taskIds, options) => taskDoneCommand(feature, taskIds, options));
 
-taskCommand
-  .command('bulk-done <feature> [range]')
-  .description('Bulk-complete tasks (--all | --from T001 --to T053 | T001..T082)')
-  .option('--all', 'Complete all pending tasks')
-  .option('--from <id>', 'Start task ID for range')
-  .option('--to <id>', 'End task ID for range')
-  .option('--skip-validation', 'Skip code validation (not recommended)')
-  .option('--dry-run', 'Show validation results without marking tasks as complete')
-  .action((feature, range, options) => taskBulkDoneCommand(feature, range, options));
-
 taskCommand
   .command('start <feature> <task-id>')
   .description('Start a task (mark as in_progress)')
@@ -161,6 +151,12 @@ taskCommand
   .description('Show next suggested task')
   .action((feature, options) => taskNextCommand(feature, options));
 
+taskCommand
+  .command('expand <feature> <task-id>')
+  .description('Expand a task into sub-tasks (low-impact scope escalation)')
+  .option('--into <subtasks...>', 'Sub-task definitions ("T017a: Title")')
+  .action((feature, taskId, options) => taskExpandCommand(feature, taskId, options));
+
 // Generation commands
 const generateCommand = program
   .command('generate')
@@ -175,14 +171,6 @@ generateCommand
     await generateRecap('.', feature, options);
   });
 
-generateCommand
-  .command('contracts <feature>')
-  .description('Generate contracts.cs from schema-analysis.md using real field names and types')
-  .option('--dry-run', 'Preview output without writing file')
-  .option('--output <path>', 'Override output path for contracts.cs')
-  .option('-v, --verbose', 'Show stack trace on error')
-  .action((feature, options) => generateContractsCommand(feature, options));
-
 // Validation commands (Sprint 4: Continuous Validation)
 program
   .command('validate [validator]')
@@ -219,12 +207,10 @@ phaseCommand
   .option('--skip-approval', 'Skip approval gate checks')
   .action((feature, options) => phaseRunCommand(feature, options));
 
-// Phase validation command (also available as standalone)
-program
-  .command('validate-phase <feature> <phase>')
-  .description('Validate prerequisites before advancing to a phase')
-  .option('-v, --verbose', 'Show detailed output')
-  .action(validatePhaseCommand);
+phaseCommand
+  .command('reset <feature> <phase>')
+  .description('Reset feature phase (recovery tool — bypasses approval gates)')
+  .action((feature, phase) => phaseResetCommand(feature, phase));
 
 // Feature validation command (content-aware)
 program
@@ -243,17 +229,6 @@ program
   .option('--label <label>', 'Custom label for checkpoint')
   .action(checkpointSaveCommand);
 
-program
-  .command('checkpoint-restore <feature> [checkpoint]')
-  .description('Restore feature from a checkpoint (latest if no name given)')
-  .action(checkpointRestoreCommand);
-
-program
-  .command('checkpoint-list <feature>')
-  .description('List all checkpoints for a feature')
-  .option('--json', 'Output as JSON')
-  .action(checkpointListCommand);
-
 // Approval workflow commands
 program
   .command('approve <feature> <gate>')
@@ -300,7 +275,7 @@ trustCommand
 
 trustCommand
   .command('set <feature> <level> [reason]')
-  .description('Manually set trust level (low|medium|high|maximum)')
+  .description('Manually set trust level (manual|high|auto)')
   .action(trustSetCommand);
 
 // ─────────────────────────────────────────────────────────────────────────────
@@ -326,4 +301,18 @@ program
   .option('-v, --verbose', 'Show stack trace on error')
   .action((feature, phase, options) => dispatchAgentsCommand(feature, phase, options));
 
+// Scope escalation commands
+const scopeCommand = program
+  .command('scope')
+  .description('Scope management (escalate)');
+
+scopeCommand
+  .command('escalate <feature>')
+  .description('Escalate scope when implementation reveals unexpected complexity')
+  .option('--task <id>', 'Trigger task ID (required)')
+  .option('--reason <text>', 'Reason for escalation (required)')
+  .option('--target <phase>', 'Override target phase (tasks | design)')
+  .option('--dry-run', 'Show recommendation without executing')
+  .action((feature, options) => scopeEscalateCommand(feature, options));
+
 program.parse();

package/bin/task-manager.js

@@ -15,6 +15,9 @@ import chalk from 'chalk';
 
 import { loadState, saveState } 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';
+import { STALE_MS, isStaleTask } from '../framework/hooks/shared/stale-task-reset.js';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
@@ -96,6 +99,8 @@ class TaskManager {
    * @param {string[]} taskIds - Task IDs to complete
    * @param {Object} options - Options
    * @param {boolean} options.skipValidation - Skip code validation
+   * @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();
@@ -108,7 +113,7 @@ class TaskManager {
     const taskList = await ensureTaskList(feature, featureName);
 
     if (taskList.length === 0) {
-      const tasksPath = join(process.cwd(), `.morph/features/${featureName}/3-tasks/tasks.md`);
+      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`);
@@ -142,6 +147,12 @@ class TaskManager {
       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);
+
     // Run validation BEFORE marking tasks as complete
     if (tasksToComplete.length > 0 && !options.skipValidation) {
       const validationResult = await this.runValidation(featureName);
@@ -183,26 +194,32 @@ class TaskManager {
         process.exit(1);
       }
 
-      // Validation passed — mark any pending history as passed
-      const successState = loadState();
-      const successFeature = successState.features[featureName];
-      if (successFeature) {
+      // Validation passed — mark any pending history as passed.
+      // 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 (successFeature.validationHistory?.[task.id]) {
-            successFeature.validationHistory[task.id].status = 'passed';
-            successFeature.validationHistory[task.id].updatedAt = new Date().toISOString();
+          if (feature.validationHistory[task.id]) {
+            feature.validationHistory[task.id].status = 'passed';
+            feature.validationHistory[task.id].updatedAt = new Date().toISOString();
           }
         }
-        saveState(successState);
       }
     } 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)) {
+      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 breakingChanges = await detectBreakingChanges();
+      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'));
@@ -274,6 +291,18 @@ class TaskManager {
     // Display progress
     this.displayProgress(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
+      }
+    }
+
     // Suggest next task
     const nextTask = this.getNextTask(taskList);
     if (nextTask) {
@@ -343,7 +372,7 @@ class TaskManager {
       // 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: npx morph-spec validate --verbose'));
+      console.log(chalk.gray(`   Run manually: npx morph-spec validate-feature ${featureName}`));
       return { passed: true, validators: {}, passRate: 1.0 };
     }
   }
@@ -391,10 +420,12 @@ class TaskManager {
    * Calculate progress
    */
   calculateProgress(tasks) {
-    const total = tasks.length;
-    const completed = tasks.filter(t => t.status === 'completed').length;
-    const inProgress = tasks.filter(t => t.status === 'in_progress').length;
-    const pending = tasks.filter(t => t.status === 'pending').length;
+    // Exclude expanded tasks — they are replaced by their sub-tasks
+    const activeTasks = tasks.filter(t => t.status !== 'expanded');
+    const total = activeTasks.length;
+    const completed = activeTasks.filter(t => t.status === 'completed').length;
+    const inProgress = activeTasks.filter(t => t.status === 'in_progress').length;
+    const pending = activeTasks.filter(t => t.status === 'pending').length;
     const percentage = total > 0 ? Math.round((completed / total) * 100) : 0;
 
     return { total, completed, inProgress, pending, percentage };
@@ -408,7 +439,8 @@ class TaskManager {
       id: task.checkpoint,
       timestamp: new Date().toISOString(),
       tasksCompleted: [task.id],
-      note: `Checkpoint: ${task.title}`
+      note: `Checkpoint: ${task.title}`,
+      passed: true  // reaching a named checkpoint means the task completed successfully
     };
 
     feature.checkpoints = feature.checkpoints || [];
@@ -469,6 +501,7 @@ class TaskManager {
       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
     };
 
@@ -542,12 +575,22 @@ class TaskManager {
   }
 
   /**
-   * Get next pending task (based on dependencies)
+   * Get next available task (based on dependencies).
+   * Stale in_progress tasks (older than 1 hour, or missing startedAt) are
+   * treated as effectively pending and included as candidates.
    */
   getNextTask(tasks) {
-    const pending = tasks.filter(t => t.status === 'pending');
+    // Include stale in_progress tasks as effectively pending candidates
+    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;
+    };
+
+    const candidates = tasks.filter(isEffectivelyAvailable);
 
-    for (const task of pending) {
+    for (const task of candidates) {
       const missingDeps = this.checkDependencies(task, tasks);
       if (missingDeps.length === 0) {
         return task;
@@ -570,6 +613,13 @@ class TaskManager {
     const filledLength = Math.round((percentage / 100) * barLength);
     const bar = '█'.repeat(filledLength) + '░'.repeat(barLength - filledLength);
     console.log(chalk.cyan(`   [${bar}] ${percentage}%`));
+
+    // Warn about tasks flagged for review (from scope escalation)
+    const taskList = feature.taskList || [];
+    const needsReviewTasks = taskList.filter(t => t.needsReview && (t.status === 'done' || t.status === 'completed'));
+    if (needsReviewTasks.length > 0) {
+      console.log(chalk.yellow(`\n   ⚠  ${needsReviewTasks.length} completed task(s) flagged for review (scope escalation)`));
+    }
   }
 
   /**
@@ -586,7 +636,7 @@ class TaskManager {
     const taskList = await ensureTaskList(feature, featureName);
 
     if (taskList.length === 0) {
-      const tasksPath = join(process.cwd(), `.morph/features/${featureName}/3-tasks/tasks.md`);
+      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`);
@@ -610,6 +660,16 @@ class TaskManager {
       throw new Error(`Cannot start ${taskId}: missing dependencies: ${missingDeps.join(', ')}`);
     }
 
+    // Reset any sibling tasks stuck in in_progress from a previous session.
+    // Only tasks OTHER than the one being started, and only if stale (>1h).
+    for (const t of taskList) {
+      if (t.id !== taskId && isStaleTask(t)) {
+        t.status = 'pending';
+        delete t.startedAt;
+        console.log(chalk.yellow(`⚠️  Task ${t.id} auto-reset to pending (stale from previous session)`));
+      }
+    }
+
     task.status = 'in_progress';
     task.startedAt = new Date().toISOString();
     syncCounters(feature);
@@ -800,4 +860,57 @@ 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;
+}
+
+/**
+ * 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;

package/bin/validate.js

@@ -3,46 +3,75 @@
 /**
  * Validation CLI
  *
- * Runs all validators (package, architecture, contrast) on the project.
- * Part of Sprint 4: Continuous Validation
+ * Runs validators for the current project stack (detected from .morph/config/config.json).
+ *
+ * .NET/Blazor stacks: packages, architecture, contrast, spec-tasks
+ * Next.js stack:      next-components, spec-tasks
+ * Other stacks:       spec-tasks
  *
  * Usage:
  *   morph-spec validate [options]
- *   morph-spec validate packages
- *   morph-spec validate architecture
- *   morph-spec validate contrast
  *   morph-spec validate all
+ *   morph-spec validate next-components  (Next.js projects)
+ *   morph-spec validate packages         (.NET projects)
  *
  * MORPH-SPEC 3.0
  */
 
 import chalk from 'chalk';
-import { validatePackages } from '../src/lib/validators/packages/package-validator.js';
-import { validateArchitecture } from '../src/lib/validators/architecture/architecture-validator.js';
-import { validateContrast } from '../src/lib/validators/ui/ui-contrast-validator.js';
-
-const VALIDATORS = {
-  packages: {
-    name: 'Package Compatibility',
-    description: 'Validates NuGet package versions against .NET compatibility matrix',
-    run: validatePackages
-  },
-  architecture: {
-    name: 'Architecture Patterns',
-    description: 'Detects DI anti-patterns and lifecycle issues in Blazor',
-    run: validateArchitecture
-  },
-  contrast: {
-    name: 'UI Contrast (WCAG)',
-    description: 'Validates color contrast ratios for accessibility',
-    run: validateContrast
-  },
-  'spec-tasks': {
+import { getStackProfile } from '../src/lib/stack/stack-profile.js';
+
+/**
+ * Build the VALIDATORS registry for the current stack.
+ * .NET stacks  → packages, architecture, contrast, spec-tasks
+ * nextjs stack → next-components, spec-tasks
+ * other stacks → spec-tasks only
+ */
+async function buildValidators(stack) {
+  const validators = {};
+
+  const isDotnet = !stack || ['dotnet', 'blazor', 'aspnet', 'dotnet-blazor'].includes(stack.toLowerCase());
+  const isNextjs = stack && ['nextjs', 'next', 'next.js'].includes(stack.toLowerCase());
+
+  if (isDotnet) {
+    const { validatePackages } = await import('../src/lib/validators/packages/package-validator.js');
+    const { validateArchitecture } = await import('../src/lib/validators/architecture/architecture-validator.js');
+    const { validateContrast } = await import('../src/lib/validators/ui/ui-contrast-validator.js');
+
+    validators.packages = {
+      name: 'Package Compatibility',
+      description: 'Validates NuGet package versions against .NET compatibility matrix',
+      run: validatePackages
+    };
+    validators.architecture = {
+      name: 'Architecture Patterns',
+      description: 'Detects DI anti-patterns and lifecycle issues in Blazor',
+      run: validateArchitecture
+    };
+    validators.contrast = {
+      name: 'UI Contrast (WCAG)',
+      description: 'Validates color contrast ratios for accessibility',
+      run: validateContrast
+    };
+  }
+
+  if (isNextjs) {
+    const { validateNextComponentFiles } = await import('../src/lib/validators/nextjs/next-component-validator.js');
+    validators['next-components'] = {
+      name: 'Next.js Components',
+      description: "Validates 'use client' directives, hook usage, and file naming conventions",
+      run: (projectPath, opts) => validateNextComponentFiles(projectPath, opts)
+    };
+  }
+
+  validators['spec-tasks'] = {
     name: 'Spec vs Tasks Coverage',
     description: 'Validates that tasks.json covers all requirements from spec.md',
     run: validateSpecVsTasks
-  }
-};
+  };
+
+  return validators;
+}
 
 /**
  * Validate spec.md requirements are covered by tasks
@@ -147,12 +176,18 @@ export async function validateCommand(args = []) {
   const validatorName = args[0] || 'all';
   const options = parseOptions(args);
 
+  const { stack } = getStackProfile();
+  const VALIDATORS = await buildValidators(stack);
+
   console.log(chalk.bold.cyan('\n🔍 MORPH-SPEC Validator\n'));
+  if (stack) {
+    console.log(chalk.gray(`Stack: ${stack}\n`));
+  }
 
   if (validatorName === 'all') {
-    await runAllValidators(options);
+    await runAllValidators(VALIDATORS, options);
   } else if (VALIDATORS[validatorName]) {
-    await runValidator(validatorName, options);
+    await runValidator(VALIDATORS, validatorName, options);
   } else {
     console.error(chalk.red(`❌ Unknown validator: ${validatorName}`));
     console.log(chalk.gray('\nAvailable validators:'));
@@ -162,13 +197,12 @@ export async function validateCommand(args = []) {
     console.log(chalk.gray('  - all: Run all validators'));
     process.exit(1);
   }
-
 }
 
 /**
  * Run all validators
  */
-async function runAllValidators(options) {
+async function runAllValidators(VALIDATORS, options) {
   const results = {};
   let totalErrors = 0;
   let totalWarnings = 0;
@@ -230,7 +264,7 @@ async function runAllValidators(options) {
 /**
  * Run single validator
  */
-async function runValidator(name, options) {
+async function runValidator(VALIDATORS, name, options) {
   const validator = VALIDATORS[name];
 
   console.log(chalk.cyan(`▸ ${validator.name}`));

package/claude-plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "morph-spec",
-  "version": "4.8.19",
+  "version": "4.10.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",