@polymorphism-tech/morph-spec 4.8.19 → 4.9.0

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

@@ -1,345 +0,0 @@
-/**
- * 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);
-}

package/src/lib/checkpoints/checkpoint-hooks.js

@@ -1,298 +0,0 @@
-import { readFileSync, existsSync } from 'fs';
-import { join } from 'path';
-import { execSync } from 'child_process';
-import chalk from 'chalk';
-import { executeStopHooks, isMaxRetriesExceeded, incrementRetryCount } from '../hooks/stop-hook-executor.js';
-import { recordEvent } from '../analytics/analytics-engine.js';
-import { getFeature } from '../../core/state/state-manager.js';
-
-/**
- * Checkpoint Hooks - Automated validation orchestration
- *
- * Runs validators, tests, and linters at checkpoint milestones (every N tasks).
- * Blocks progress if critical validations fail.
- */
-
-/**
- * Load LLM interaction configuration
- * @returns {Object} Configuration object
- */
-function loadLLMInteractionConfig() {
-  const configPath = join(process.cwd(), '.morph/config/llm-interaction.json');
-
-  if (!existsSync(configPath)) {
-    // Return defaults if config doesn't exist
-    return {
-      checkpoints: {
-        frequency: 3,
-        autoValidate: true,
-        validators: {
-          enabled: ['architecture', 'packages', 'design-system', 'security'],
-          optional: []
-        },
-        hooks: {
-          runTests: false,
-          runLinters: true,
-          buildCheck: false
-        },
-        onFailure: {
-          blockProgress: true,
-          maxRetries: 3,
-          escalateAfter: 3
-        }
-      }
-    };
-  }
-
-  return JSON.parse(readFileSync(configPath, 'utf8'));
-}
-
-/**
- * Run a single validator
- * @param {string} validatorName - Validator to run (architecture, packages, etc.)
- * @param {string} featureName - Feature being validated
- * @returns {Promise<Object>} Validation result
- */
-async function runValidator(validatorName, featureName) {
-  try {
-    // Use existing validate command
-    const result = execSync(
-      `node bin/validate.js ${validatorName} --feature=${featureName} --json`,
-      { encoding: 'utf8', stdio: 'pipe' }
-    );
-
-    const parsed = JSON.parse(result);
-    return {
-      validator: validatorName,
-      passed: parsed.errors === 0,
-      errors: parsed.errors || 0,
-      warnings: parsed.warnings || 0,
-      details: parsed.issues || []
-    };
-  } catch (error) {
-    return {
-      validator: validatorName,
-      passed: false,
-      errors: 1,
-      warnings: 0,
-      details: [{ message: error.message, severity: 'error' }]
-    };
-  }
-}
-
-/**
- * Run tests if configured
- * @param {string} featureName - Feature being tested
- * @returns {Promise<Object>} Test result
- */
-async function runTests(featureName) {
-  try {
-    execSync('npm test --passWithNoTests', { encoding: 'utf8', stdio: 'pipe' });
-    return {
-      validator: 'tests',
-      passed: true,
-      errors: 0,
-      warnings: 0,
-      details: []
-    };
-  } catch (error) {
-    return {
-      validator: 'tests',
-      passed: false,
-      errors: 1,
-      warnings: 0,
-      details: [{ message: 'Test suite failed', severity: 'error' }]
-    };
-  }
-}
-
-/**
- * Run linters if configured
- * @param {string} featureName - Feature being linted
- * @returns {Promise<Object>} Linter result
- */
-async function runLinters(featureName) {
-  try {
-    // Check if eslint exists
-    if (existsSync(join(process.cwd(), 'node_modules/.bin/eslint'))) {
-      execSync('npm run lint --if-present', { encoding: 'utf8', stdio: 'pipe' });
-    }
-
-    return {
-      validator: 'linters',
-      passed: true,
-      errors: 0,
-      warnings: 0,
-      details: []
-    };
-  } catch (error) {
-    return {
-      validator: 'linters',
-      passed: false,
-      errors: 0,
-      warnings: 1,
-      details: [{ message: 'Linting warnings detected', severity: 'warning' }]
-    };
-  }
-}
-
-/**
- * Run checkpoint hooks - orchestrates all validation
- * @param {string} featureName - Feature name
- * @param {number} checkpointNum - Checkpoint number (1, 2, 3, etc.)
- * @returns {Promise<Object>} Checkpoint result
- */
-export async function runCheckpointHooks(featureName, checkpointNum) {
-  const config = loadLLMInteractionConfig();
-  const checkpointConfig = config.checkpoints;
-
-  if (!checkpointConfig.autoValidate) {
-    return {
-      passed: true,
-      skipped: true,
-      message: 'Auto-validation disabled in config'
-    };
-  }
-
-  console.log(`\n🔍 Running CHECKPOINT ${checkpointNum} for feature: ${featureName}`);
-  console.log('━'.repeat(60));
-
-  const results = [];
-
-  // 1. Run enabled validators
-  console.log('\n📋 Running validators...');
-  for (const validatorName of checkpointConfig.validators.enabled) {
-    process.stdout.write(`  • ${validatorName}... `);
-    const result = await runValidator(validatorName, featureName);
-    results.push(result);
-
-    if (result.passed) {
-      console.log('✅ PASSED');
-    } else {
-      console.log(`❌ FAILED (${result.errors} errors, ${result.warnings} warnings)`);
-    }
-  }
-
-  // 2. Run tests (if configured)
-  if (checkpointConfig.hooks.runTests) {
-    console.log('\n🧪 Running tests...');
-    process.stdout.write('  • test suite... ');
-    const testResult = await runTests(featureName);
-    results.push(testResult);
-
-    if (testResult.passed) {
-      console.log('✅ PASSED');
-    } else {
-      console.log('❌ FAILED');
-    }
-  }
-
-  // 3. Run linters (if configured)
-  if (checkpointConfig.hooks.runLinters) {
-    console.log('\n🎨 Running linters...');
-    process.stdout.write('  • code style... ');
-    const lintResult = await runLinters(featureName);
-    results.push(lintResult);
-
-    if (lintResult.passed) {
-      console.log('✅ PASSED');
-    } else {
-      console.log('⚠️  WARNINGS');
-    }
-  }
-
-  // Calculate overall pass/fail
-  const errorCount = results.reduce((sum, r) => sum + r.errors, 0);
-  const warningCount = results.reduce((sum, r) => sum + r.warnings, 0);
-  const passed = errorCount === 0;
-
-  console.log('\n' + '━'.repeat(60));
-  console.log(`\n📊 Checkpoint ${checkpointNum} Summary:`);
-  console.log(`   Errors: ${errorCount}`);
-  console.log(`   Warnings: ${warningCount}`);
-  console.log(`   Status: ${passed ? '✅ PASSED' : '❌ FAILED'}`);
-
-  if (!passed) {
-    console.log('\n⚠️  Checkpoint failed! Fix violations before proceeding.');
-
-    // Show details of failures
-    results.filter(r => r.errors > 0).forEach(r => {
-      console.log(`\n❌ ${r.validator} errors:`);
-      r.details.forEach(d => {
-        if (d.severity === 'error') {
-          console.log(`   - ${d.message}`);
-        }
-      });
-    });
-  }
-
-  console.log('\n' + '━'.repeat(60) + '\n');
-
-  // Run stop hooks for L-Thread support
-  let stopHookResult = null;
-  if (featureName) {
-    try {
-      // Use feature name as pseudo thread ID for stop hook feedback
-      const pseudoThreadId = `checkpoint-${featureName}-${checkpointNum}`;
-      stopHookResult = await executeStopHooks(pseudoThreadId, 'on-stop', { feature: featureName });
-
-      if (!stopHookResult.passed) {
-        // Check retry count
-        let retryCount = null;
-        if (isMaxRetriesExceeded(pseudoThreadId)) {
-          console.log(chalk.red('\n❌ Stop hooks failed 5+ times. Escalating to user.'));
-        } else {
-          retryCount = incrementRetryCount(pseudoThreadId);
-          console.log(chalk.yellow(`\n⚠ Stop hooks failed (attempt ${retryCount}/5). Feedback saved.`));
-          if (stopHookResult.feedback?.suggestions?.length > 0) {
-            stopHookResult.feedback.suggestions.forEach(s => console.log(`  → ${s}`));
-          }
-        }
-
-        // Record to analytics
-        recordEvent({
-          type: 'stop_hook_failed_at_checkpoint',
-          feature: featureName,
-          data: { checkpointNum, retryCount }
-        });
-      }
-    } catch {
-      // Stop hooks are non-critical — don't block checkpoint if they error
-    }
-  }
-
-  const phase = featureName ? (getFeature(featureName)?.phase || null) : null;
-
-  return {
-    passed,
-    checkpointNum,
-    timestamp: new Date().toISOString(),
-    phase,
-    results,
-    summary: {
-      errors: errorCount,
-      warnings: warningCount,
-      validatorsRun: results.length
-    }
-  };
-}
-
-/**
- * Check if checkpoint should run based on task count
- * @param {number} tasksCompleted - Number of tasks completed
- * @param {number} frequency - Checkpoint frequency (default: 3)
- * @returns {boolean} True if checkpoint should run
- */
-export function shouldRunCheckpoint(tasksCompleted, frequency = 3) {
-  return tasksCompleted > 0 && tasksCompleted % frequency === 0;
-}
-
-/**
- * Get checkpoint number from task count
- * @param {number} tasksCompleted - Number of tasks completed
- * @param {number} frequency - Checkpoint frequency (default: 3)
- * @returns {number} Checkpoint number
- */
-export function getCheckpointNumber(tasksCompleted, frequency = 3) {
-  return Math.floor(tasksCompleted / frequency);
-}

package/src/lib/checkpoints/index.js

@@ -1,7 +0,0 @@
-/**
- * Checkpoint System
- *
- * Automatic validation hooks triggered at checkpoints during feature implementation.
- */
-
-export * from './checkpoint-hooks.js';