@polymorphism-tech/morph-spec 4.2.0 → 4.3.0

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

@@ -0,0 +1,304 @@
+/**
+ * Fusion Executor — F-Thread best-of-N aggregation
+ *
+ * Runs N parallel agents on the same prompt, collects results,
+ * then aggregates using one of three strategies:
+ *   - best-of-n: score each result, pick highest (automated)
+ *   - consensus: merge common elements from all results
+ *   - manual-select: present all N to user for selection
+ *
+ * Returns: { winner, allResults, scores }
+ */
+
+import { createThread, startThread, completeThread, failThread, THREAD_TYPES } from '../threads/thread-manager.js';
+import { recordEvent, generateAsciiChart } from '../analytics/analytics-engine.js';
+
+// ============================================================================
+// Scoring
+// ============================================================================
+
+/**
+ * Score a fusion result based on completeness, compliance, and quality
+ * @param {Object} result - Agent result object
+ * @param {Object} [rubric] - Scoring rubric
+ * @returns {number} Score 0-100
+ */
+export function scoreResult(result, rubric = {}) {
+  let score = 0;
+  const weights = {
+    completeness: rubric.completenessWeight || 40,
+    checkpointCompliance: rubric.complianceWeight || 30,
+    codeQuality: rubric.qualityWeight || 30
+  };
+
+  // Completeness: does it have all required deliverables?
+  if (result.deliverables) {
+    const required = rubric.requiredDeliverables?.length || 1;
+    const provided = Object.keys(result.deliverables).length;
+    score += weights.completeness * Math.min(provided / required, 1.0);
+  } else if (result.content) {
+    // Estimate completeness from content length
+    const targetLength = rubric.targetLength || 1000;
+    score += weights.completeness * Math.min(result.content.length / targetLength, 1.0);
+  } else {
+    score += weights.completeness * 0.5; // Partial credit
+  }
+
+  // Checkpoint compliance: did it follow patterns?
+  if (result.checkpointsPassed !== undefined) {
+    const total = (result.checkpointsPassed || 0) + (result.checkpointsFailed || 0);
+    const passRate = total > 0 ? result.checkpointsPassed / total : 0.8; // Assume 80% if unknown
+    score += weights.checkpointCompliance * passRate;
+  } else {
+    score += weights.checkpointCompliance * 0.8; // Default: assume compliant
+  }
+
+  // Code quality: based on error count and warnings
+  const errors = result.errors || 0;
+  const warnings = result.warnings || 0;
+  const qualityScore = Math.max(0, 1.0 - (errors * 0.2) - (warnings * 0.05));
+  score += weights.codeQuality * qualityScore;
+
+  return Math.round(score);
+}
+
+// ============================================================================
+// Aggregation Strategies
+// ============================================================================
+
+/**
+ * Best-of-N aggregation: score each result, return highest scorer
+ * @param {Array} results - Array of agent results
+ * @param {Object} rubric - Scoring rubric
+ * @returns {Object} { winner, scores }
+ */
+export function aggregateBestOfN(results, rubric = {}) {
+  const scored = results.map((result, idx) => ({
+    index: idx,
+    agentId: result.agentId || `agent-${idx}`,
+    result,
+    score: scoreResult(result, rubric)
+  }));
+
+  scored.sort((a, b) => b.score - a.score);
+  const winner = scored[0];
+
+  return {
+    winner: winner.result,
+    winnerId: winner.agentId,
+    winnerScore: winner.score,
+    scores: scored.map(s => ({
+      agentId: s.agentId,
+      score: s.score,
+      rank: scored.indexOf(s) + 1
+    }))
+  };
+}
+
+/**
+ * Consensus aggregation: merge common elements from all results
+ * @param {Array} results - Array of agent results
+ * @returns {Object} { merged, commonElements }
+ */
+export function aggregateConsensus(results) {
+  if (results.length === 0) return { merged: {}, commonElements: [] };
+  if (results.length === 1) return { merged: results[0], commonElements: [] };
+
+  // Find common keys across all results
+  const allKeys = results.map(r => Object.keys(r));
+  const commonKeys = allKeys[0].filter(key =>
+    allKeys.every(keys => keys.includes(key))
+  );
+
+  const merged = {};
+  const commonElements = [];
+
+  for (const key of commonKeys) {
+    const values = results.map(r => r[key]);
+
+    // For strings: use longest (most complete) version
+    if (values.every(v => typeof v === 'string')) {
+      merged[key] = values.reduce((longest, v) =>
+        v.length > longest.length ? v : longest, ''
+      );
+      commonElements.push(key);
+    }
+    // For arrays: union of all arrays
+    else if (values.every(v => Array.isArray(v))) {
+      merged[key] = [...new Set(values.flat())];
+      commonElements.push(key);
+    }
+    // For objects: merge recursively (simple one level)
+    else if (values.every(v => v && typeof v === 'object')) {
+      merged[key] = Object.assign({}, ...values);
+      commonElements.push(key);
+    }
+    // For primitives: use majority value
+    else {
+      const valueCounts = values.reduce((acc, v) => {
+        const key2 = String(v);
+        acc[key2] = (acc[key2] || 0) + 1;
+        return acc;
+      }, {});
+      const [majority] = Object.entries(valueCounts).sort(([, a], [, b]) => b - a);
+      merged[key] = majority ? JSON.parse(majority[0]) : values[0];
+      commonElements.push(key);
+    }
+  }
+
+  return { merged, commonElements };
+}
+
+// ============================================================================
+// Main Fusion Runner
+// ============================================================================
+
+/**
+ * Run fusion execution: spawn N agents in parallel, collect and aggregate results
+ * @param {Object} opts
+ * @param {string} opts.feature - Feature name
+ * @param {string} opts.prompt - Prompt/mission for all agents
+ * @param {number} [opts.count=3] - Number of agents to run
+ * @param {string} [opts.strategy='best-of-n'] - Aggregation strategy
+ * @param {string[]} [opts.agents] - Agent IDs to use (will use thread types if not specified)
+ * @param {Object} [opts.rubric] - Scoring rubric for best-of-n
+ * @returns {Promise<Object>} { winner, allResults, scores, strategy, threads }
+ */
+export async function runFusion(prompt, {
+  feature,
+  count = 3,
+  strategy = 'best-of-n',
+  agents = null,
+  rubric = {}
+} = {}) {
+  const { randomUUID } = await import('crypto');
+  const sessionId = randomUUID();
+  const agentList = agents || Array.from({ length: count }, (_, i) => `fusion-agent-${i + 1}`);
+  const threads = [];
+  const results = [];
+
+  recordEvent({
+    type: 'fusion_started',
+    feature,
+    data: { count, strategy, agents: agentList }
+  });
+
+  // Create and start all fusion threads simultaneously
+  for (let i = 0; i < agentList.length; i++) {
+    const thread = createThread({
+      feature,
+      type: THREAD_TYPES.FUSION,
+      agent: agentList[i],
+      mission: prompt,
+      meta: { fusionIndex: i, strategy }
+    });
+    startThread(thread.id);
+    threads.push(thread);
+  }
+
+  console.log(`  [fusion] ${threads.length} agents spawned. Collecting results...`);
+
+  // In a real system, results would come from actual sub-agent execution.
+  // Here we return thread configs for the calling code to use with Task tool.
+  // The aggregation is designed to be called after results are collected.
+
+  return {
+    id: sessionId,
+    threads,
+    strategy,
+    feature,
+    prompt,
+    agentConfigs: agentList.map((agentId, i) => ({
+      agentId,
+      threadId: threads[i].id,
+      mission: prompt
+    })),
+    aggregate: (collectedResults) => aggregateResults(collectedResults, strategy, rubric)
+  };
+}
+
+/**
+ * Aggregate collected results from N agents
+ * @param {Array} results - Array of result objects from agents
+ * @param {string} strategy - Aggregation strategy
+ * @param {Object} [rubric] - Scoring rubric for best-of-n
+ * @returns {Object} Aggregated result
+ */
+export function aggregateResults(results, strategy = 'best-of-n', rubric = {}) {
+  if (!results || results.length === 0) {
+    throw new Error('No results to aggregate');
+  }
+
+  let aggregated;
+
+  switch (strategy) {
+    case 'best-of-n':
+      aggregated = aggregateBestOfN(results, rubric);
+      break;
+
+    case 'consensus':
+      const { merged, commonElements } = aggregateConsensus(results);
+      aggregated = {
+        winner: merged,
+        winnerId: 'consensus',
+        scores: results.map((_, i) => ({
+          agentId: `agent-${i}`,
+          score: 0,
+          rank: i + 1
+        })),
+        commonElements
+      };
+      break;
+
+    case 'manual-select':
+      aggregated = {
+        winner: null,
+        winnerId: null,
+        allResults: results,
+        requiresUserSelection: true,
+        scores: results.map((r, i) => ({
+          agentId: r.agentId || `agent-${i}`,
+          score: scoreResult(r, rubric),
+          rank: i + 1
+        }))
+      };
+      break;
+
+    default:
+      throw new Error(`Unknown aggregation strategy: ${strategy}`);
+  }
+
+  return {
+    ...aggregated,
+    strategy,
+    totalAgents: results.length,
+    allResults: results
+  };
+}
+
+/**
+ * Display fusion results summary
+ * @param {Object} fusionResult - Result from aggregateResults
+ */
+export function displayFusionSummary(fusionResult) {
+  const { strategy, totalAgents, scores, winner, requiresUserSelection } = fusionResult;
+
+  console.log(`\n  Fusion Results — ${strategy} (${totalAgents} agents)\n`);
+  console.log('  ' + '─'.repeat(50));
+
+  if (scores) {
+    const scoreData = {};
+    scores.forEach(s => { scoreData[s.agentId] = s.score; });
+    console.log(generateAsciiChart(scoreData, { title: 'Agent Scores' }));
+  }
+
+  if (requiresUserSelection) {
+    console.log('\n  Manual selection required — review results above');
+  } else if (winner) {
+    console.log(`\n  Winner: ${fusionResult.winnerId || 'consensus'}`);
+    if (fusionResult.winnerScore !== undefined) {
+      console.log(`  Score: ${fusionResult.winnerScore}/100`);
+    }
+  }
+  console.log('');
+}

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