@polymorphism-tech/morph-spec 4.2.0 → 4.3.0

package/src/core/state/state-manager.js

@@ -90,7 +90,7 @@ export function initState(options = {}) {
   }
 
   const initialState = {
-    version: "2.1.1",
+    version: "3.0.0",
     project: {
       name: projectName,
       type: projectType,
@@ -98,6 +98,7 @@ export function initState(options = {}) {
       updatedAt: new Date().toISOString()
     },
     features: {},
+    threads: {},
     metadata: {
       totalFeatures: 0,
       completedFeatures: 0,
@@ -201,7 +202,22 @@ async function ensureFeature(featureName, options = {}) {
         inProgress: 0,
         pending: 0
       },
-      checkpoints: []
+      checkpoints: [],
+      threadMetrics: {
+        totalThreads: 0,
+        parallelPeak: 0,
+        avgDuration: 0,
+        checkpointPassRate: 100
+      },
+      trustConfig: {
+        level: 'low',
+        history: [],
+        autoApprove: {
+          design: false,
+          tasks: false
+        }
+      },
+      contextBundles: []
     };
 
     state.metadata.totalFeatures++;

package/src/core/workflows/workflow-detector.js

@@ -27,8 +27,8 @@ function getFrameworkRoot(projectPath) {
     return npmPath;
   }
 
-  // Fallback to local development path (from src/lib/ → root)
-  return join(__dirname, '..', '..');
+  // Fallback to local development path (from src/core/workflows/ → root)
+  return join(__dirname, '..', '..', '..');
 }
 
 /**
@@ -352,3 +352,101 @@ export function listWorkflows(projectPath = '.') {
     description: w.description
   }));
 }
+
+// ============================================================================
+// Parallel, Fusion, Long-Running, Zero-Touch Detection
+// ============================================================================
+
+/**
+ * Detect if parallel execution mode should be used for a feature.
+ * Based on dependency graph analysis: if feature has independent task squads,
+ * recommend parallel mode.
+ *
+ * @param {string} feature - Feature name
+ * @param {string} [projectPath='.'] - Project path
+ * @returns {Object} { useParallel: boolean, reason: string, squads: Array }
+ */
+export async function detectParallelMode(feature, projectPath = '.') {
+  try {
+    const { getExecutionPlan } = await import('../../lib/threads/thread-coordinator.js').catch(() => {
+      // thread-coordinator may not exist yet — graceful fallback
+      return { getExecutionPlan: null };
+    });
+
+    if (!getExecutionPlan) {
+      return { useParallel: false, reason: 'thread-coordinator not available', squads: [] };
+    }
+
+    const plan = getExecutionPlan(feature);
+
+    if (!plan.valid) {
+      return { useParallel: false, reason: plan.error, squads: [] };
+    }
+
+    const parallelPhases = plan.phases.filter(p => p.canRunParallel);
+    const useParallel = parallelPhases.length > 0 && plan.stats.parallelizationRatio > 30;
+
+    return {
+      useParallel,
+      reason: useParallel
+        ? `${plan.stats.parallelizationRatio}% of tasks are parallelizable across ${parallelPhases.length} phases`
+        : 'Tasks are mostly sequential — parallel mode would not improve throughput',
+      parallelizationRatio: plan.stats.parallelizationRatio,
+      parallelPhases: parallelPhases.length,
+      squads: parallelPhases.map(p => p.tasks)
+    };
+  } catch {
+    return { useParallel: false, reason: 'Dependency analysis failed', squads: [] };
+  }
+}
+
+/**
+ * Detect if a request needs fusion workflow (uncertainty → run N agents → best-of-N)
+ * @param {string} userRequest
+ * @returns {boolean}
+ */
+export function detectFusionNeed(userRequest) {
+  const fusionKeywords = [
+    'uncertain', 'uncertainty', 'critical decision', 'compare approaches',
+    'best approach', 'prototype', 'explore options', 'which is better',
+    'not sure how', 'multiple solutions', 'benchmark'
+  ];
+  const req = userRequest.toLowerCase();
+  return fusionKeywords.some(kw => req.includes(kw));
+}
+
+/**
+ * Detect if a request needs long-running workflow (L-Thread with stop hooks)
+ * @param {string} userRequest
+ * @returns {boolean}
+ */
+export function detectLongRunningNeed(userRequest) {
+  const longRunningKeywords = [
+    'autonomous', 'large scope', 'full system', 'end to end', 'e2e',
+    'complete implementation', 'no interruption', 'long running', 'unattended'
+  ];
+  const req = userRequest.toLowerCase();
+  const fileCountMatch = req.match(/(\d+)\+?\s+files?/);
+  const fileCount = fileCountMatch ? parseInt(fileCountMatch[1]) : 0;
+  return longRunningKeywords.some(kw => req.includes(kw)) || fileCount > 10;
+}
+
+/**
+ * Check zero-touch eligibility for a feature (requires trust-manager)
+ * @param {string} feature
+ * @returns {Promise<boolean>}
+ */
+export async function checkZeroTouchEligibility(feature) {
+  try {
+    const { getTrustLevel } = await import('../../lib/trust/trust-manager.js').catch(() => ({
+      getTrustLevel: null
+    }));
+
+    if (!getTrustLevel) return false;
+
+    const level = getTrustLevel(feature);
+    return level === 'maximum';
+  } catch {
+    return false;
+  }
+}

package/src/lib/agents/micro-agent-factory.js

@@ -0,0 +1,161 @@
+/**
+ * Micro Agent Factory — Create ultra-specialized agents
+ *
+ * Micro-agents are stripped-down versions of base agents with:
+ * - Only the standards they need (1-3 files max)
+ * - A single focused mission
+ * - Minimal context overhead (~2-5K tokens vs 20-50K for full agent)
+ *
+ * Saved to: .morph/micro-agents/{name}.json
+ */
+
+import { readFileSync, writeFileSync, existsSync, mkdirSync, readdirSync } from 'fs';
+import { join } from 'path';
+
+const MICRO_AGENTS_DIR = join(process.cwd(), '.morph/micro-agents');
+const AGENTS_CONFIG = join(process.cwd(), '.morph/config/agents.json');
+
+// ============================================================================
+// Agent Creation
+// ============================================================================
+
+/**
+ * Create a micro-agent from a base agent with a standards subset
+ * @param {Object} opts
+ * @param {string} opts.name - Micro-agent name (e.g., 'jwt-validator')
+ * @param {string} opts.baseAgent - Base agent ID (e.g., 'security-expert')
+ * @param {string[]} opts.standards - Relevant standards file paths (1-3 files)
+ * @param {string} opts.mission - Focused mission description
+ * @param {string[]} [opts.tools] - Tools this micro-agent uses (default: minimal set)
+ * @param {Object} [opts.constraints] - Additional constraints
+ * @returns {Object} Micro-agent config object
+ */
+export function createMicroAgent({ name, baseAgent, standards, mission, tools = null, constraints = {} }) {
+  if (!name || !baseAgent || !mission) {
+    throw new Error('name, baseAgent, and mission are required');
+  }
+
+  if (standards && standards.length > 5) {
+    throw new Error('Micro-agents should load at most 5 standards files (ideally 1-3)');
+  }
+
+  const baseAgentConfig = loadBaseAgent(baseAgent);
+
+  const microAgent = {
+    id: name,
+    type: 'micro-agent',
+    baseAgent,
+    createdAt: new Date().toISOString(),
+    mission,
+    tier: (baseAgentConfig?.tier || 3) + 1, // micro-agents are tier+1 (more specialized)
+    domain: baseAgentConfig?.domain || 'general',
+    standards: standards || [],
+    tools: tools || ['Read', 'Write', 'Edit'],
+    constraints: {
+      maxStandards: 3,
+      maxFiles: 10,
+      focusOnly: mission,
+      ...constraints
+    },
+    contextEstimate: {
+      standards: (standards || []).length * 2000,
+      overhead: 1500,
+      total: ((standards || []).length * 2000) + 1500
+    },
+    prompt: generateMicroAgentPrompt({ name, baseAgent, standards, mission, constraints, baseAgentConfig })
+  };
+
+  return microAgent;
+}
+
+/**
+ * Save a micro-agent to disk
+ * @param {Object} microAgent - Micro-agent config (from createMicroAgent)
+ * @returns {string} Path to saved file
+ */
+export function saveMicroAgent(microAgent) {
+  if (!existsSync(MICRO_AGENTS_DIR)) {
+    mkdirSync(MICRO_AGENTS_DIR, { recursive: true });
+  }
+
+  const filePath = join(MICRO_AGENTS_DIR, `${microAgent.id}.json`);
+  writeFileSync(filePath, JSON.stringify(microAgent, null, 2), 'utf8');
+  return filePath;
+}
+
+/**
+ * List all micro-agents
+ * @returns {Array} Array of micro-agent summaries
+ */
+export function listMicroAgents() {
+  if (!existsSync(MICRO_AGENTS_DIR)) return [];
+
+  return readdirSync(MICRO_AGENTS_DIR)
+    .filter(f => f.endsWith('.json'))
+    .map(f => {
+      try {
+        const agent = JSON.parse(readFileSync(join(MICRO_AGENTS_DIR, f), 'utf8'));
+        return {
+          id: agent.id,
+          baseAgent: agent.baseAgent,
+          mission: agent.mission,
+          standards: agent.standards?.length || 0,
+          contextEstimate: agent.contextEstimate?.total || 0,
+          createdAt: agent.createdAt
+        };
+      } catch {
+        return null;
+      }
+    })
+    .filter(Boolean);
+}
+
+/**
+ * Get a specific micro-agent
+ * @param {string} name - Micro-agent name
+ * @returns {Object|null} Micro-agent config or null
+ */
+export function getMicroAgent(name) {
+  const filePath = join(MICRO_AGENTS_DIR, `${name}.json`);
+  if (!existsSync(filePath)) return null;
+  try {
+    return JSON.parse(readFileSync(filePath, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+// ============================================================================
+// Helpers
+// ============================================================================
+
+function loadBaseAgent(agentId) {
+  if (!existsSync(AGENTS_CONFIG)) return null;
+  try {
+    const config = JSON.parse(readFileSync(AGENTS_CONFIG, 'utf8'));
+    return config.agents?.find(a => a.id === agentId) || null;
+  } catch {
+    return null;
+  }
+}
+
+function generateMicroAgentPrompt({ name, baseAgent, standards, mission, constraints, baseAgentConfig }) {
+  const standardsList = standards?.map(s => `- framework/standards/${s}`).join('\n') || '(none)';
+
+  return `You are a MICRO-AGENT: ${name}
+Base: ${baseAgent} (${baseAgentConfig?.description || 'specialist'})
+
+MISSION (single focus):
+${mission}
+
+STANDARDS TO LOAD (${standards?.length || 0} files):
+${standardsList}
+
+CONSTRAINTS:
+- Focus ONLY on your mission above
+- Do NOT load additional standards or context
+- Maximum ${constraints.maxFiles || 10} files to read/write
+- Report completion when done — do NOT start new tasks
+
+This is a minimal-context agent. Stay focused.`;
+}

package/src/lib/analytics/analytics-engine.js

@@ -0,0 +1,345 @@
+/**
+ * Analytics Engine — Metrics collection and JSONL storage
+ *
+ * Records events to append-only JSONL files:
+ * - .morph/analytics/threads-log.jsonl
+ * - .morph/analytics/context-log.jsonl
+ * - .morph/analytics/trust-log.jsonl
+ *
+ * Provides aggregation, ASCII chart generation, and 30-day dashboards.
+ * Auto-prunes entries older than 90 days.
+ */
+
+import { readFileSync, writeFileSync, appendFileSync, existsSync, mkdirSync } from 'fs';
+import { join } from 'path';
+
+const ANALYTICS_DIR = join(process.cwd(), '.morph/analytics');
+const THREADS_LOG = join(ANALYTICS_DIR, 'threads-log.jsonl');
+const CONTEXT_LOG = join(ANALYTICS_DIR, 'context-log.jsonl');
+const TRUST_LOG = join(ANALYTICS_DIR, 'trust-log.jsonl');
+const PRUNE_DAYS = 90;
+const DASHBOARD_DAYS = 30;
+
+// ============================================================================
+// Internal Helpers
+// ============================================================================
+
+function ensureAnalyticsDir() {
+  if (!existsSync(ANALYTICS_DIR)) {
+    mkdirSync(ANALYTICS_DIR, { recursive: true });
+  }
+}
+
+function appendJSONL(filePath, record) {
+  ensureAnalyticsDir();
+  appendFileSync(filePath, JSON.stringify(record) + '\n', 'utf8');
+}
+
+function readJSONL(filePath) {
+  if (!existsSync(filePath)) return [];
+
+  const lines = readFileSync(filePath, 'utf8').trim().split('\n').filter(Boolean);
+  const records = [];
+
+  for (const line of lines) {
+    try {
+      records.push(JSON.parse(line));
+    } catch {
+      // Skip malformed lines
+    }
+  }
+  return records;
+}
+
+function pruneJSONL(filePath) {
+  if (!existsSync(filePath)) return;
+
+  const cutoff = new Date();
+  cutoff.setDate(cutoff.getDate() - PRUNE_DAYS);
+
+  const records = readJSONL(filePath);
+  const fresh = records.filter(r => {
+    const ts = new Date(r.timestamp || r.createdAt || 0);
+    return ts > cutoff;
+  });
+
+  if (fresh.length < records.length) {
+    writeFileSync(filePath, fresh.map(r => JSON.stringify(r)).join('\n') + '\n', 'utf8');
+  }
+}
+
+function recentRecords(records, days = DASHBOARD_DAYS) {
+  const cutoff = new Date();
+  cutoff.setDate(cutoff.getDate() - days);
+  return records.filter(r => {
+    const ts = new Date(r.timestamp || r.createdAt || 0);
+    return ts > cutoff;
+  });
+}
+
+// ============================================================================
+// Event Recording
+// ============================================================================
+
+/**
+ * Record a thread analytics event
+ * @param {Object} event
+ * @param {string} event.type - Event type (thread_created|thread_completed|thread_failed|checkpoint_passed|etc.)
+ * @param {string} event.feature - Feature name
+ * @param {string} [event.threadId] - Thread ID
+ * @param {string} [event.agent] - Agent name
+ * @param {Object} [event.data] - Additional event data
+ */
+export function recordEvent(event) {
+  const record = {
+    ...event,
+    timestamp: new Date().toISOString()
+  };
+
+  // Route to appropriate log
+  if (event.type?.startsWith('context_') || event.type === 'token_usage') {
+    appendJSONL(CONTEXT_LOG, record);
+  } else if (event.type?.startsWith('trust_')) {
+    appendJSONL(TRUST_LOG, record);
+  } else {
+    appendJSONL(THREADS_LOG, record);
+  }
+}
+
+/**
+ * Record a context event (token usage, optimization, etc.)
+ * @param {Object} event
+ */
+export function recordContextEvent(event) {
+  recordEvent({ ...event, type: event.type || 'context_usage' });
+}
+
+/**
+ * Record a trust level change event
+ * @param {string} feature
+ * @param {string} level - new trust level
+ * @param {string} reason
+ */
+export function recordTrustEvent(feature, level, reason = '') {
+  appendJSONL(TRUST_LOG, {
+    timestamp: new Date().toISOString(),
+    type: 'trust_level_changed',
+    feature,
+    level,
+    reason
+  });
+}
+
+/**
+ * Record auto-approval event (gate approved by trust)
+ * @param {string} feature
+ * @param {string} gate - 'design' | 'tasks' | 'proposal'
+ * @param {string} trustLevel
+ * @param {number} passRate
+ */
+export function recordAutoApproval(feature, gate, trustLevel, passRate) {
+  appendJSONL(TRUST_LOG, {
+    timestamp: new Date().toISOString(),
+    type: 'trust_auto_approved',
+    feature,
+    gate,
+    trustLevel,
+    passRate,
+    timeSavedMinutes: 5 // estimated minutes saved per auto-approval
+  });
+}
+
+/**
+ * Get trust progression for a feature
+ * @param {string} featureName
+ * @returns {Array} Trust level history
+ */
+export function getTrustProgression(featureName) {
+  const events = readJSONL(TRUST_LOG)
+    .filter(e => e.feature === featureName && e.type === 'trust_level_changed')
+    .sort((a, b) => new Date(a.timestamp) - new Date(b.timestamp));
+  return events;
+}
+
+// ============================================================================
+// Feature Analytics
+// ============================================================================
+
+/**
+ * Get analytics for a specific feature
+ * @param {string} feature - Feature name
+ * @returns {Object} Feature analytics
+ */
+export function getFeatureAnalytics(feature) {
+  const allThreadEvents = readJSONL(THREADS_LOG).filter(r => r.feature === feature);
+  const allContextEvents = readJSONL(CONTEXT_LOG).filter(r => r.feature === feature);
+
+  const threadsByStatus = allThreadEvents
+    .filter(e => e.type === 'thread_completed' || e.type === 'thread_failed')
+    .reduce((acc, e) => {
+      const status = e.type === 'thread_completed' ? 'completed' : 'failed';
+      acc[status] = (acc[status] || 0) + 1;
+      return acc;
+    }, {});
+
+  const checkpoints = allThreadEvents.filter(e =>
+    e.type === 'checkpoint_passed' || e.type === 'checkpoint_failed'
+  );
+  const checkpointPassRate = checkpoints.length > 0
+    ? Math.round(checkpoints.filter(e => e.type === 'checkpoint_passed').length / checkpoints.length * 100)
+    : 100;
+
+  const totalDuration = allThreadEvents
+    .filter(e => e.type === 'thread_completed' && e.data?.duration)
+    .reduce((sum, e) => sum + e.data.duration, 0);
+
+  const toolCallEvents = allThreadEvents.filter(e => e.type === 'tool_call');
+  const tokenEvents = allContextEvents.filter(e => e.data?.tokensUsed);
+  const totalTokens = tokenEvents.reduce((sum, e) => sum + (e.data.tokensUsed || 0), 0);
+
+  return {
+    feature,
+    threads: threadsByStatus,
+    checkpointPassRate,
+    totalDuration,
+    totalToolCalls: toolCallEvents.length,
+    totalTokensUsed: totalTokens,
+    optimizationEvents: allContextEvents.filter(e => e.type === 'context_optimized').length
+  };
+}
+
+/**
+ * Get project-wide analytics dashboard (30-day summary)
+ * @returns {Object} Project analytics
+ */
+export function getProjectAnalytics() {
+  const allThreadEvents = recentRecords(readJSONL(THREADS_LOG));
+  const allContextEvents = recentRecords(readJSONL(CONTEXT_LOG));
+  const allTrustEvents = recentRecords(readJSONL(TRUST_LOG));
+
+  const features = [...new Set(allThreadEvents.map(e => e.feature).filter(Boolean))];
+
+  const completedThreads = allThreadEvents.filter(e => e.type === 'thread_completed');
+  const failedThreads = allThreadEvents.filter(e => e.type === 'thread_failed');
+  const checkpoints = allThreadEvents.filter(e =>
+    e.type === 'checkpoint_passed' || e.type === 'checkpoint_failed'
+  );
+
+  const parallelEvents = allThreadEvents.filter(e => e.data?.type === 'parallel');
+  const avgParallel = parallelEvents.length > 0
+    ? parallelEvents.reduce((sum, e) => sum + (e.data?.concurrency || 1), 0) / parallelEvents.length
+    : 1;
+
+  const autoApprovalEvents = allTrustEvents.filter(e => e.type === 'trust_auto_approved');
+  const avgTokens = allContextEvents.filter(e => e.data?.tokensUsed).length > 0
+    ? Math.round(allContextEvents.reduce((sum, e) => sum + (e.data?.tokensUsed || 0), 0) / allContextEvents.filter(e => e.data?.tokensUsed).length)
+    : 0;
+
+  return {
+    period: `${DASHBOARD_DAYS} days`,
+    features: features.length,
+    threads: {
+      total: completedThreads.length + failedThreads.length,
+      completed: completedThreads.length,
+      failed: failedThreads.length
+    },
+    checkpoints: {
+      total: checkpoints.length,
+      passed: checkpoints.filter(e => e.type === 'checkpoint_passed').length,
+      passRate: checkpoints.length > 0
+        ? Math.round(checkpoints.filter(e => e.type === 'checkpoint_passed').length / checkpoints.length * 100)
+        : 100
+    },
+    parallelization: {
+      avgConcurrency: Math.round(avgParallel * 10) / 10,
+      parallelThreads: parallelEvents.length
+    },
+    trust: {
+      autoApprovals: autoApprovalEvents.length,
+      trustChanges: allTrustEvents.filter(e => e.type === 'trust_level_changed').length
+    },
+    context: {
+      avgTokensPerSession: avgTokens,
+      optimizations: allContextEvents.filter(e => e.type === 'context_optimized').length
+    }
+  };
+}
+
+// ============================================================================
+// ASCII Charts
+// ============================================================================
+
+/**
+ * Generate an ASCII bar chart
+ * @param {Object} data - { label: value }
+ * @param {Object} [opts]
+ * @param {number} [opts.width=40] - Chart width in chars
+ * @param {string} [opts.title] - Chart title
+ * @returns {string} ASCII chart string
+ */
+export function generateAsciiChart(data, { width = 40, title = '' } = {}) {
+  const entries = Object.entries(data);
+  if (entries.length === 0) return '  (no data)';
+
+  const maxValue = Math.max(...entries.map(([, v]) => v), 1);
+  const maxLabelLen = Math.max(...entries.map(([k]) => k.length));
+  const lines = [];
+
+  if (title) {
+    lines.push(`  ${title}`);
+    lines.push('  ' + '─'.repeat(width + maxLabelLen + 5));
+  }
+
+  for (const [label, value] of entries) {
+    const barLen = Math.round((value / maxValue) * width);
+    const bar = '█'.repeat(barLen);
+    const paddedLabel = label.padStart(maxLabelLen);
+    lines.push(`  ${paddedLabel} │${bar} ${value}`);
+  }
+
+  return lines.join('\n');
+}
+
+/**
+ * Generate thread timeline ASCII chart
+ * @param {Array} events - Array of thread events with timestamps
+ * @param {string} label - Chart label
+ * @returns {string} ASCII timeline
+ */
+export function generateTimelineChart(events, label = 'Timeline') {
+  if (events.length === 0) return '  (no data)';
+
+  const now = new Date();
+  const days = Array.from({ length: 7 }, (_, i) => {
+    const d = new Date(now);
+    d.setDate(d.getDate() - (6 - i));
+    return d.toLocaleDateString('en-US', { weekday: 'short' });
+  });
+
+  const counts = new Array(7).fill(0);
+  for (const event of events) {
+    const ts = new Date(event.timestamp);
+    const daysAgo = Math.floor((now - ts) / (1000 * 60 * 60 * 24));
+    if (daysAgo < 7) {
+      counts[6 - daysAgo]++;
+    }
+  }
+
+  const data = {};
+  days.forEach((d, i) => { data[d] = counts[i]; });
+
+  return generateAsciiChart(data, { title: label });
+}
+
+// ============================================================================
+// Maintenance
+// ============================================================================
+
+/**
+ * Prune all analytics logs (remove entries older than 90 days)
+ */
+export function pruneAnalytics() {
+  pruneJSONL(THREADS_LOG);
+  pruneJSONL(CONTEXT_LOG);
+  pruneJSONL(TRUST_LOG);
+}