@polymorphism-tech/morph-spec 4.2.0 → 4.3.1

package/bin/morph-spec.js

@@ -60,8 +60,44 @@ import searchPatternsProgram from '../src/commands/learning/search-patterns.js';
 // Utility commands
 import troubleshootCommand from '../src/commands/utils/troubleshoot.js';
 import { sessionSummaryCommand } from '../src/commands/utils/session-summary.js';
-import migrateStateProgram from '../src/commands/utils/migrate-state.js';
-import upgradeProgram from '../src/commands/utils/upgrade.js';
+
+// Thread, Analytics, Core Four commands
+import {
+  threadsListCommand, threadsStatusCommand, threadsKillCommand,
+  threadsAnalyticsCommand, threadsWaitAllCommand, threadsWaitAnyCommand
+} from '../src/commands/threads/threads.js';
+import {
+  analyticsFeatureCommand, analyticsContextCommand, analyticsProjectCommand
+} from '../src/commands/analytics/analytics.js';
+import { coreFourCommand } from '../src/commands/context/core-four.js';
+
+// Context Optimization commands
+import { mcpOptimizeCommand, mcpListCommand } from '../src/commands/mcp/mcp.js';
+import {
+  microAgentCreateCommand, microAgentListCommand, microAgentShowCommand
+} from '../src/commands/agents/micro-agent.js';
+import { contextPrimeCommand } from '../src/commands/context/context-prime.js';
+
+// Parallelization commands
+import {
+  squadTemplateListCommand, squadTemplateUseCommand, squadTemplateShowCommand
+} from '../src/commands/agents/squad-template.js';
+import {
+  threadTemplateListCommand, threadTemplateUseCommand
+} from '../src/commands/threads/thread-template.js';
+import { spawnTeamParallelCommand } from '../src/commands/agents/spawn-team.js';
+
+// Fusion commands
+import { agentsFuseCommand, agentsReviewAggregateCommand } from '../src/commands/agents/agents-fuse.js';
+
+// Meta-Prompts (HOP) commands
+import { hopRenderCommand, hopListCommand } from '../src/commands/templates/template-render.js';
+
+// Trust commands
+import {
+  trustStatusCommand, trustSetCommand, trustHistoryCommand,
+  trustAutoCalculateCommand, trustClearCommand
+} from '../src/commands/trust/trust.js';
 
 // Libraries
 import { LearningSystem } from '../src/lib/learning/learning-system.js';
@@ -105,6 +141,7 @@ program
 program
   .command('doctor')
   .description('Check MORPH installation health')
+  .option('--full', 'Run full health check (lib files, commands, HOPs, standards, agents, state)')
   .action(doctorCommand);
 
 program
@@ -219,7 +256,7 @@ generateCommand
   .description('Auto-generate recap.md from project data (state, validation, contracts)')
   .option('--quiet', 'Suppress output')
   .action(async (feature, options) => {
-    const { generateRecap } = await import('../src/lib/recap-generator.js');
+    const { generateRecap } = await import('../src/lib/generators/recap-generator.js');
     await generateRecap('.', feature, options);
   });
 
@@ -423,6 +460,53 @@ templateCommand
   .option('-v, --verbose', 'Show detailed validation information')
   .action(templateValidateCommand);
 
+// HOP (Higher-Order Prompts) commands
+const hopCommand = program
+  .command('hop')
+  .description('Higher-Order Prompts — render and manage meta-prompt templates');
+
+hopCommand
+  .command('list')
+  .description('List all available HOP templates')
+  .action(hopListCommand);
+
+hopCommand
+  .command('render <hop-id> [output-path]')
+  .description('Render a HOP template with variables')
+  .option('--variables <json>', 'Variables JSON string', '{}')
+  .option('--dry-run', 'Preview without writing file')
+  .action((hopId, outputPath, options) => hopRenderCommand(hopId, outputPath, options.variables, options));
+
+// Trust commands
+const trustCommand = program
+  .command('trust')
+  .description('Trust level management for zero-touch execution');
+
+trustCommand
+  .command('status [feature]')
+  .description('Show trust level and auto-approval status')
+  .action(trustStatusCommand);
+
+trustCommand
+  .command('set <feature> <level> [reason]')
+  .description('Manually set trust level (low|medium|high|maximum)')
+  .action(trustSetCommand);
+
+trustCommand
+  .command('history')
+  .description('Show trust history for all features')
+  .action(trustHistoryCommand);
+
+trustCommand
+  .command('auto-calculate <feature>')
+  .description('Recalculate trust from checkpoint history')
+  .action(trustAutoCalculateCommand);
+
+trustCommand
+  .command('clear <feature>')
+  .description('Clear manual trust override (revert to calculated)')
+  .action(trustClearCommand);
+
 // Troubleshooting command
 program
   .command('troubleshoot <keywords...>')
