mindforge-cc 5.6.0 → 5.10.0

package/bin/engine/feedback-loop.js

@@ -2,11 +2,14 @@
  * MindForge — WaveFeedbackLoop (Pillar VI: Proactive Equilibrium)
  * Monitors divergence during wave execution and triggers self-healing.
  */
+const fs = require('fs');
+const path = require('path');
 
 class WaveFeedbackLoop {
   constructor(config = {}) {
     this.failureThreshold = config.failureThreshold || 0.20; // 20% failure rate
     this.divergenceWeight = config.divergenceWeight || 1.5; // Bias for rapid divergence
+    this.statsPath = config.statsPath || path.join(__dirname, '..', 'models', 'performance-stats.json');
     this.waveState = {
       completed: 0,
       failed: 0,
@@ -16,19 +19,51 @@ class WaveFeedbackLoop {
   }
 
   /**
-   * Updates the feedback loop with a task result.
+   * Updates the feedback loop with a task result and records performance stats.
    */
   update(result) {
     this.waveState.total++;
+    const provider = result.providerId || 'unknown';
+    const taskType = result.taskType || 'default';
+
     if (result.status === 'completed') {
       this.waveState.completed++;
+      this.recordPerformance(provider, taskType, true);
     } else if (result.status === 'failed') {
       this.waveState.failed++;
+      this.recordPerformance(provider, taskType, false);
     } else {
       this.waveState.skipped++;
     }
   }
 
+  /**
+   * Records performance metrics to persistent storage.
+   */
+  recordPerformance(provider, taskType, isSuccess) {
+    if (provider === 'unknown') return;
+
+    try {
+      let stats = {};
+      if (fs.existsSync(this.statsPath)) {
+        stats = JSON.parse(fs.readFileSync(this.statsPath, 'utf8'));
+      }
+
+      if (!stats[provider]) stats[provider] = {};
+      if (!stats[provider][taskType]) stats[provider][taskType] = { success: 0, failure: 0 };
+
+      if (isSuccess) {
+        stats[provider][taskType].success++;
+      } else {
+        stats[provider][taskType].failure++;
+      }
+
+      fs.writeFileSync(this.statsPath, JSON.stringify(stats, null, 2));
+    } catch (e) {
+      console.warn(`[MCA-WARN] Failed to record performance stats: ${e.message}`);
+    }
+  }
+
   /**
    * Calculates the current divergence rate.
    * @returns {number} - 0.0 to 1.0 divergence rate.

package/bin/engine/nexus-tracer.js

@@ -45,7 +45,7 @@ class NexusTracer {
   /**
    * Start a new ART span.
    */
-  startSpan(name, attributes = {}, parentSpanId = null) {
+  async startSpan(name, attributes = {}, parentSpanId = null) {
     const spanId = `sp_${crypto.randomBytes(6).toString('hex')}`;
     const startTime = new Date().toISOString();
 
@@ -59,6 +59,8 @@ class NexusTracer {
       attributes: {
         ...attributes,
         service: 'mindforge-nexus',
+        host: require('os').hostname(),
+        pid: process.pid
       }
     };
 
@@ -81,7 +83,7 @@ class NexusTracer {
     }
 
     // Record span start in AUDIT.jsonl
-    this._recordEvent('span_started', { 
+    await this._recordEvent('span_started', { 
       span_id: spanId, 
       parent_span_id: parentSpanId,
       span_name: name,
@@ -95,7 +97,7 @@ class NexusTracer {
   /**
    * End an active span.
    */
-  endSpan(spanId, status = 'success', metadata = {}) {
+  async endSpan(spanId, status = 'success', metadata = {}) {
     const span = this.activeSpans.get(spanId);
     if (!span) return;
 
@@ -107,7 +109,7 @@ class NexusTracer {
       this.sreManager.terminateEnclave(span.attributes.enclave_id);
     }
 
-    this._recordEvent('span_completed', {
+    await this._recordEvent('span_completed', {
       span_id: spanId,
       status,
       ...metadata
@@ -119,19 +121,31 @@ class NexusTracer {
   /**
    * Record a Reasoning Trace event (ART granularity).
    */
-  recordReasoning(spanId, agent, thought, resolution = 'none') {
+  async recordReasoning(spanId, agent, thought, resolution = 'none') {
     const span = this.activeSpans.get(spanId);
     let sanitizedThought = thought;
 
     if (span && span.attributes.enclave_id) {
-      sanitizedThought = this.sreManager.sanitizeThoughtChain(thought, span.attributes.enclave_id);
+      const result = this.sreManager.sanitizeThoughtChain(thought, span.attributes.enclave_id);
+      
+      if (result.status === 'SRE-ISOLATED') {
+        // Log the ZK proof instead of the raw thought
+        await this._recordEvent('sre_proof_logged', {
+          span_id: spanId,
+          agent,
+          certificate: result,
+          resolution
+        });
+        return; // Skip standard reasoning trace for isolated content
+      }
+      sanitizedThought = result.content || thought;
     }
 
     // v5 Pillar III: PES (Proactive Equilibrium Scoring)
     const entropy = this.calculateEntropy(spanId, sanitizedThought);
     const isStagnant = entropy > this.RES_THRESHOLD;
 
-    this._recordEvent('reasoning_trace', {
+    await this._recordEvent('reasoning_trace', {
       span_id: spanId,
       agent,
       thought: sanitizedThought,
@@ -145,7 +159,7 @@ class NexusTracer {
       const stagnationCount = history.filter(h => h.entropy > this.RES_THRESHOLD).length;
 
       if (stagnationCount >= 3) {
-        this._recordEvent('vulnerability_detected', {
+        await this._recordEvent('vulnerability_detected', {
           span_id: spanId,
           type: 'REASONING_LOOP',
           severity: 'HIGH',
@@ -154,7 +168,7 @@ class NexusTracer {
         });
         
         // Signal proactive recovery
-        this.recordSelfHeal(spanId, {
+        await this.recordSelfHeal(spanId, {
           type: 'PROACTIVE_RCA',
           cause: 'REASONING_STAGNATION',
           suggestion: 'Entropy threshold exceeded. Switch reasoning strategy.'
@@ -200,7 +214,7 @@ class NexusTracer {
   /**
    * Internal AUDIT writer.
    */
-  _recordEvent(event, data) {
+  async _recordEvent(event, data) {
     const entry = {
       id: crypto.randomUUID(),
       timestamp: new Date().toISOString(),
@@ -215,7 +229,7 @@ class NexusTracer {
         entry.did = this.did;
         // Sign the stringified entry WITHOUT the signature field itself
         const payload = JSON.stringify(entry);
-        entry.signature = ztai.signData(this.did, payload);
+        entry.signature = await ztai.signData(this.did, payload);
       } catch (err) {
         console.warn(`[NexusTracer] ZTAI signing failed: ${err.message}`);
       }
@@ -234,8 +248,8 @@ class NexusTracer {
   /**
    * Records a FinOps budget decision (Pillar V).
    */
-  recordFinOps(spanId, decision) {
-    this._recordEvent('finops_decision', {
+  async recordFinOps(spanId, decision) {
+    await this._recordEvent('finops_decision', {
       span_id: spanId,
       ...decision
     });
@@ -244,8 +258,8 @@ class NexusTracer {
   /**
    * Records a Self-Healing trigger event (Pillar VI).
    */
-  recordSelfHeal(spanId, report) {
-    this._recordEvent('self_heal_trigger', {
+  async recordSelfHeal(spanId, report) {
+    await this._recordEvent('self_heal_trigger', {
       span_id: spanId,
       ...report
     });
@@ -254,7 +268,7 @@ class NexusTracer {
   /**
    * Finalize and export the Agentic SBOM (Pillar IV).
    */
-  exportSBOM(outputPath = null) {
+  async exportSBOM(outputPath = null) {
     const finalPath = outputPath || path.join(process.cwd(), '.planning', 'MANIFEST.sbom.json');
     const manifest = {
       ...this.sbom,
@@ -269,7 +283,7 @@ class NexusTracer {
       }
       fs.writeFileSync(finalPath, JSON.stringify(manifest, null, 2));
       
-      this._recordEvent('sbom_exported', { path: finalPath });
+      await this._recordEvent('sbom_exported', { path: finalPath });
       return finalPath;
     } catch (err) {
       console.error(`[NexusTracer] Failed to export SBOM: ${err.message}`);
@@ -278,4 +292,9 @@ class NexusTracer {
   }
 }
 
-module.exports = NexusTracer;
+// Global Singleton Instance for easy mesh-wide access
+const globalTracer = new NexusTracer();
+
+// Export both the class and the global instance
+module.exports = globalTracer;
+module.exports.NexusTracer = NexusTracer;

package/bin/engine/sre-manager.js

@@ -6,6 +6,10 @@
 
 const crypto = require('crypto');
 
+// Simulated System DID for Enclave Proofs (Tier 3)
+const ENCLAVE_PRIVATE_KEY = 'tier3-enclave-secret-key-sim'; // In production, this would be a TEE-bound private key
+const SYSTEM_DID = 'did:mindforge:enclave:0xbeast';
+
 class SREManager {
   constructor() {
     this.activeEnclaves = new Map();
@@ -26,7 +30,8 @@ class SREManager {
       startedAt: new Date().toISOString(),
       principal: context.did,
       hasIP: true,
-      isolationLevel: 'Hardware-Enclave (Simulated)'
+      isolationLevel: 'Hardware-Enclave (Simulated)',
+      cumulativeHash: null // Root of the proof chain
     });
 
     console.log(`[SRE-INIT] Initialized Sovereign Reason Enclave: ${enclaveId} for ${context.did}`);
@@ -34,19 +39,68 @@ class SREManager {
   }
 
   /**
-   * Sanitizes a thought chain for global audit logging.
-   * Ensures that sensitive IP or "zero-visibility" thoughts are isolated.
+   * Sanitizes a thought chain and generates a ZK-Proof Compliance Certificate.
+   * Ensures that sensitive IP or "zero-visibility" thoughts are isolated while proving audit-eligibility.
    * @param {string} thoughtChain - The raw agentic thought chain.
-   * @returns {string} - Sanitized/Isolated thought chain.
+   * @param {string} enclaveId - The active enclave ID.
+   * @param {Object} policyResult - Whether the content passed internal policy checks.
+   * @returns {Object} - ZK-Proof compliance certificate.
    */
-  sanitizeThoughtChain(thoughtChain, enclaveId) {
-    if (!this.activeEnclaves.has(enclaveId)) return thoughtChain;
+  sanitizeThoughtChain(thoughtChain, enclaveId, policyResult = { passed: true }) {
+    if (!this.activeEnclaves.has(enclaveId)) {
+      return { status: 'PLAINTEXT', content: thoughtChain };
+    }
 
-    // Zero-Visibility Protocol: In SRE mode, the global audit log only receives a hash
-    // or a redacted summary. The full chain is kept in volatile enclave memory.
+    // v5 Pillar VI: Merkle-style Cumulative Hash Chain
+    const enclaveData = this.activeEnclaves.get(enclaveId);
+    const prevHash = enclaveData.cumulativeHash;
     const digest = crypto.createHash('sha256').update(thoughtChain).digest('hex');
     
-    return `[SRE-ISOLATED] Confidential reasoning executed in enclave ${enclaveId}. Verification Digest: ${digest}. Original trace is isolated from persistence.`;
+    // Generate a simulated ZK-Proof Compliance Certificate
+    const proofPayload = {
+      enclaveId: enclaveId,
+      digest: digest,
+      prevHash: prevHash, // Links the chain
+      policyPassed: policyResult.passed,
+      timestamp: new Date().toISOString(),
+      principal: enclaveData.principal
+    };
+
+    // Sign the proof with the Enclave Private Key
+    const signature = crypto.createHmac('sha256', ENCLAVE_PRIVATE_KEY)
+      .update(JSON.stringify(proofPayload))
+      .digest('hex');
+
+    // Update the cumulative hash for the next block
+    const proofHash = crypto.createHash('sha256').update(signature).digest('hex');
+    enclaveData.cumulativeHash = proofHash;
+
+    const certificate = {
+      status: 'SRE-ISOLATED',
+      proof: proofPayload,
+      signature: signature,
+      proofHash: proofHash,
+      verificationDid: SYSTEM_DID,
+      message: `[SRE-ZK-PROOF] Confidential reasoning (sha256:${digest.substring(0, 8)}...) verified by Enclave Auditor.`
+    };
+
+    return certificate;
+  }
+
+  /**
+   * Verifies an SRE Compliance Certificate without seeing the original content.
+   */
+  verifyZKProof(certificate) {
+    if (certificate.status !== 'SRE-ISOLATED') return false;
+
+    const expectedSignature = crypto.createHmac('sha256', ENCLAVE_PRIVATE_KEY)
+      .update(JSON.stringify(certificate.proof))
+      .digest('hex');
+
+    const isValid = (expectedSignature === certificate.signature);
+    const policyPassed = certificate.proof.policyPassed;
+
+    return isValid && policyPassed;
   }
 
   /**

package/bin/models/cloud-broker.js

@@ -3,33 +3,97 @@
  * Dynamically routes tasks across multiple cloud providers (Vertex, Bedrock, Azure).
  */
 'use strict';
+ 
+const fs = require('fs');
+const path = require('path');
 
 class CloudBroker {
   constructor(config = {}) {
     this.providers = config.providers || ['anthropic', 'google', 'aws', 'azure'];
+    this.statsPath = config.statsPath || path.join(__dirname, 'performance-stats.json');
+    this.blacklist = new Map(); // provider -> expiry (Date)
+    this.failureWindow = new Map(); // provider:taskType -> count
     this.state = {
       'anthropic': { latency: 450, costMultiplier: 1.0, healthy: true },
       'google': { latency: 600, costMultiplier: 0.85, healthy: true },
       'aws': { latency: 550, costMultiplier: 0.95, healthy: true },
       'azure': { latency: 650, costMultiplier: 1.1, healthy: true }
     };
+    this.reloadStats();
   }
 
   /**
-   * Selects the optimal provider based on weighted latency and cost.
-   * @param {Object} options - Task requirements (maxLatency, budgetConstraint)
+   * Loads performance stats from persistent storage and applies decay (0.95 factor).
+   */
+  reloadStats() {
+    try {
+      if (fs.existsSync(this.statsPath)) {
+        const raw = JSON.parse(fs.readFileSync(this.statsPath, 'utf8'));
+        
+        // v5 Pillar V: Metrics Decay (Hyper-Enterprise Hardening)
+        // Ensure historical data doesn't anchor the model if recent performance shifts.
+        this.performanceStats = {};
+        for (const [provider, tasks] of Object.entries(raw)) {
+          this.performanceStats[provider] = {};
+          for (const [task, stats] of Object.entries(tasks)) {
+            this.performanceStats[provider][task] = {
+              success: stats.success * 0.95,
+              failure: stats.failure * 0.95
+            };
+          }
+        }
+      } else {
+        this.performanceStats = {};
+      }
+    } catch (e) {
+      console.warn(`[MCA-WARN] Failed to load performance stats: ${e.message}`);
+      this.performanceStats = {};
+    }
+  }
+
+  /**
+   * Selects the optimal provider based on weighted latency, cost, and historical success.
+   * @param {Object} requirements - Task requirements (maxLatency, budgetConstraint, taskType)
    * @returns {string} - Best provider ID
    */
   getBestProvider(requirements = {}) {
+    this.reloadStats(); // Just-In-Time refresh for latest feedback loop data
+    const taskType = requirements.taskType || 'default';
+
     const scored = Object.entries(this.state)
-      .filter(([_, data]) => data.healthy)
+      .filter(([id, data]) => {
+        // v5 Pillar V: Circuit Breaker Verification
+        if (!data.healthy) return false;
+        const blacklistExpiry = this.blacklist.get(id);
+        if (blacklistExpiry && blacklistExpiry > new Date()) {
+          return false; // Circuit is OPEN (Blacklisted)
+        }
+        return true;
+      })
       .map(([id, data]) => {
-        // Score = (Latency * 0.4) + (Cost * 0.6) — Lower is better
-        const score = (data.latency * 0.4) + (data.costMultiplier * 1000 * 0.6);
-        return { id, score };
+        // Calculate Success Probability for this task
+        const stats = this.performanceStats[id]?.[taskType] || { success: 1, failure: 0 };
+        const totalTasks = stats.success + stats.failure;
+        const successProb = totalTasks > 0 ? (stats.success / totalTasks) : 0.5;
+
+        // Score Calculation (The "Affinity" Algorithm)
+        const latencyWeight = 0.2;
+        const costWeight = 0.3;
+        const affinityWeight = 0.5; 
+
+        const score = (data.latency * latencyWeight) + 
+                      (data.costMultiplier * 1000 * costWeight) + 
+                      ((1.0 - successProb) * 2000 * affinityWeight);
+
+        return { id, score, successProb: successProb.toFixed(2) };
       });
 
     scored.sort((a, b) => a.score - b.score);
+    
+    if (scored.length > 0) {
+      console.log(`[MCA-ROUTE] Selected provider: ${scored[0].id} (Affinity: ${scored[0].successProb} for '${taskType}')`);
+    }
+
     return scored[0]?.id || 'anthropic';
   }
 
@@ -53,20 +117,34 @@ class CloudBroker {
 
   /**
    * Retrieves provider-specific model mapping.
-   * @param {string} provider - Provider ID
-   * @param {string} modelGroup - e.g., 'sonnet', 'opus', 'haiku'
    */
   mapToProviderModel(provider, modelGroup) {
     const mappings = {
       'anthropic': { 'sonnet': 'claude-3-5-sonnet', 'opus': 'claude-3-opus', 'haiku': 'claude-3-haiku' },
-      'google': { 'sonnet': 'gemini-1.5-pro', 'opus': 'gemini-1.5-pro', 'haiku': 'gemini-1.5-flash' },
-      'aws': { 'sonnet': 'anthropic.claude-3-5-sonnet-v2:0', 'opus': 'anthropic.claude-3-opus-v1:0', 'haiku': 'anthropic.claude-3-haiku-v1:0' },
-      'azure': { 'sonnet': 'gpt-4o', 'opus': 'gpt-4-turbo', 'haiku': 'gpt-35-turbo' }
+      'google': { 'sonnet': 'gemini-1.5-pro', 'haiku': 'gemini-1.5-flash' },
+      'aws': { 'sonnet': 'anthropic.claude-3-5-sonnet-v2:0', 'haiku': 'anthropic.claude-3-haiku-v1:0' },
+      'azure': { 'sonnet': 'gpt-4o', 'haiku': 'gpt-35-turbo' }
     };
 
     return mappings[provider]?.[modelGroup] || mappings[provider]?.['sonnet'];
   }
 
+  /**
+   * Records a task failure and manages the circuit breaker.
+   */
+  recordFailure(provider, taskType = 'default') {
+    const key = `${provider}:${taskType}`;
+    const failures = (this.failureWindow.get(key) || 0) + 1;
+    this.failureWindow.set(key, failures);
+
+    if (failures >= 3) {
+      const expiry = new Date(Date.now() + 10 * 60 * 1000); // 10 min blacklist
+      this.blacklist.set(provider, expiry);
+      console.warn(`[MCA-CIRCUIT-OPEN] Provider '${provider}' blacklisted for 10 min due to consecutive failures on '${taskType}'.`);
+      this.failureWindow.set(key, 0); // Reset window upon blacklisting
+    }
+  }
+
   /**
    * Hardening: Simulate provider failures to verify Fallback Protocol.
    */

package/bin/models/performance-stats.json

@@ -0,0 +1,22 @@
+{
+  "anthropic": {
+    "refactor": { "success": 45, "failure": 2 },
+    "test": { "success": 30, "failure": 1 },
+    "architect": { "success": 12, "failure": 0 }
+  },
+  "google": {
+    "refactor": { "success": 25, "failure": 8 },
+    "test": { "success": 50, "failure": 2 },
+    "architect": { "success": 8, "failure": 4 }
+  },
+  "aws": {
+    "refactor": { "success": 20, "failure": 5 },
+    "test": { "success": 15, "failure": 5 },
+    "architect": { "success": 5, "failure": 2 }
+  },
+  "azure": {
+    "refactor": { "success": 10, "failure": 10 },
+    "test": { "success": 20, "failure": 5 },
+    "architect": { "success": 3, "failure": 5 }
+  }
+}

package/bin/revops/debt-monitor.js

@@ -0,0 +1,60 @@
+/**
+ * MindForge v5.10.0 — AgRevOps Governance Debt Monitor
+ * Calculates Security Health Score and Governance Debt.
+ */
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+class DebtMonitor {
+  constructor() {
+    this.auditPath = path.join(process.cwd(), '.planning', 'AUDIT.jsonl');
+  }
+
+  /**
+   * Monitor governance debt and security health.
+   * @param {Object} metrics - From MetricsAggregator
+   */
+  monitor(metrics) {
+    const auditEntries = metrics.auditEntries || [];
+    
+    // 1. Identify high-risk events
+    const criticalFindings = auditEntries.filter(e => e.event === 'security_finding' && e.severity === 'critical');
+    const tier3Approvals  = auditEntries.filter(e => e.event === 'approval_granted' && e.tier === 3);
+    const policyBypasses   = auditEntries.filter(e => e.event === 'policy_bypass');
+
+    // 2. Calculate Health Score (starts at 100)
+    let score = 100;
+    score -= (criticalFindings.length * 10);
+    score -= (tier3Approvals.length * 5);
+    score -= (policyBypasses.length * 15);
+
+    const healthScore = Math.max(0, score);
+
+    // 3. Determine status
+    let status = 'Excellent';
+    if (healthScore < 90) status = 'Good';
+    if (healthScore < 75) status = 'Warning';
+    if (healthScore < 50) status = 'Critical';
+
+    return {
+      security_health_score: healthScore,
+      governance_status: status,
+      critical_findings: criticalFindings.length,
+      tier3_approvals: tier3Approvals.length,
+      policy_bypasses: policyBypasses.length,
+      debt_level: this.getDebtLevel(healthScore),
+      timestamp: new Date().toISOString()
+    };
+  }
+
+  getDebtLevel(score) {
+      if (score >= 95) return 'Minimal';
+      if (score >= 80) return 'Managing';
+      if (score >= 60) return 'Moderate';
+      return 'High';
+  }
+}
+
+module.exports = new DebtMonitor();

package/bin/revops/roi-engine.js

@@ -0,0 +1,60 @@
+/**
+ * MindForge v5.10.0 — AgRevOps ROI Engine
+ * Calculates $ Value Saved vs $ Token Cost.
+ */
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+class ROIEngine {
+  constructor() {
+    this.hourlyRate = 100; // Average Enterprise Dev Hourly Rate (USD)
+    this.taskValues = {
+      'refactor': 1.5, // 1.5 hours saved
+      'test': 0.75,   // 0.75 hours saved
+      'architect': 4.0, // 4 hours saved
+      'default': 0.5   // 0.5 hours saved
+    };
+  }
+
+  /**
+   * Calculate ROI from current session metrics.
+   * @param {Object} metrics - From MetricsAggregator
+   */
+  calculate(metrics) {
+    const tokenCost = metrics.costs?.reduce((sum, c) => sum + (c.cost || 0), 0) || 0;
+    
+    // map successful tasks to dev hours
+    const tasks = metrics.auditEntries?.filter(e => e.event === 'task_completed') || [];
+    let hoursSaved = 0;
+
+    tasks.forEach(t => {
+      const type = this.detectTaskType(t.message || t.task || '');
+      hoursSaved += this.taskValues[type] || this.taskValues.default;
+    });
+
+    const grossValue = hoursSaved * this.hourlyRate;
+    const netValue   = grossValue - tokenCost;
+    const roi        = tokenCost > 0 ? (netValue / tokenCost) * 100 : 0;
+
+    return {
+      token_cost: parseFloat(tokenCost.toFixed(4)),
+      hours_saved: parseFloat(hoursSaved.toFixed(2)),
+      gross_value: parseFloat(grossValue.toFixed(2)),
+      net_value: parseFloat(netValue.toFixed(2)),
+      roi_percentage: parseFloat(roi.toFixed(1)),
+      currency: 'USD'
+    };
+  }
+
+  detectTaskType(msg) {
+    const m = msg.toLowerCase();
+    if (m.includes('refactor')) return 'refactor';
+    if (m.includes('test') || m.includes('verify')) return 'test';
+    if (m.includes('architect') || m.includes('design') || m.includes('pillar')) return 'architect';
+    return 'default';
+  }
+}
+
+module.exports = new ROIEngine();

package/bin/revops/velocity-forecaster.js

@@ -0,0 +1,59 @@
+/**
+ * MindForge v5.10.0 — AgRevOps Velocity Forecaster
+ * Predicts milestone completion ETA based on historical velocity.
+ */
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+class VelocityForecaster {
+  constructor() {
+    this.auditPath = path.join(process.cwd(), '.planning', 'AUDIT.jsonl');
+  }
+
+  /**
+   * Predict completion ETA for remaining tasks.
+   * @param {Object} metrics - From MetricsAggregator
+   */
+  predict(metrics) {
+    const completedTasks = metrics.auditEntries?.filter(e => e.event === 'task_completed') || [];
+    if (completedTasks.length < 2) {
+      return { 
+        avg_seconds_per_task: 0, 
+        tasks_remaining: metrics.tasks_total - metrics.tasks_completed, 
+        eta: 'Inconclusive (Not enough data)' 
+      };
+    }
+
+    // Sort by timestamp
+    const sorted = [...completedTasks].sort((a,b) => new Date(a.timestamp) - new Date(b.timestamp));
+    
+    // Calculate historical duration between tasks
+    let totalSeconds = 0;
+    for (let i = 1; i < sorted.length; i++) {
+        const delta = (new Date(sorted[i].timestamp) - new Date(sorted[i - 1].timestamp)) / 1000;
+        // ignore outliers (gaps longer than 1 hour)
+        if (delta < 3600) {
+            totalSeconds += delta;
+        }
+    }
+
+    const avgSeconds = totalSeconds / (sorted.length - 1) || 0;
+    const remainingTasks = Math.max(0, metrics.tasks_total - metrics.tasks_completed);
+    const etaSeconds = avgSeconds * remainingTasks;
+
+    const etaDate = new Date(Date.now() + (etaSeconds * 1000));
+
+    return {
+      avg_seconds_per_task: parseFloat(avgSeconds.toFixed(1)),
+      tasks_completed: metrics.tasks_completed,
+      tasks_remaining: remainingTasks,
+      eta: remainingTasks > 0 ? etaDate.toLocaleString() : 'Done',
+      confidence: completedTasks.length > 5 ? 'High (85%)' : 'Medium (60%)',
+      timestamp: new Date().toISOString()
+    };
+  }
+}
+
+module.exports = new VelocityForecaster();