@polymorphism-tech/morph-spec 4.8.7 → 4.8.8

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.7  
+**Version:** 4.8.8  
 **Requires:** Node.js 18+, Claude Code
 
 ---
@@ -376,4 +376,4 @@ Code generated by morph-spec (contracts, templates, implementation output) belon
 
 ---
 
-*morph-spec v4.8.7 by [Polymorphism Tech](https://polymorphism.tech)*
+*morph-spec v4.8.8 by [Polymorphism Tech](https://polymorphism.tech)*

package/bin/morph-spec.js

@@ -1,4 +1,4 @@
-#!/usr/bin/env node
+#!/usr/bin/env node
 
 import { program } from 'commander';
 import chalk from 'chalk';
@@ -23,6 +23,9 @@ 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';
 
+// Agent commands
+import { dispatchAgentsCommand } from '../src/commands/agents/dispatch-agents.js';
+
 // Task commands
 import { taskDoneCommand, taskStartCommand, taskNextCommand } from '../src/commands/tasks/task.js';
 
@@ -32,6 +35,7 @@ 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';
@@ -90,6 +94,7 @@ program
   .command('doctor')
   .description('Check MORPH installation health')
   .option('--full', 'Run full health check (lib files, commands, HOPs, standards, agents, state)')
+  .option('--mcp', 'Check MCP server configuration (binary + env vars)')
   .option('--reset', 'Remove morph-managed entries from .claude/settings.local.json')
   .action(doctorCommand);
 
@@ -150,6 +155,14 @@ 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]')
@@ -276,4 +289,12 @@ mcpCommand
   .option('--auto', 'Auto-install credential-free MCPs without prompts')
   .action((name, options) => mcpSetupCommand(name, options));
 
+// Agent orchestration commands
+program
+  .command('dispatch-agents <feature> <phase>')
+  .description('Build dispatch config for parallel agent orchestration (design | tasks | implement)')
+  .option('--table', 'Human-readable table output instead of JSON')
+  .option('-v, --verbose', 'Show stack trace on error')
+  .action((feature, phase, options) => dispatchAgentsCommand(feature, phase, options));
+
 program.parse();

package/bin/task-manager.cjs

@@ -32,7 +32,7 @@ const chalk = {
  * Looks for headings like: ### T001 — Task title
  */
 async function parseTasksMd(featureName) {
-  const tasksPath = path.join(process.cwd(), `.morph/features/${featureName}/tasks.md`);
+  const tasksPath = path.join(process.cwd(), `.morph/features/${featureName}/3-tasks/tasks.md`);
   let content = '';
   try {
     content = await fs.readFile(tasksPath, 'utf-8');
@@ -75,14 +75,79 @@ async function ensureTaskList(feature, featureName) {
 
 /**
  * After modifying taskList, sync counts back to feature.tasks counter.
+ * tasks.total is derived from the actual taskList length (Problem 3 fix).
  */
 function syncCounters(feature) {
   if (Array.isArray(feature.tasks)) return; // v2, nothing to sync
   const list = feature.taskList || [];
+  feature.tasks.total = list.length; // Auto-sync total from parsed taskList
   feature.tasks.completed = list.filter(t => t.status === 'completed').length;
   feature.tasks.inProgress = list.filter(t => t.status === 'in_progress').length;
   feature.tasks.pending = list.filter(t => t.status === 'pending').length;
-  // Don't touch feature.tasks.total — it is the authoritative count
+}
+
+/**
+ * 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>}
+ */
+async function detectBreakingChanges() {
+  try {
+    const { execSync } = require('child_process');
+    const execOpts = { cwd: process.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 += execSync(args.join(' '), execOpts).toString();
+      } catch {
+        // git not available or no changes — continue
+      }
+    }
+
+    if (!diff.trim()) return null;
+
+    // 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 = [];
+    for (const sym of removedExports) {
+      try {
+        // git grep returns exit code 1 when nothing found — that's handled by catch
+        const result = execSync(`git grep -l "${sym}"`, execOpts).toString().trim();
+        if (result) {
+          const consumers = result.split('\n').filter(Boolean);
+          warnings.push({ export: sym, consumers });
+        }
+      } catch {
+        // No match found — safe
+      }
+    }
+
+    return warnings;
+  } catch {
+    return null; // Non-blocking: any unexpected error → skip detection
+  }
 }
 
 class TaskManager {
@@ -134,6 +199,16 @@ class TaskManager {
     }
 
     const taskList = await ensureTaskList(feature, featureName);
+
+    if (taskList.length === 0) {
+      const tasksPath = path.join(process.cwd(), `.morph/features/${featureName}/3-tasks/tasks.md`);
+      const tasksExist = await fs.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`);
+    }
+
     const results = [];
     const tasksToComplete = [];
 
@@ -141,7 +216,7 @@ class TaskManager {
       const task = taskList.find(t => t.id === taskId);
 
       if (!task) {
-        console.error(chalk.red(`❌ Task ${taskId} not found`));
+        console.error(chalk.red(`❌ Task ${taskId} not found (available: ${taskList.map(t => t.id).join(', ')})`));
         continue;
       }
 
@@ -171,6 +246,23 @@ class TaskManager {
       }
     }
 
+    // Breaking change detection (non-blocking warning)
+    if (tasksToComplete.length > 0) {
+      const breakingChanges = await detectBreakingChanges();
+      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 (only after validation passes)
     for (const task of tasksToComplete) {
       task.status = 'completed';
@@ -191,17 +283,16 @@ class TaskManager {
     syncCounters(feature);
     feature.progress = this.calculateProgress(taskList);
 
-    // Auto-checkpoint every 3 tasks
-    const recentCompleted = this.getRecentCompleted(taskList, 3);
-    if (recentCompleted.length === 3) {
-      const lastCheckpoint = feature.checkpoints[feature.checkpoints.length - 1];
-      const shouldAutoCheckpoint = !lastCheckpoint ||
-        !recentCompleted.every(t =>
-          lastCheckpoint.tasksCompleted.includes(t.id)
-        );
-
-      if (shouldAutoCheckpoint) {
+    // Auto-checkpoint every 3 tasks (at exact multiples of 3, not after every task).
+    // Uses feature._lastAutoCheckpointNum to track which threshold already fired.
+    const completedCount = taskList.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;
       }
     }
 
@@ -258,8 +349,11 @@ class TaskManager {
       formatValidationResults(result);
       return result.passed;
     } catch (error) {
-      // If validation runner fails to load, warn but don't block
-      console.log(chalk.yellow(`\n⚠️  Validation skipped: ${error.message}`));
+      // 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: ESM import failure on Windows or missing optional deps.
+      console.log(chalk.yellow(`\n⚠️  Validation skipped (${error.message})`));
+      console.log(chalk.gray('   Run manually: npx morph-spec validate --verbose'));
       return true;
     }
   }
@@ -496,10 +590,20 @@ class TaskManager {
     }
 
     const taskList = await ensureTaskList(feature, featureName);
+
+    if (taskList.length === 0) {
+      const tasksPath = path.join(process.cwd(), `.morph/features/${featureName}/3-tasks/tasks.md`);
+      const tasksExist = await fs.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`);
+    }
+
     const task = taskList.find(t => t.id === taskId);
 
     if (!task) {
-      throw new Error(`Task ${taskId} not found`);
+      throw new Error(`Task ${taskId} not found in '${featureName}' (${taskList.length} tasks available: ${taskList.map(t => t.id).join(', ')})`);
     }
 
     if (task.status === 'completed') {

package/claude-plugin.json

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

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

package/docs/QUICKSTART.md

@@ -203,4 +203,4 @@ morph-spec doctor
 
 ---
 
-*morph-spec v4.8.7 by Polymorphism Tech*
+*morph-spec v4.8.8 by Polymorphism Tech*