@@ -467,7 +551,7 @@ program
   .option('-v, --verbose', 'Show detailed output')
   .action(rollbackPhaseCommand);
 
-// Approval workflow commands (MORPH-SPEC 3.0)
+// Approval workflow commands
 program
   .command('approve <feature> <gate>')
   .description('Approve a phase gate (design, tasks, uiux, proposal)')
@@ -486,7 +570,7 @@ program
   .option('--json', 'Output as JSON')
   .action((feature, options) => approvalStatusCommand(feature, options));
 
-// Agent team spawning (MORPH-SPEC 3.0)
+// Agent team spawning
 program
   .command('spawn-team <feature>')
   .description('Generate agent team configuration for Task tool')
@@ -494,13 +578,204 @@ program
   .option('--verbose', 'Show detailed team configuration')
   .action((feature, options) => spawnTeamCommand(feature, options));
 
-// Pattern learning system (MORPH-SPEC 3.0) - Add as subcommands
+// Pattern learning system - Add as subcommands
 program.addCommand(capturePatternProgram);
 program.addCommand(searchPatternsProgram);
 
-// Migration and upgrade commands (MORPH-SPEC 3.0) - Add as subcommands
-program.addCommand(migrateStateProgram);
-program.addCommand(upgradeProgram);
+// ─────────────────────────────────────────────────────────────────────────────
+// Thread Management
+// ─────────────────────────────────────────────────────────────────────────────
+const threadsCommand = program
+  .command('threads')
+  .description('Thread lifecycle management');
+
+threadsCommand
+  .command('list')
+  .description('List threads (optionally filtered by feature/status/type)')
+  .option('--feature <feature>', 'Filter by feature name')
+  .option('--status <status>', 'Filter by status (pending|running|completed|failed|killed)')
+  .option('--type <type>', 'Filter by type (base|parallel|fusion|long-running|zero-touch)')
+  .action((options) => threadsListCommand(options));
+
+threadsCommand
+  .command('status <id>')
+  .description('Show detailed status of a thread')
+  .action((id) => threadsStatusCommand(id));
+
+threadsCommand
+  .command('kill <id>')
+  .description('Terminate a running thread')
+  .action((id) => threadsKillCommand(id));
+
+threadsCommand
+  .command('analytics')
+  .description('Show thread analytics dashboard for a feature')
+  .option('--feature <feature>', 'Feature name (required)')
+  .action((options) => threadsAnalyticsCommand(options));
+
+threadsCommand
+  .command('wait-all <feature>')
+  .description('Block until all threads for a feature complete')
+  .option('--timeout <minutes>', 'Timeout in minutes (default: 60)', '60')
+  .action((feature, options) => threadsWaitAllCommand(feature, options));
+
+threadsCommand
+  .command('wait-any <feature>')
+  .description('Block until any thread for a feature completes')
+  .option('--timeout <minutes>', 'Timeout in minutes (default: 60)', '60')
+  .action((feature, options) => threadsWaitAnyCommand(feature, options));
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Analytics
+// ─────────────────────────────────────────────────────────────────────────────
+const analyticsCommand = program
+  .command('analytics')
+  .description('Metrics and analytics dashboards');
+
+analyticsCommand
+  .command('feature <name>')
+  .description('Show thread analytics dashboard for a feature')
+  .action((name, options) => analyticsFeatureCommand(name, options));
+
+analyticsCommand
+  .command('context <name>')
+  .description('Show context token usage and optimization opportunities')
+  .action((name, options) => analyticsContextCommand(name, options));
+
+analyticsCommand
+  .command('project')
+  .description('Show project-wide analytics dashboard (30-day summary)')
+  .option('--period <days>', 'Period in days (default: 30)', '30')
+  .action((options) => analyticsProjectCommand(options));
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Core Four
+// ─────────────────────────────────────────────────────────────────────────────
+program
+  .command('core-four <feature>')
+  .description('Show Core Four dashboard: Context/Model/Prompt/Tools')
+  .option('--json', 'Output as JSON')
+  .action((feature, options) => coreFourCommand(feature, options));
+
+// ─────────────────────────────────────────────────────────────────────────────
+// MCP Optimizer
+// ─────────────────────────────────────────────────────────────────────────────
+const mcpCommand = program
+  .command('mcp')
+  .description('MCP server analysis and optimization');
+
+mcpCommand
+  .command('optimize')
+  .description('Analyze MCP servers and suggest optimizations')
+  .action((options) => mcpOptimizeCommand(options));
+
+mcpCommand
+  .command('list')
+  .description('List configured MCP servers with usage stats')
+  .action((options) => mcpListCommand(options));
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Micro Agents
+// ─────────────────────────────────────────────────────────────────────────────
+const microAgentCommand = program
+  .command('micro-agent')
+  .description('Create and manage ultra-specialized micro-agents');
+
+microAgentCommand
+  .command('create <name>')
+  .description('Create a new micro-agent')
+  .option('--base-agent <agent>', 'Base agent ID to specialize from')
+  .option('--mission <mission>', 'Single focused mission for this agent')
+  .option('--standards <files>', 'Comma-separated standards files to load (1-3 max)')
+  .option('--tools <tools>', 'Comma-separated tools to allow (default: Read,Write,Edit)')
+  .action((name, options) => microAgentCreateCommand(name, options));
+
+microAgentCommand
+  .command('list')
+  .description('List all micro-agents')
+  .action((options) => microAgentListCommand(options));
+
+microAgentCommand
+  .command('show <name>')
+  .description('Show micro-agent details')
+  .option('--show-prompt', 'Show the generated system prompt')
+  .action((name, options) => microAgentShowCommand(name, options));
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Context Prime
+// ─────────────────────────────────────────────────────────────────────────────
+program
+  .command('prime [type]')
+  .description('Output context priming file (feature|bug|refactor|design|infra)')
+  .option('--json', 'Output as JSON')
+  .action((type, options) => contextPrimeCommand(type, options));
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Fusion (F-Thread)
+// ─────────────────────────────────────────────────────────────────────────────
+const agentsFuseCmd = program
+  .command('agents-fuse')
+  .description('F-Thread fusion execution: run N agents, aggregate best result');
+
+agentsFuseCmd
+  .command('run')
+  .description('Run fusion: spawn N agents with same prompt, aggregate results')
+  .option('--prompt <prompt>', 'Prompt/mission for all fusion agents (required)')
+  .option('--count <n>', 'Number of agents to run (default: 3)', '3')
+  .option('--strategy <strategy>', 'Aggregation strategy: best-of-n | consensus | manual-select', 'best-of-n')
+  .option('--feature <feature>', 'Feature name for tracking')
+  .option('--agents <list>', 'Comma-separated agent IDs to use')
+  .option('--json', 'Output as JSON')
+  .action((options) => agentsFuseCommand(options));
+
+agentsFuseCmd
+  .command('aggregate-reviews <feature>')
+  .description('Aggregate review results from N agents')
+  .option('--agents <list>', 'Comma-separated agent IDs (required)')
+  .option('--strategy <strategy>', 'Aggregation strategy', 'best-of-n')
+  .action((feature, options) => agentsReviewAggregateCommand(feature, options));
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Squad Templates
+// ─────────────────────────────────────────────────────────────────────────────
+const squadTemplateCmd = program
+  .command('squad-template')
+  .description('Squad template management for parallel execution');
+
+squadTemplateCmd
+  .command('list')
+  .description('List available squad templates')
+  .action((options) => squadTemplateListCommand(options));
+
+squadTemplateCmd
+  .command('use <template-id>')
+  .description('Configure a feature to use a squad template')
+  .option('--feature <feature>', 'Feature name (required)')
+  .action((id, options) => squadTemplateUseCommand(id, options));
+
+squadTemplateCmd
+  .command('show <template-id>')
+  .description('Show squad template details')
+  .option('--json', 'Output as JSON')
+  .action((id, options) => squadTemplateShowCommand(id, options));
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Commands — Thread Templates
+// ─────────────────────────────────────────────────────────────────────────────
+const threadTemplateCmd = program
+  .command('thread-template')
+  .description('Thread type management');
+
+threadTemplateCmd
+  .command('list')
+  .description('List available thread types (B/P/F/L/Z-Thread)')
+  .action((options) => threadTemplateListCommand(options));
+
+threadTemplateCmd
+  .command('use <type>')
+  .description('Configure thread type for a feature')
+  .option('--feature <feature>', 'Feature name (required)')
+  .action((type, options) => threadTemplateUseCommand(type, options));
 
 // Wire global --stack flag to stack-resolver before any command executes
 program.hook('preAction', () => {

package/bin/task-manager.cjs

@@ -8,6 +8,7 @@
  */
 
 const fs = require('fs').promises;
+const fsSync = require('fs');
 const path = require('path');
 
 // Simple ANSI color helpers (chalk v5 is ESM-only, can't require in CJS)
@@ -22,6 +23,68 @@ const chalk = {
   bold: (s) => `\x1b[1m${s}\x1b[0m`,
 };
 
+// ============================================================================
+// v3 Schema Helpers
+// ============================================================================
+
+/**
+ * Parse tasks.md to extract task stubs for v3 state format.
+ * Looks for headings like: ### T001 — Task title
+ */
+async function parseTasksMd(featureName) {
+  const tasksPath = path.join(process.cwd(), `.morph/project/outputs/${featureName}/tasks.md`);
+  let content = '';
+  try {
+    content = await fs.readFile(tasksPath, 'utf-8');
+  } catch {
+    return [];
+  }
+
+  const tasks = [];
+  const headingRe = /^###\s+(T\d+)\s+[—–-]\s+(.+)$/gm;
+  let match;
+  while ((match = headingRe.exec(content)) !== null) {
+    tasks.push({
+      id: match[1],
+      title: match[2].trim(),
+      status: 'pending',
+      dependencies: [],
+      files: [],
+      checkpoint: null
+    });
+  }
+  return tasks;
+}
+
+/**
+ * Ensure feature.taskList exists (array of individual task objects).
+ * In v3 state, feature.tasks is a counter object {total, completed, ...}.
+ * Individual task objects live in feature.taskList.
+ */
+async function ensureTaskList(feature, featureName) {
+  if (Array.isArray(feature.tasks)) {
+    // v2 format: tasks IS the array
+    return feature.tasks;
+  }
+  // v3 format: use taskList or build from tasks.md
+  if (!feature.taskList || feature.taskList.length === 0) {
+    feature.taskList = await parseTasksMd(featureName);
+  }
+  return feature.taskList;
+}
+
+/**
+ * After modifying taskList, sync counts back to feature.tasks counter.
+ */
+function syncCounters(feature) {
+  if (Array.isArray(feature.tasks)) return; // v2, nothing to sync
+  const list = feature.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
+}
+
 class TaskManager {
   constructor(statePath = '.morph/state.json') {
     this.statePath = statePath;
@@ -46,7 +109,12 @@ class TaskManager {
    * Save state.json
    */
   async saveState(state) {
-    state.project.updatedAt = new Date().toISOString();
+    // v3 state uses metadata.lastUpdated, v2 used project.updatedAt
+    if (state.metadata) {
+      state.metadata.lastUpdated = new Date().toISOString();
+    } else if (state.project) {
+      state.project.updatedAt = new Date().toISOString();
+    }
     await fs.writeFile(this.statePath, JSON.stringify(state, null, 2), 'utf-8');
   }
 
@@ -65,11 +133,12 @@ class TaskManager {
       throw new Error(`Feature '${featureName}' not found in state.json`);
     }
 
+    const taskList = await ensureTaskList(feature, featureName);
     const results = [];
     const tasksToComplete = [];
 
     for (const taskId of taskIds) {
-      const task = feature.tasks.find(t => t.id === taskId);
+      const task = taskList.find(t => t.id === taskId);
 
       if (!task) {
         console.error(chalk.red(`❌ Task ${taskId} not found`));
@@ -82,7 +151,7 @@ class TaskManager {
       }
 
       // Validate dependencies
-      const missingDeps = this.checkDependencies(task, feature.tasks);
+      const missingDeps = this.checkDependencies(task, taskList);
       if (missingDeps.length > 0) {
         console.error(chalk.red(`❌ Cannot complete ${taskId}: missing dependencies: ${missingDeps.join(', ')}`));
         continue;
@@ -118,11 +187,12 @@ class TaskManager {
       }
     }
 
-    // Update progress
-    feature.progress = this.calculateProgress(feature.tasks);
+    // Sync v3 counters then compute progress
+    syncCounters(feature);
+    feature.progress = this.calculateProgress(taskList);
 
     // Auto-checkpoint every 3 tasks
-    const recentCompleted = this.getRecentCompleted(feature.tasks, 3);
+    const recentCompleted = this.getRecentCompleted(taskList, 3);
     if (recentCompleted.length === 3) {
       const lastCheckpoint = feature.checkpoints[feature.checkpoints.length - 1];
       const shouldAutoCheckpoint = !lastCheckpoint ||
@@ -138,6 +208,21 @@ class TaskManager {
     // Save state
     await this.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);
 
@@ -145,7 +230,7 @@ class TaskManager {
     this.displayProgress(feature);
 
     // Suggest next task
-    const nextTask = this.getNextTask(feature.tasks);
+    const nextTask = this.getNextTask(taskList);
     if (nextTask) {
       console.log(chalk.cyan(`\n⏭️  Next: ${nextTask.id} - ${nextTask.title}`));
       if (nextTask.dependencies && nextTask.dependencies.length > 0) {
@@ -167,7 +252,7 @@ class TaskManager {
     try {
       console.log(chalk.cyan('\n🔍 Running code validation...'));
 
-      const { runValidation, formatValidationResults } = await import('../src/lib/validation-runner.js');
+      const { runValidation, formatValidationResults } = await import('../src/lib/validators/validation-runner.js');
       const result = await runValidation('.', featureName, { verbose: true });
 
       formatValidationResults(result);
@@ -243,7 +328,7 @@ class TaskManager {
 
     // Run checkpoint hooks (new enhanced validation system)
     try {
-      const { runCheckpointHooks, shouldRunCheckpoint } = await import('../src/lib/checkpoint-hooks.js');
+      const { runCheckpointHooks, shouldRunCheckpoint } = await import('../src/lib/checkpoints/checkpoint-hooks.js');
 
       if (shouldRunCheckpoint(tasksCompleted, 3)) {
         checkpointResult = await runCheckpointHooks(featureName, checkpointNum);
@@ -268,7 +353,7 @@ class TaskManager {
       // 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/validation-runner.js');
+        const { runValidation } = await import('../src/lib/validators/validation-runner.js');
         const result = await runValidation('.', featureName, { verbose: false });
         validationNote = result.passed
           ? ' | Validation: PASSED'
@@ -333,7 +418,7 @@ class TaskManager {
         return;
       }
 
-      const { extractFeatureMetadata } = await import('../src/lib/metadata-extractor.js');
+      const { extractFeatureMetadata } = await import('../src/lib/generators/metadata-extractor.js');
       const metadata = extractFeatureMetadata(feature);
 
       const outputPath = path.join(
@@ -410,7 +495,8 @@ class TaskManager {
       throw new Error(`Feature '${featureName}' not found`);
     }
 
-    const task = feature.tasks.find(t => t.id === taskId);
+    const taskList = await ensureTaskList(feature, featureName);
+    const task = taskList.find(t => t.id === taskId);
 
     if (!task) {
       throw new Error(`Task ${taskId} not found`);
@@ -422,13 +508,14 @@ class TaskManager {
     }
 
     // Validate dependencies
-    const missingDeps = this.checkDependencies(task, feature.tasks);
+    const missingDeps = this.checkDependencies(task, taskList);
     if (missingDeps.length > 0) {
       throw new Error(`Cannot start ${taskId}: missing dependencies: ${missingDeps.join(', ')}`);
     }
 
     task.status = 'in_progress';
     task.startedAt = new Date().toISOString();
+    syncCounters(feature);
 
     await this.saveState(state);
 
@@ -446,7 +533,8 @@ class TaskManager {
       throw new Error(`Feature '${featureName}' not found`);
     }
 
-    const nextTask = this.getNextTask(feature.tasks);
+    const taskList = await ensureTaskList(feature, featureName);
+    const nextTask = this.getNextTask(taskList);
 
     if (nextTask) {
       console.log(chalk.cyan(`\n⏭️  Next task: ${nextTask.id} - ${nextTask.title}`));

package/bin/validate.js

@@ -17,9 +17,9 @@
  */
 
 import chalk from 'chalk';
-import { validatePackages } from '../src/lib/validators/package-validator.js';
-import { validateArchitecture } from '../src/lib/validators/architecture-validator.js';
-import { validateContrast } from '../src/lib/validators/ui-contrast-validator.js';
+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';
 import { LearningSystem } from '../src/lib/learning/learning-system.js';
 
 const VALIDATORS = {
@@ -51,7 +51,7 @@ const VALIDATORS = {
 async function validateSpecVsTasks(projectPath, options = {}) {
   const path = await import('path');
   const fs = await import('fs');
-  const { loadState } = await import('../src/lib/state-manager.js');
+  const { loadState } = await import('../src/core/state/state-manager.js');
 
   const results = [];
   let errors = 0;

package/docs/{v3.0 → next-generation}/AGENTS.md

@@ -485,7 +485,7 @@
 ```json
 {
   "squadConfigs": {
-    "full-stack-v3": {
+    "full-stack": {
       "parallel": true,
       "agents": [
         "dotnet-senior",