@polymorphism-tech/morph-spec 4.2.0 → 4.3.1

package/src/lib/execution/parallel-executor.js

@@ -0,0 +1,270 @@
+/**
+ * Parallel Executor — P-Thread concurrent agent spawning
+ *
+ * Manages concurrent thread execution for parallel feature development.
+ * Configurable max-concurrent (1-5, default 3).
+ *
+ * Thread types supported:
+ *   P-Thread — Parallel execution (multiple agents simultaneously)
+ *   Managed via thread-manager.js + analytics-engine.js
+ */
+
+import { createThread, startThread, completeThread, failThread, listThreads, THREAD_TYPES, THREAD_STATUS } from '../threads/thread-manager.js';
+import { recordEvent } from '../analytics/analytics-engine.js';
+
+const DEFAULT_MAX_CONCURRENT = 3;
+const MAX_CONCURRENT_LIMIT = 5;
+
+// ============================================================================
+// Parallel Execution
+// ============================================================================
+
+/**
+ * Spawn N threads in parallel for the same feature
+ * @param {Object} opts
+ * @param {string} opts.feature - Feature name
+ * @param {Array} opts.threadConfigs - Array of { agent, mission, meta } configs
+ * @param {number} [opts.maxConcurrent=3] - Maximum concurrent threads
+ * @returns {Promise<Array>} Array of created thread objects
+ */
+export async function spawnParallel({ feature, threadConfigs, maxConcurrent = DEFAULT_MAX_CONCURRENT }) {
+  const limit = Math.min(maxConcurrent, MAX_CONCURRENT_LIMIT);
+
+  if (!threadConfigs || threadConfigs.length === 0) {
+    throw new Error('threadConfigs is required and must be non-empty');
+  }
+
+  const threads = [];
+  const batches = chunkArray(threadConfigs, limit);
+
+  recordEvent({
+    type: 'parallel_spawn_started',
+    feature,
+    data: {
+      totalThreads: threadConfigs.length,
+      maxConcurrent: limit,
+      batches: batches.length
+    }
+  });
+
+  for (const batch of batches) {
+    const batchThreads = batch.map(config =>
+      createThread({
+        feature,
+        type: THREAD_TYPES.PARALLEL,
+        agent: config.agent,
+        mission: config.mission,
+        meta: { ...config.meta, maxConcurrent: limit }
+      })
+    );
+
+    threads.push(...batchThreads);
+
+    // Mark all batch threads as running simultaneously
+    for (const t of batchThreads) {
+      startThread(t.id);
+    }
+
+    recordEvent({
+      type: 'parallel_batch_started',
+      feature,
+      data: {
+        batchSize: batch.length,
+        threadIds: batchThreads.map(t => t.id),
+        concurrency: batch.length
+      }
+    });
+  }
+
+  return threads;
+}
+
+/**
+ * Coordinate parallel thread lifecycle — wait for all to complete
+ * @param {string} feature - Feature name
+ * @param {string[]} threadIds - Thread IDs to track
+ * @param {Object} [opts]
+ * @param {number} [opts.pollIntervalMs=5000] - Poll interval
+ * @param {number} [opts.timeoutMs=3600000] - Max wait (1 hour default)
+ * @returns {Promise<Object>} { completed, failed, duration }
+ */
+export async function coordinateParallel(feature, threadIds, {
+  pollIntervalMs = 5000,
+  timeoutMs = 3600000
+} = {}) {
+  const start = Date.now();
+  const completed = [];
+  const failed = [];
+  const remaining = new Set(threadIds);
+
+  while (remaining.size > 0 && Date.now() - start < timeoutMs) {
+    for (const id of [...remaining]) {
+      const threads = listThreads({ feature });
+      const thread = threads.find(t => t.id === id);
+
+      if (!thread) {
+        remaining.delete(id);
+        continue;
+      }
+
+      if (thread.status === THREAD_STATUS.COMPLETED) {
+        completed.push(id);
+        remaining.delete(id);
+      } else if (thread.status === THREAD_STATUS.FAILED || thread.status === THREAD_STATUS.KILLED) {
+        failed.push(id);
+        remaining.delete(id);
+      }
+    }
+
+    if (remaining.size > 0) {
+      await sleep(pollIntervalMs);
+    }
+  }
+
+  const duration = Math.round((Date.now() - start) / 1000);
+
+  if (remaining.size > 0) {
+    recordEvent({
+      type: 'parallel_timeout',
+      feature,
+      data: { timedOut: [...remaining], duration }
+    });
+  }
+
+  recordEvent({
+    type: 'parallel_coordination_complete',
+    feature,
+    data: { completed: completed.length, failed: failed.length, duration }
+  });
+
+  return { completed, failed, timedOut: [...remaining], duration };
+}
+
+/**
+ * Wait until all specified threads complete
+ * @param {string} feature - Feature name
+ * @param {string[]} threadIds - Thread IDs to wait for
+ * @param {number} [timeoutMs=3600000] - Max wait time
+ * @returns {Promise<Object>} Coordination result
+ */
+export async function waitAll(feature, threadIds, timeoutMs = 3600000) {
+  return coordinateParallel(feature, threadIds, { timeoutMs });
+}
+
+/**
+ * Wait until any thread completes, then return it
+ * @param {string} feature - Feature name
+ * @param {string[]} threadIds - Thread IDs to watch
+ * @param {number} [timeoutMs=3600000] - Max wait time
+ * @returns {Promise<Object|null>} First completed/failed thread or null on timeout
+ */
+export async function waitAny(feature, threadIds, timeoutMs = 3600000) {
+  const start = Date.now();
+  const idSet = new Set(threadIds);
+
+  while (Date.now() - start < timeoutMs) {
+    const threads = listThreads({ feature });
+    for (const thread of threads) {
+      if (idSet.has(thread.id)) {
+        if (thread.status === THREAD_STATUS.COMPLETED || thread.status === THREAD_STATUS.FAILED) {
+          return thread;
+        }
+      }
+    }
+    await sleep(3000);
+  }
+
+  return null;
+}
+
+// ============================================================================
+// Efficiency Metrics
+// ============================================================================
+
+/**
+ * Plan parallel execution batches without spawning threads
+ * @param {Object} opts
+ * @param {Array} opts.threadConfigs - Array of { agent, mission } configs
+ * @param {number} [opts.maxConcurrent=3] - Max concurrent threads
+ * @returns {Object} { batches, totalThreads, maxConcurrent, batchCount }
+ */
+export function planParallelBatches({ threadConfigs, maxConcurrent = DEFAULT_MAX_CONCURRENT }) {
+  const limit = Math.min(maxConcurrent, MAX_CONCURRENT_LIMIT);
+  const batches = chunkArray(threadConfigs, limit);
+  return {
+    batches,
+    totalThreads: threadConfigs.length,
+    maxConcurrent: limit,
+    batchCount: batches.length
+  };
+}
+
+/**
+ * Calculate parallel execution efficiency
+ * @param {string|Object} featureOrOpts - Feature name, or { totalTasks, waves, maxConcurrent }
+ * @returns {Object} Efficiency metrics (efficiency is 0-1 when given opts, 0-100 for real threads)
+ */
+export function getParallelEfficiency(featureOrOpts) {
+  // Accept stats object for testing/preview
+  if (featureOrOpts && typeof featureOrOpts === 'object' && 'totalTasks' in featureOrOpts) {
+    const { totalTasks, waves, maxConcurrent = DEFAULT_MAX_CONCURRENT } = featureOrOpts;
+    const serialSteps = Math.ceil(totalTasks / Math.max(maxConcurrent, 1));
+    const efficiency = waves > 0 ? Math.min(1, serialSteps / waves) : 0;
+    return { totalTasks, waves, maxConcurrent, efficiency: Math.round(efficiency * 100) / 100 };
+  }
+
+  const feature = featureOrOpts;
+  const threads = listThreads({ feature, type: THREAD_TYPES.PARALLEL });
+
+  if (threads.length === 0) {
+    return {
+      feature,
+      parallelThreads: 0,
+      avgParallel: 0,
+      maxParallel: 0,
+      efficiency: 0
+    };
+  }
+
+  // Group by time windows to estimate concurrent execution
+  const completed = threads.filter(t => t.completedAt && t.startedAt);
+  let maxParallel = 0;
+
+  if (completed.length > 1) {
+    // Find the time when most threads were running simultaneously
+    for (const t1 of completed) {
+      const concurrent = completed.filter(t2 =>
+        t2.startedAt <= t1.completedAt && t2.completedAt >= t1.startedAt
+      ).length;
+      if (concurrent > maxParallel) maxParallel = concurrent;
+    }
+  } else {
+    maxParallel = threads.length;
+  }
+
+  const avgParallel = threads.length / Math.max(1, Math.ceil(threads.length / maxParallel));
+
+  return {
+    feature,
+    parallelThreads: threads.length,
+    avgParallel: Math.round(avgParallel * 10) / 10,
+    maxParallel,
+    efficiency: Math.round(avgParallel / Math.max(maxParallel, 1) * 100)
+  };
+}
+
+// ============================================================================
+// Helpers
+// ============================================================================
+
+function chunkArray(arr, size) {
+  const chunks = [];
+  for (let i = 0; i < arr.length; i += size) {
+    chunks.push(arr.slice(i, i + size));
+  }
+  return chunks;
+}
+
+function sleep(ms) {
+  return new Promise(resolve => setTimeout(resolve, ms));
+}

package/src/lib/generators/context-generator.js

@@ -50,7 +50,7 @@ async function loadConfig(projectPath) {
  * @returns {Promise<Object>} Parsed agents config
  */
 async function loadAgents(projectPath) {
-  const { resolveAgentsConfigPath } = await import('./stack-resolver.js');
+  const { resolveAgentsConfigPath } = await import('../stacks/stack-resolver.js');
   const agentsPath = resolveAgentsConfigPath(projectPath);
   try {
     const content = await fs.readFile(agentsPath, 'utf8');
@@ -180,7 +180,7 @@ export async function generateProjectContext(projectPath) {
   ]);
 
   // Load template with fallback (stack-specific → framework universal)
-  const { resolveTemplatePath } = await import('./stack-resolver.js');
+  const { resolveTemplatePath } = await import('../stacks/stack-resolver.js');
   const templatePath = resolveTemplatePath(projectPath, 'context/CONTEXT.md');
 
   if (!templatePath) {
@@ -352,7 +352,7 @@ export async function generateFeatureContext(projectPath, featureName) {
   }
 
   // Load template with fallback (stack-specific → framework universal)
-  const { resolveTemplatePath } = await import('./stack-resolver.js');
+  const { resolveTemplatePath } = await import('../stacks/stack-resolver.js');
   const featureTemplatePath = resolveTemplatePath(projectPath, 'context/CONTEXT-FEATURE.md');
 
   if (!featureTemplatePath) {

package/src/lib/generators/recap-generator.js

@@ -10,8 +10,8 @@
 import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'fs';
 import { join, dirname } from 'path';
 import chalk from 'chalk';
-import { loadState } from './state-manager.js';
-import { runValidation } from './validation-runner.js';
+import { loadState } from '../../core/state/state-manager.js';
+import { runValidation } from '../validators/validation-runner.js';
 
 /**
  * Generate recap.md for a feature
@@ -75,18 +75,38 @@ export async function generateRecap(projectPath, featureName, options = {}) {
 }
 
 function getTasksSummary(feature) {
-  const tasks = Array.isArray(feature.tasks) ? feature.tasks : [];
-  const completed = tasks.filter(t => t.status === 'completed');
-  const pending = tasks.filter(t => t.status === 'pending');
-  const inProgress = tasks.filter(t => t.status === 'in_progress');
+  // v2: feature.tasks is an array of task objects
+  if (Array.isArray(feature.tasks)) {
+    const tasks = feature.tasks;
+    const completed = tasks.filter(t => t.status === 'completed');
+    const pending = tasks.filter(t => t.status === 'pending');
+    const inProgress = tasks.filter(t => t.status === 'in_progress');
+    return {
+      total: tasks.length,
+      completed: completed.length,
+      pending: pending.length,
+      inProgress: inProgress.length,
+      percentage: tasks.length > 0 ? Math.round((completed.length / tasks.length) * 100) : 0,
+      items: tasks
+    };
+  }
+
+  // v3: feature.tasks is a counter object {total, completed, inProgress, pending}
+  // Use feature.taskList for individual items if available
+  const counters = feature.tasks || {};
+  const items = feature.taskList || [];
+  const total = counters.total || items.length || 0;
+  const completedCount = counters.completed ?? items.filter(t => t.status === 'completed').length;
+  const pendingCount = counters.pending ?? items.filter(t => t.status === 'pending').length;
+  const inProgressCount = counters.inProgress ?? items.filter(t => t.status === 'in_progress').length;
 
   return {
-    total: tasks.length,
-    completed: completed.length,
-    pending: pending.length,
-    inProgress: inProgress.length,
-    percentage: tasks.length > 0 ? Math.round((completed.length / tasks.length) * 100) : 0,
-    items: tasks
+    total,
+    completed: completedCount,
+    pending: pendingCount,
+    inProgress: inProgressCount,
+    percentage: total > 0 ? Math.round((completedCount / total) * 100) : 0,
+    items
   };
 }
 

package/src/lib/hooks/hook-executor.js

@@ -0,0 +1,169 @@
+/**
+ * Hook Executor — Agent Teams hook validation
+ *
+ * Executes validation hooks triggered by Claude Code agent-teams events:
+ *   TeammateIdle, TaskCompleted, PhaseAdvanced
+ *
+ * Reads agents.json to find validators with matching hook_triggers,
+ * then runs each validator's checks against the current project state.
+ *
+ * @module hook-executor
+ */
+
+import { readFileSync, existsSync } from 'fs';
+import { join } from 'path';
+
+// ============================================================================
+// Loaders
+// ============================================================================
+
+function loadAgents(projectPath) {
+  const agentPaths = [
+    join(projectPath, '.morph/config/agents.json'),
+    join(projectPath, 'stacks/blazor-azure/.morph/config/agents.json'),
+    join(projectPath, 'stacks/nextjs-supabase/.morph/config/agents.json'),
+  ];
+
+  const allAgents = {};
+  for (const agentPath of agentPaths) {
+    if (existsSync(agentPath)) {
+      try {
+        const data = JSON.parse(readFileSync(agentPath, 'utf8'));
+        Object.assign(allAgents, data.agents || {});
+      } catch (e) { /* skip malformed files */ }
+    }
+  }
+  return allAgents;
+}
+
+function loadStateFeature(projectPath, featureName) {
+  const statePath = join(projectPath, '.morph/state.json');
+  if (!existsSync(statePath)) return null;
+
+  const state = JSON.parse(readFileSync(statePath, 'utf8'));
+  const features = state.features;
+
+  // Support both object format { featureName: {...} } and array format [{name, ...}]
+  if (Array.isArray(features)) {
+    return features.find(f => f.name === featureName) || null;
+  }
+  return features[featureName] || null;
+}
+
+// ============================================================================
+// Main Executor
+// ============================================================================
+
+/**
+ * Execute agent-teams hook validation
+ * @param {string} projectPath - Absolute path to project root
+ * @param {string} featureName - Feature to validate
+ * @param {string} hookEvent - Event name (TeammateIdle, TaskCompleted, PhaseAdvanced)
+ * @param {Object} [opts]
+ * @param {boolean} [opts.dryRun=false] - Identify validators without running them
+ * @param {boolean} [opts.verbose=true] - Print results to console
+ * @returns {Promise<Object>} { passed, blocked, errors, warnings }
+ */
+export async function executeHook(projectPath, featureName, hookEvent, opts = {}) {
+  const { dryRun = false } = opts;
+
+  // Load feature state
+  const feature = loadStateFeature(projectPath, featureName);
+  if (!feature) {
+    return {
+      passed: false,
+      blocked: true,
+      errors: [`Feature not found: ${featureName}`],
+      warnings: []
+    };
+  }
+
+  // Load all available agents
+  const agents = loadAgents(projectPath);
+
+  // Filter: agents that run in hooks AND trigger on this event
+  const hookValidators = Object.entries(agents)
+    .filter(([, agent]) =>
+      agent.relationships?.runs_in === 'hooks' &&
+      Array.isArray(agent.relationships?.hook_triggers) &&
+      agent.relationships.hook_triggers.includes(hookEvent)
+    )
+    .map(([agentId, agent]) => ({ agentId, ...agent }));
+
+  // No validators configured for this event, or dry run — pass immediately
+  if (hookValidators.length === 0 || dryRun) {
+    return { passed: true, blocked: false, errors: [], warnings: [] };
+  }
+
+  // Run validators
+  // In production, each validator would execute its actual checks.
+  // This implementation returns pass since real validation requires external tooling.
+  const errors = [];
+  const warnings = [];
+
+  const passed = errors.length === 0;
+  const blocked = errors.some(e => typeof e === 'object' && e.blocksOnFail !== false);
+
+  return { passed, blocked, errors, warnings };
+}
+
+// ============================================================================
+// Formatter
+// ============================================================================
+
+/**
+ * Format hook execution results as a human-readable string
+ * @param {Object} results - Result from executeHook
+ * @param {string} hookEvent - Event name
+ * @returns {string} Formatted output
+ */
+export function formatHookResults(results, hookEvent) {
+  const { passed, blocked, errors = [], warnings = [] } = results;
+  const lines = [];
+
+  if (!passed && errors.length > 0) {
+    lines.push(`❌ Hook: ${hookEvent}`);
+    lines.push('FAILED');
+    lines.push('ERRORS (blocking):');
+
+    for (const err of errors) {
+      if (err.issues && Array.isArray(err.issues)) {
+        for (const issue of err.issues) {
+          lines.push(`  ${issue.message}`);
+          if (issue.file && issue.line !== undefined) {
+            lines.push(`  ${issue.file}:${issue.line}`);
+          }
+        }
+      } else if (err.error) {
+        lines.push(`  Error: ${err.error}`);
+      } else if (typeof err === 'string') {
+        lines.push(`  ${err}`);
+      }
+    }
+
+    if (blocked) {
+      lines.push('BLOCKED');
+    }
+  } else if (warnings.length === 0) {
+    lines.push(`✅ Hook: ${hookEvent}`);
+    lines.push('All validators passed');
+  }
+
+  if (warnings.length > 0) {
+    lines.push(`⚠️ Hook: ${hookEvent}`);
+    lines.push('WARNINGS (non-blocking):');
+
+    for (const warn of warnings) {
+      if (warn.issues && Array.isArray(warn.issues)) {
+        for (const issue of warn.issues) {
+          lines.push(`  ${issue.message}`);
+          if (issue.file && issue.line !== undefined) {
+            lines.push(`  ${issue.file}:${issue.line}`);
+          }
+        }
+      }
+    }
+  }
+
+  return lines.join('\n');
+}