@aiready/core 0.9.38 → 0.17.0

package/dist/index.mjs

@@ -20,6 +20,54 @@ import {
   parseWeightString
 } from "./chunk-UQGI67WR.mjs";
 
+// src/types/contract.ts
+function validateSpokeOutput(toolName, output) {
+  const errors = [];
+  if (!output) {
+    return { valid: false, errors: ["Output is null or undefined"] };
+  }
+  if (!Array.isArray(output.results)) {
+    errors.push(`${toolName}: 'results' must be an array`);
+  } else {
+    output.results.forEach((res, idx) => {
+      const fileName = res.fileName || res.file || res.filePath;
+      if (!fileName)
+        errors.push(
+          `${toolName}: results[${idx}] missing 'fileName', 'file' or 'filePath'`
+        );
+      const issues = res.issues;
+      if (!Array.isArray(issues)) {
+        errors.push(`${toolName}: results[${idx}] 'issues' must be an array`);
+      } else if (issues.length > 0) {
+        issues.forEach((issue, iidx) => {
+          if (typeof issue === "string") return;
+          if (!issue.type && !res.file)
+            errors.push(
+              `${toolName}: results[${idx}].issues[${iidx}] missing 'type'`
+            );
+          if (!issue.severity && !res.severity)
+            errors.push(
+              `${toolName}: results[${idx}].issues[${iidx}] missing 'severity'`
+            );
+          const severity = issue.severity || res.severity;
+          if (severity && !["critical", "major", "minor", "info"].includes(severity)) {
+            errors.push(
+              `${toolName}: results[${idx}].issues[${iidx}] has invalid severity: ${severity}`
+            );
+          }
+        });
+      }
+    });
+  }
+  if (!output.summary) {
+    errors.push(`${toolName}: missing 'summary'`);
+  }
+  return {
+    valid: errors.length === 0,
+    errors
+  };
+}
+
 // src/utils/file-scanner.ts
 import { glob } from "glob";
 import { readFile } from "fs/promises";
@@ -513,8 +561,43 @@ function handleCLIError(error, commandName) {
 function getElapsedTime(startTime) {
   return ((Date.now() - startTime) / 1e3).toFixed(2);
 }
+function getScoreBar(val) {
+  return "\u2588".repeat(Math.round(val / 10)).padEnd(10, "\u2591");
+}
+function getSafetyIcon(rating) {
+  switch (rating) {
+    case "safe":
+      return "\u2705";
+    case "moderate-risk":
+      return "\u26A0\uFE0F ";
+    case "high-risk":
+      return "\u{1F534}";
+    case "blind-risk":
+      return "\u{1F480}";
+    default:
+      return "\u2753";
+  }
+}
+function getSeverityColor(severity, chalk) {
+  switch (severity.toLowerCase()) {
+    case "critical":
+    case "high-risk":
+    case "blind-risk":
+      return chalk.red;
+    case "major":
+    case "moderate-risk":
+      return chalk.yellow;
+    case "minor":
+    case "safe":
+      return chalk.green;
+    case "info":
+      return chalk.blue;
+    default:
+      return chalk.white;
+  }
+}
 
-// src/business-metrics.ts
+// src/business/pricing-models.ts
 var MODEL_PRICING_PRESETS = {
   "gpt-5.3": {
     name: "GPT-5.3",
@@ -576,30 +659,17 @@ var MODEL_PRICING_PRESETS = {
 function getModelPreset(modelId) {
   return MODEL_PRICING_PRESETS[modelId] ?? MODEL_PRICING_PRESETS["claude-4.6"];
 }
+
+// src/business/cost-metrics.ts
 var DEFAULT_COST_CONFIG = {
   pricePer1KTokens: 5e-3,
-  // GPT-4o input price (updated from GPT-4 era 0.01)
   queriesPerDevPerDay: 60,
-  // Average AI queries per developer (updated: 40→60 as of 2026)
   developerCount: 5,
-  // Default team size
   daysPerMonth: 30
 };
-var SEVERITY_TIME_ESTIMATES = {
-  critical: 4,
-  // Complex architectural issues (industry avg: 6.8h)
-  major: 2,
-  // Significant refactoring needed (avg: 3.4h)
-  minor: 0.5,
-  // Simple naming/style fixes (avg: 0.8h)
-  info: 0.25
-  // Documentation improvements
-};
-var DEFAULT_HOURLY_RATE = 75;
 function calculateMonthlyCost(tokenWaste, config = {}) {
   const budget = calculateTokenBudget({
     totalContextTokens: tokenWaste * 2.5,
-    // Heuristic: context is larger than waste
     wastedTokens: {
       duplication: tokenWaste * 0.7,
       fragmentation: tokenWaste * 0.3,
@@ -633,7 +703,6 @@ function calculateTokenBudget(params) {
     },
     efficiencyRatio: Math.round(efficiencyRatio * 100) / 100,
     potentialRetrievableTokens: Math.round(totalWaste * 0.8)
-    // Heuristic: 80% is fixable
   };
 }
 function estimateCostFromBudget(budget, model, config = {}) {
@@ -657,6 +726,15 @@ function estimateCostFromBudget(budget, model, config = {}) {
     confidence
   };
 }
+
+// src/business/productivity-metrics.ts
+var SEVERITY_TIME_ESTIMATES = {
+  critical: 4,
+  major: 2,
+  minor: 0.5,
+  info: 0.25
+};
+var DEFAULT_HOURLY_RATE = 75;
 function calculateProductivityImpact(issues, hourlyRate = DEFAULT_HOURLY_RATE) {
   const counts = {
     critical: issues.filter((i) => i.severity === "critical").length,
@@ -697,108 +775,158 @@ function predictAcceptanceRate(toolOutputs) {
   const baseRate = 0.3;
   const patterns = toolOutputs.get("pattern-detect");
   if (patterns) {
-    const patternImpact = (patterns.score - 50) * 3e-3;
     factors.push({
       name: "Semantic Duplication",
-      impact: Math.round(patternImpact * 100)
+      impact: Math.round((patterns.score - 50) * 3e-3 * 100)
     });
   }
   const context = toolOutputs.get("context-analyzer");
   if (context) {
-    const contextImpact = (context.score - 50) * 4e-3;
     factors.push({
       name: "Context Efficiency",
-      impact: Math.round(contextImpact * 100)
+      impact: Math.round((context.score - 50) * 4e-3 * 100)
     });
   }
   const consistency = toolOutputs.get("consistency");
   if (consistency) {
-    const consistencyImpact = (consistency.score - 50) * 2e-3;
     factors.push({
       name: "Code Consistency",
-      impact: Math.round(consistencyImpact * 100)
+      impact: Math.round((consistency.score - 50) * 2e-3 * 100)
     });
   }
   const aiSignalClarity = toolOutputs.get("ai-signal-clarity");
   if (aiSignalClarity) {
-    const hrImpact = (50 - aiSignalClarity.score) * 2e-3;
     factors.push({
       name: "AI Signal Clarity",
-      impact: Math.round(hrImpact * 100)
+      impact: Math.round((50 - aiSignalClarity.score) * 2e-3 * 100)
     });
   }
   const totalImpact = factors.reduce((sum, f) => sum + f.impact / 100, 0);
   const rate = Math.max(0.05, Math.min(0.8, baseRate + totalImpact));
-  let confidence;
+  let confidence = 0.35;
   if (toolOutputs.size >= 4) confidence = 0.75;
   else if (toolOutputs.size >= 3) confidence = 0.65;
   else if (toolOutputs.size >= 2) confidence = 0.5;
-  else confidence = 0.35;
-  return {
-    rate: Math.round(rate * 100) / 100,
-    confidence,
-    factors
-  };
+  return { rate: Math.round(rate * 100) / 100, confidence, factors };
 }
-function calculateComprehensionDifficulty(contextBudget, importDepth, fragmentation, consistencyScore, totalFiles, modelTier = "standard") {
-  const tierThresholds = CONTEXT_TIER_THRESHOLDS[modelTier];
-  const idealBudget = tierThresholds.idealTokens;
-  const criticalBudget = tierThresholds.criticalTokens;
-  const idealDepth = tierThresholds.idealDepth;
-  const budgetRange = criticalBudget - idealBudget;
-  const budgetFactor = Math.min(
-    100,
-    Math.max(0, (contextBudget - idealBudget) / budgetRange * 100)
-  );
-  const depthFactor = Math.min(
-    100,
-    Math.max(0, (importDepth - idealDepth) * 10)
-  );
-  const fragmentationFactor = Math.min(
-    100,
-    Math.max(0, (fragmentation - 0.3) * 250)
-  );
-  const consistencyFactor = Math.min(100, Math.max(0, 100 - consistencyScore));
-  const fileFactor = Math.min(100, Math.max(0, (totalFiles - 50) / 5));
+
+// src/business/risk-metrics.ts
+function calculateKnowledgeConcentration(params) {
+  const { uniqueConceptFiles, totalFiles, singleAuthorFiles, orphanFiles } = params;
+  const concentrationRatio = totalFiles > 0 ? (uniqueConceptFiles + singleAuthorFiles) / (totalFiles * 2) : 0;
   const score = Math.round(
-    budgetFactor * 0.35 + depthFactor * 0.2 + fragmentationFactor * 0.2 + consistencyFactor * 0.15 + fileFactor * 0.1
+    Math.min(
+      100,
+      concentrationRatio * 100 + orphanFiles / Math.max(1, totalFiles) * 20
+    )
   );
   let rating;
-  if (score < 20) rating = "trivial";
-  else if (score < 40) rating = "easy";
-  else if (score < 60) rating = "moderate";
-  else if (score < 80) rating = "difficult";
-  else rating = "expert";
+  if (score < 30) rating = "low";
+  else if (score < 50) rating = "moderate";
+  else if (score < 75) rating = "high";
+  else rating = "critical";
+  const recommendations = [];
+  if (singleAuthorFiles > 0)
+    recommendations.push(
+      `Distribute knowledge for ${singleAuthorFiles} single-author files.`
+    );
+  if (orphanFiles > 0)
+    recommendations.push(
+      `Link ${orphanFiles} orphan files to the rest of the codebase.`
+    );
   return {
     score,
     rating,
-    factors: [
-      {
-        name: "Context Budget",
-        contribution: Math.round(budgetFactor * 0.35),
-        description: `${Math.round(contextBudget)} tokens required (${modelTier} model tier: ideal <${idealBudget.toLocaleString()})`
-      },
-      {
-        name: "Import Depth",
-        contribution: Math.round(depthFactor * 0.2),
-        description: `${importDepth.toFixed(1)} average levels (ideal <${idealDepth} for ${modelTier})`
-      },
-      {
-        name: "Code Fragmentation",
-        contribution: Math.round(fragmentationFactor * 0.2),
-        description: `${(fragmentation * 100).toFixed(0)}% fragmentation`
-      },
-      {
-        name: "Consistency",
-        contribution: Math.round(consistencyFactor * 0.15),
-        description: `${consistencyScore}/100 consistency score`
-      },
-      {
-        name: "Project Scale",
-        contribution: Math.round(fileFactor * 0.1),
-        description: `${totalFiles} files analyzed`
-      }
-    ]
+    recommendations,
+    analysis: {
+      uniqueConceptFiles,
+      totalFiles,
+      concentrationRatio,
+      singleAuthorFiles,
+      orphanFiles
+    }
+  };
+}
+function calculateDebtInterest(principal, monthlyGrowthRate) {
+  const monthlyRate = monthlyGrowthRate;
+  const annualRate = Math.pow(1 + monthlyRate, 12) - 1;
+  const monthlyCost = principal * monthlyRate;
+  return {
+    monthlyRate,
+    annualRate,
+    principal,
+    monthlyCost,
+    projections: {
+      months6: principal * Math.pow(1 + monthlyRate, 6),
+      months12: principal * Math.pow(1 + monthlyRate, 12),
+      months24: principal * Math.pow(1 + monthlyRate, 24)
+    }
+  };
+}
+
+// src/business/comprehension-metrics.ts
+function calculateTechnicalValueChain(params) {
+  const { businessLogicDensity, dataAccessComplexity, apiSurfaceArea } = params;
+  const score = (businessLogicDensity * 0.5 + (1 - dataAccessComplexity / 10) * 0.3 + (1 - apiSurfaceArea / 20) * 0.2) * 100;
+  return {
+    score: Math.round(Math.max(0, Math.min(100, score))),
+    density: businessLogicDensity,
+    complexity: dataAccessComplexity,
+    surface: apiSurfaceArea
+  };
+}
+function calculateComprehensionDifficulty(contextBudget, importDepth, fragmentation, modelTier = "frontier") {
+  const tierMap = {
+    compact: "compact",
+    standard: "standard",
+    extended: "extended",
+    frontier: "frontier",
+    easy: "frontier",
+    // Map legacy 'easy' to 'frontier'
+    moderate: "standard",
+    difficult: "compact"
+  };
+  const tier = tierMap[modelTier] || "frontier";
+  const threshold = CONTEXT_TIER_THRESHOLDS[tier];
+  const budgetRatio = contextBudget / threshold.idealTokens;
+  const score = (budgetRatio * 0.6 + importDepth / 10 * 0.2 + fragmentation * 0.2) * 100;
+  const finalScore = Math.round(Math.max(0, Math.min(100, score)));
+  let rating;
+  if (finalScore < 20) rating = "trivial";
+  else if (finalScore < 40) rating = "easy";
+  else if (finalScore < 60) rating = "moderate";
+  else if (finalScore < 85) rating = "difficult";
+  else rating = "expert";
+  return {
+    score: finalScore,
+    rating,
+    factors: { budgetRatio, depthRatio: importDepth / 10, fragmentation }
+  };
+}
+
+// src/business-metrics.ts
+function calculateBusinessROI(params) {
+  const model = getModelPreset(params.modelId || "claude-4.6");
+  const devCount = params.developerCount || 5;
+  const budget = calculateTokenBudget({
+    totalContextTokens: params.tokenWaste * 2.5,
+    wastedTokens: {
+      duplication: params.tokenWaste * 0.7,
+      fragmentation: params.tokenWaste * 0.3,
+      chattiness: 0
+    }
+  });
+  const cost = estimateCostFromBudget(budget, model, {
+    developerCount: devCount
+  });
+  const productivity = calculateProductivityImpact(params.issues);
+  const monthlySavings = cost.total;
+  const productivityGainHours = productivity.totalHours;
+  const annualValue = (monthlySavings + productivityGainHours * 75) * 12;
+  return {
+    monthlySavings: Math.round(monthlySavings),
+    productivityGainHours: Math.round(productivityGainHours),
+    annualValue: Math.round(annualValue)
   };
 }
 function formatCost(cost) {
@@ -824,220 +952,6 @@ function formatHours(hours) {
 function formatAcceptanceRate(rate) {
   return `${Math.round(rate * 100)}%`;
 }
-function calculateScoreTrend(history) {
-  if (history.length < 2) {
-    return {
-      direction: "stable",
-      change30Days: 0,
-      change90Days: 0,
-      velocity: 0,
-      projectedScore: history[0]?.overallScore || 100
-    };
-  }
-  const now = /* @__PURE__ */ new Date();
-  const thirtyDaysAgo = new Date(now.getTime() - 30 * 24 * 60 * 60 * 1e3);
-  const ninetyDaysAgo = new Date(now.getTime() - 90 * 24 * 60 * 60 * 1e3);
-  const last30Days = history.filter(
-    (e) => new Date(e.timestamp) >= thirtyDaysAgo
-  );
-  const last90Days = history.filter(
-    (e) => new Date(e.timestamp) >= ninetyDaysAgo
-  );
-  const currentScore = history[history.length - 1].overallScore;
-  const thirtyDaysAgoScore = last30Days[0]?.overallScore || currentScore;
-  const ninetyDaysAgoScore = last90Days[0]?.overallScore || thirtyDaysAgoScore;
-  const change30Days = currentScore - thirtyDaysAgoScore;
-  const change90Days = currentScore - ninetyDaysAgoScore;
-  const weeksOfData = Math.max(1, history.length / 7);
-  const totalChange = currentScore - history[0].overallScore;
-  const velocity = totalChange / weeksOfData;
-  let direction;
-  if (change30Days > 3) direction = "improving";
-  else if (change30Days < -3) direction = "degrading";
-  else direction = "stable";
-  const projectedScore = Math.max(
-    0,
-    Math.min(100, currentScore + velocity * 4)
-  );
-  return {
-    direction,
-    change30Days,
-    change90Days,
-    velocity: Math.round(velocity * 10) / 10,
-    projectedScore: Math.round(projectedScore)
-  };
-}
-function calculateRemediationVelocity(history, currentIssues) {
-  if (history.length < 2) {
-    return {
-      issuesFixedThisWeek: 0,
-      avgIssuesPerWeek: 0,
-      trend: "stable",
-      estimatedCompletionWeeks: currentIssues > 0 ? Infinity : 0
-    };
-  }
-  const now = /* @__PURE__ */ new Date();
-  const oneWeekAgo = new Date(now.getTime() - 7 * 24 * 60 * 60 * 1e3);
-  const twoWeeksAgo = new Date(now.getTime() - 14 * 24 * 60 * 60 * 1e3);
-  const thisWeek = history.filter((e) => new Date(e.timestamp) >= oneWeekAgo);
-  const lastWeek = history.filter(
-    (e) => new Date(e.timestamp) >= twoWeeksAgo && new Date(e.timestamp) < oneWeekAgo
-  );
-  const issuesFixedThisWeek = thisWeek.length > 1 ? thisWeek[0].totalIssues - thisWeek[thisWeek.length - 1].totalIssues : 0;
-  const totalIssuesFixed = history[0].totalIssues - history[history.length - 1].totalIssues;
-  const weeksOfData = Math.max(1, history.length / 7);
-  const avgIssuesPerWeek = totalIssuesFixed / weeksOfData;
-  let trend;
-  if (lastWeek.length > 1) {
-    const lastWeekFixed = lastWeek[0].totalIssues - lastWeek[lastWeek.length - 1].totalIssues;
-    if (issuesFixedThisWeek > lastWeekFixed * 1.2) trend = "accelerating";
-    else if (issuesFixedThisWeek < lastWeekFixed * 0.8) trend = "decelerating";
-    else trend = "stable";
-  } else {
-    trend = "stable";
-  }
-  const estimatedCompletionWeeks = avgIssuesPerWeek > 0 ? Math.ceil(currentIssues / avgIssuesPerWeek) : Infinity;
-  return {
-    issuesFixedThisWeek: Math.max(0, issuesFixedThisWeek),
-    avgIssuesPerWeek: Math.round(avgIssuesPerWeek * 10) / 10,
-    trend,
-    estimatedCompletionWeeks
-  };
-}
-function calculateKnowledgeConcentration(files, authorData) {
-  if (files.length === 0) {
-    return {
-      score: 0,
-      rating: "low",
-      analysis: {
-        uniqueConceptFiles: 0,
-        totalFiles: 0,
-        concentrationRatio: 0,
-        singleAuthorFiles: 0,
-        orphanFiles: 0
-      },
-      recommendations: ["No files to analyze"]
-    };
-  }
-  const orphanFiles = files.filter(
-    (f) => f.exports < 2 && f.imports < 2
-  ).length;
-  const avgExports = files.reduce((sum, f) => sum + f.exports, 0) / files.length;
-  const uniqueConceptFiles = files.filter(
-    (f) => f.exports > avgExports * 2
-  ).length;
-  const totalExports = files.reduce((sum, f) => sum + f.exports, 0);
-  const concentrationRatio = totalExports > 0 ? uniqueConceptFiles / files.length : 0;
-  let singleAuthorFiles = 0;
-  if (authorData) {
-    for (const files2 of authorData.values()) {
-      if (files2.length === 1) singleAuthorFiles++;
-    }
-  }
-  const orphanRisk = orphanFiles / files.length * 30;
-  const uniqueRisk = concentrationRatio * 40;
-  const singleAuthorRisk = authorData ? singleAuthorFiles / files.length * 30 : 0;
-  const score = Math.min(
-    100,
-    Math.round(orphanRisk + uniqueRisk + singleAuthorRisk)
-  );
-  let rating;
-  if (score < 20) rating = "low";
-  else if (score < 40) rating = "moderate";
-  else if (score < 70) rating = "high";
-  else rating = "critical";
-  const recommendations = [];
-  if (orphanFiles > files.length * 0.2) {
-    recommendations.push(
-      `Reduce ${orphanFiles} orphan files by connecting them to main modules`
-    );
-  }
-  if (uniqueConceptFiles > files.length * 0.1) {
-    recommendations.push(
-      "Distribute high-export files into more focused modules"
-    );
-  }
-  if (authorData && singleAuthorFiles > files.length * 0.3) {
-    recommendations.push(
-      "Increase knowledge sharing to reduce single-author dependencies"
-    );
-  }
-  return {
-    score,
-    rating,
-    analysis: {
-      uniqueConceptFiles,
-      totalFiles: files.length,
-      concentrationRatio: Math.round(concentrationRatio * 100) / 100,
-      singleAuthorFiles,
-      orphanFiles
-    },
-    recommendations
-  };
-}
-function calculateTechnicalDebtInterest(params) {
-  const { currentMonthlyCost, issues, monthsOpen } = params;
-  const criticalCount = issues.filter((i) => i.severity === "critical").length;
-  const majorCount = issues.filter((i) => i.severity === "major").length;
-  const minorCount = issues.filter((i) => i.severity === "minor").length;
-  const severityWeight = (criticalCount * 3 + majorCount * 2 + minorCount * 1) / Math.max(1, issues.length);
-  const baseRate = 0.02 + severityWeight * 0.01;
-  const timeMultiplier = Math.max(1, 1 + monthsOpen * 0.1);
-  const monthlyRate = baseRate * timeMultiplier;
-  const projectDebt = (principal2, months) => {
-    let debt = principal2;
-    for (let i = 0; i < months; i++) {
-      debt = debt * (1 + monthlyRate);
-    }
-    return Math.round(debt);
-  };
-  const principal = currentMonthlyCost * 12;
-  const projections = {
-    months6: projectDebt(principal, 6),
-    months12: projectDebt(principal, 12),
-    months24: projectDebt(principal, 24)
-  };
-  return {
-    monthlyRate: Math.round(monthlyRate * 1e4) / 100,
-    annualRate: Math.round((Math.pow(1 + monthlyRate, 12) - 1) * 1e4) / 100,
-    principal,
-    projections,
-    monthlyCost: Math.round(currentMonthlyCost * (1 + monthlyRate) * 100) / 100
-  };
-}
-function getDebtBreakdown(patternCost, contextCost, consistencyCost) {
-  const breakdowns = [
-    {
-      category: "Semantic Duplication",
-      currentCost: patternCost,
-      monthlyGrowthRate: 5,
-      // Grows as devs copy-paste
-      priority: patternCost > 1e3 ? "high" : "medium",
-      fixCost: patternCost * 3
-      // Fixing costs 3x current waste
-    },
-    {
-      category: "Context Fragmentation",
-      currentCost: contextCost,
-      monthlyGrowthRate: 3,
-      // Grows with new features
-      priority: contextCost > 500 ? "high" : "medium",
-      fixCost: contextCost * 2.5
-    },
-    {
-      category: "Consistency Issues",
-      currentCost: consistencyCost,
-      monthlyGrowthRate: 2,
-      // Grows with new devs
-      priority: consistencyCost > 200 ? "medium" : "low",
-      fixCost: consistencyCost * 1.5
-    }
-  ];
-  return breakdowns.sort((a, b) => {
-    const priorityOrder = { high: 0, medium: 1, low: 2 };
-    return priorityOrder[a.priority] - priorityOrder[b.priority];
-  });
-}
 function generateValueChain(params) {
   const { issueType, count, severity } = params;
   const impacts = {
@@ -1077,9 +991,7 @@ function generateValueChain(params) {
     },
     businessOutcome: {
       directCost: count * 12,
-      // Placeholder linear cost
       opportunityCost: productivityLoss * 15e3,
-      // Monthly avg dev cost $15k
       riskLevel: impact.risk
     }
   };
@@ -1594,7 +1506,55 @@ function getSupportedLanguages() {
   return ParserFactory.getInstance().getSupportedLanguages();
 }
 
-// src/future-proof-metrics.ts
+// src/metrics/remediation-utils.ts
+function collectFutureProofRecommendations(params) {
+  const recommendations = [];
+  for (const rec of params.aiSignalClarity.recommendations) {
+    recommendations.push({ action: rec, estimatedImpact: 8, priority: "high" });
+  }
+  for (const rec of params.agentGrounding.recommendations) {
+    recommendations.push({
+      action: rec,
+      estimatedImpact: 6,
+      priority: "medium"
+    });
+  }
+  for (const rec of params.testability.recommendations) {
+    const priority = params.testability.aiChangeSafetyRating === "blind-risk" ? "high" : "medium";
+    recommendations.push({ action: rec, estimatedImpact: 10, priority });
+  }
+  for (const rec of params.patternEntropy.recommendations) {
+    recommendations.push({ action: rec, estimatedImpact: 5, priority: "low" });
+  }
+  if (params.conceptCohesion.rating === "poor") {
+    recommendations.push({
+      action: "Improve concept cohesion by grouping related exports",
+      estimatedImpact: 8,
+      priority: "high"
+    });
+  }
+  if (params.docDrift) {
+    for (const rec of params.docDrift.recommendations) {
+      recommendations.push({
+        action: rec,
+        estimatedImpact: 8,
+        priority: "high"
+      });
+    }
+  }
+  if (params.dependencyHealth) {
+    for (const rec of params.dependencyHealth.recommendations) {
+      recommendations.push({
+        action: rec,
+        estimatedImpact: 7,
+        priority: "medium"
+      });
+    }
+  }
+  return recommendations;
+}
+
+// src/metrics/cognitive-load.ts
 function calculateCognitiveLoad(params) {
   const {
     linesOfCode,
@@ -1653,13 +1613,20 @@ function calculateCognitiveLoad(params) {
     }
   };
 }
+
+// src/metrics/semantic-distance.ts
 function calculateSemanticDistance(params) {
-  const { file1, file2, file1Domain, file2Domain, sharedDependencies } = params;
+  const {
+    file1,
+    file2,
+    file1Domain,
+    file2Domain,
+    sharedDependencies,
+    file1Imports,
+    file2Imports
+  } = params;
   const domainDistance = file1Domain === file2Domain ? 0 : file1Domain && file2Domain ? 0.5 : 0.8;
-  const importOverlap = sharedDependencies.length / Math.max(
-    1,
-    Math.min(params.file1Imports.length, params.file2Imports.length)
-  );
+  const importOverlap = sharedDependencies.length / Math.max(1, Math.min(file1Imports.length, file2Imports.length));
   const importDistance = 1 - importOverlap;
   const distance = domainDistance * 0.4 + importDistance * 0.3 + (sharedDependencies.length > 0 ? 0 : 0.3);
   let relationship;
@@ -1678,6 +1645,8 @@ function calculateSemanticDistance(params) {
     reason: relationship === "same-domain" ? `Both in "${file1Domain}" domain` : relationship === "cross-domain" ? `Share ${sharedDependencies.length} dependency(ies)` : "No strong semantic relationship detected"
   };
 }
+
+// src/metrics/structural-metrics.ts
 function calculatePatternEntropy(files) {
   if (files.length === 0) {
     return {
@@ -1727,23 +1696,18 @@ function calculatePatternEntropy(files) {
   else if (normalizedEntropy < 0.8) rating = "fragmented";
   else rating = "chaotic";
   const recommendations = [];
-  if (normalizedEntropy > 0.5) {
+  if (normalizedEntropy > 0.5)
     recommendations.push(
       `Consolidate ${files.length} files into fewer directories by domain`
     );
-  }
-  if (dirGroups.size > 5) {
+  if (dirGroups.size > 5)
     recommendations.push(
       "Consider barrel exports to reduce directory navigation"
     );
-  }
-  if (gini > 0.5) {
+  if (gini > 0.5)
     recommendations.push("Redistribute files more evenly across directories");
-  }
-  const firstFile = files.length > 0 ? files[0] : null;
-  const domainValue = firstFile ? firstFile.domain : "mixed";
   return {
-    domain: domainValue,
+    domain: files[0]?.domain || "mixed",
     entropy: Math.round(normalizedEntropy * 100) / 100,
     rating,
     distribution: {
@@ -1774,9 +1738,8 @@ function calculateConceptCohesion(params) {
   }
   const uniqueDomains = new Set(allDomains);
   const domainCounts = /* @__PURE__ */ new Map();
-  for (const d of allDomains) {
+  for (const d of allDomains)
     domainCounts.set(d, (domainCounts.get(d) || 0) + 1);
-  }
   const maxCount = Math.max(...Array.from(domainCounts.values()), 1);
   const domainConcentration = maxCount / allDomains.length;
   const exportPurposeClarity = 1 - (uniqueDomains.size - 1) / Math.max(1, exports.length);
@@ -1796,59 +1759,8 @@ function calculateConceptCohesion(params) {
     }
   };
 }
-function calculateFutureProofScore(params) {
-  const loadScore = 100 - params.cognitiveLoad.score;
-  const entropyScore = 100 - params.patternEntropy.entropy * 100;
-  const cohesionScore = params.conceptCohesion.score * 100;
-  const overall = Math.round(
-    loadScore * 0.4 + entropyScore * 0.3 + cohesionScore * 0.3
-  );
-  const factors = [
-    {
-      name: "Cognitive Load",
-      impact: Math.round(loadScore - 50),
-      description: params.cognitiveLoad.rating
-    },
-    {
-      name: "Pattern Entropy",
-      impact: Math.round(entropyScore - 50),
-      description: params.patternEntropy.rating
-    },
-    {
-      name: "Concept Cohesion",
-      impact: Math.round(cohesionScore - 50),
-      description: params.conceptCohesion.rating
-    }
-  ];
-  const recommendations = [];
-  for (const rec of params.patternEntropy.recommendations) {
-    recommendations.push({
-      action: rec,
-      estimatedImpact: 5,
-      priority: "medium"
-    });
-  }
-  if (params.conceptCohesion.rating === "poor") {
-    recommendations.push({
-      action: "Improve concept cohesion by grouping related exports",
-      estimatedImpact: 8,
-      priority: "high"
-    });
-  }
-  const semanticDistanceAvg = params.semanticDistances && params.semanticDistances.length > 0 ? params.semanticDistances.reduce((s, d) => s + d.distance, 0) / params.semanticDistances.length : 0;
-  return {
-    toolName: "future-proof",
-    score: overall,
-    rawMetrics: {
-      cognitiveLoadScore: params.cognitiveLoad.score,
-      entropyScore: params.patternEntropy.entropy,
-      cohesionScore: params.conceptCohesion.score,
-      semanticDistanceAvg
-    },
-    factors,
-    recommendations
-  };
-}
+
+// src/metrics/ai-signal-clarity.ts
 function calculateAiSignalClarity(params) {
   const {
     overloadedSymbols,
@@ -1870,75 +1782,53 @@ function calculateAiSignalClarity(params) {
       recommendations: []
     };
   }
-  const overloadRatio = Math.min(
-    1,
-    overloadedSymbols / Math.max(1, totalSymbols)
-  );
+  const overloadRatio = overloadedSymbols / Math.max(1, totalSymbols);
   const overloadSignal = {
     name: "Symbol Overloading",
     count: overloadedSymbols,
-    riskContribution: Math.round(overloadRatio * 100 * 0.25),
-    // 25% weight
+    riskContribution: Math.round(Math.min(1, overloadRatio) * 100 * 0.25),
     description: `${overloadedSymbols} overloaded symbols \u2014 AI picks wrong signature`
   };
-  const magicRatio = Math.min(1, magicLiterals / Math.max(1, totalSymbols * 2));
+  const magicRatio = magicLiterals / Math.max(1, totalSymbols * 2);
   const magicSignal = {
     name: "Magic Literals",
     count: magicLiterals,
-    riskContribution: Math.round(magicRatio * 100 * 0.2),
-    // 20% weight
+    riskContribution: Math.round(Math.min(1, magicRatio) * 100 * 0.2),
     description: `${magicLiterals} unnamed constants \u2014 AI invents wrong values`
   };
-  const trapRatio = Math.min(1, booleanTraps / Math.max(1, totalSymbols));
+  const trapRatio = booleanTraps / Math.max(1, totalSymbols);
   const trapSignal = {
     name: "Boolean Traps",
     count: booleanTraps,
-    riskContribution: Math.round(trapRatio * 100 * 0.2),
-    // 20% weight
+    riskContribution: Math.round(Math.min(1, trapRatio) * 100 * 0.2),
     description: `${booleanTraps} boolean trap parameters \u2014 AI inverts intent`
   };
-  const sideEffectRatio = Math.min(
-    1,
-    implicitSideEffects / Math.max(1, totalExports)
-  );
+  const sideEffectRatio = implicitSideEffects / Math.max(1, totalExports);
   const sideEffectSignal = {
     name: "Implicit Side Effects",
     count: implicitSideEffects,
-    riskContribution: Math.round(sideEffectRatio * 100 * 0.15),
-    // 15% weight
+    riskContribution: Math.round(Math.min(1, sideEffectRatio) * 100 * 0.15),
     description: `${implicitSideEffects} functions with implicit side effects \u2014 AI misses contracts`
   };
-  const callbackRatio = Math.min(
-    1,
-    deepCallbacks / Math.max(1, totalSymbols * 0.1)
-  );
+  const callbackRatio = deepCallbacks / Math.max(1, totalSymbols * 0.1);
   const callbackSignal = {
     name: "Callback Nesting",
     count: deepCallbacks,
-    riskContribution: Math.round(callbackRatio * 100 * 0.1),
-    // 10% weight
+    riskContribution: Math.round(Math.min(1, callbackRatio) * 100 * 0.1),
     description: `${deepCallbacks} deep callback chains \u2014 AI loses control flow context`
   };
-  const ambiguousRatio = Math.min(
-    1,
-    ambiguousNames / Math.max(1, totalSymbols)
-  );
+  const ambiguousRatio = ambiguousNames / Math.max(1, totalSymbols);
   const ambiguousSignal = {
     name: "Ambiguous Names",
     count: ambiguousNames,
-    riskContribution: Math.round(ambiguousRatio * 100 * 0.1),
-    // 10% weight
+    riskContribution: Math.round(Math.min(1, ambiguousRatio) * 100 * 0.1),
     description: `${ambiguousNames} non-descriptive identifiers \u2014 AI guesses wrong intent`
   };
-  const undocRatio = Math.min(
-    1,
-    undocumentedExports / Math.max(1, totalExports)
-  );
+  const undocRatio = undocumentedExports / Math.max(1, totalExports);
   const undocSignal = {
     name: "Undocumented Exports",
     count: undocumentedExports,
-    riskContribution: Math.round(undocRatio * 100 * 0.1),
-    // 10% weight
+    riskContribution: Math.round(Math.min(1, undocRatio) * 100 * 0.1),
     description: `${undocumentedExports} public functions without docs \u2014 AI fabricates behavior`
   };
   const signals = [
@@ -1963,33 +1853,28 @@ function calculateAiSignalClarity(params) {
   const topSignal = signals.reduce(
     (a, b) => a.riskContribution > b.riskContribution ? a : b
   );
-  const topRisk = topSignal.riskContribution > 0 ? topSignal.description : "No significant AI signal claritys detected";
+  const topRisk = topSignal.riskContribution > 0 ? topSignal.description : "No significant issues detected";
   const recommendations = [];
-  if (overloadSignal.riskContribution > 5) {
+  if (overloadSignal.riskContribution > 5)
     recommendations.push(
       `Rename ${overloadedSymbols} overloaded symbols to unique, intent-revealing names`
     );
-  }
-  if (magicSignal.riskContribution > 5) {
+  if (magicSignal.riskContribution > 5)
     recommendations.push(
       `Extract ${magicLiterals} magic literals into named constants`
     );
-  }
-  if (trapSignal.riskContribution > 5) {
+  if (trapSignal.riskContribution > 5)
     recommendations.push(
       `Replace ${booleanTraps} boolean traps with named options objects`
     );
-  }
-  if (undocSignal.riskContribution > 5) {
+  if (undocSignal.riskContribution > 5)
     recommendations.push(
       `Add JSDoc/docstrings to ${undocumentedExports} undocumented public functions`
     );
-  }
-  if (sideEffectSignal.riskContribution > 5) {
+  if (sideEffectSignal.riskContribution > 5)
     recommendations.push(
       "Mark functions with side effects explicitly in their names or docs"
     );
-  }
   return {
     score: Math.round(score),
     rating,
@@ -1998,6 +1883,8 @@ function calculateAiSignalClarity(params) {
     recommendations
   };
 }
+
+// src/metrics/agent-grounding.ts
 function calculateAgentGrounding(params) {
   const {
     deepDirectories,
@@ -2012,25 +1899,33 @@ function calculateAgentGrounding(params) {
     inconsistentDomainTerms,
     domainVocabularySize
   } = params;
-  const deepDirRatio = totalDirectories > 0 ? deepDirectories / totalDirectories : 0;
   const structureClarityScore = Math.max(
     0,
-    Math.round(100 - deepDirRatio * 80)
+    Math.round(
+      100 - (totalDirectories > 0 ? deepDirectories / totalDirectories * 80 : 0)
+    )
+  );
+  const selfDocumentationScore = Math.max(
+    0,
+    Math.round(100 - (totalFiles > 0 ? vagueFileNames / totalFiles * 90 : 0))
   );
-  const vagueRatio = totalFiles > 0 ? vagueFileNames / totalFiles : 0;
-  const selfDocumentationScore = Math.max(0, Math.round(100 - vagueRatio * 90));
   let entryPointScore = 60;
   if (hasRootReadme) entryPointScore += 25;
   if (readmeIsFresh) entryPointScore += 10;
   const barrelRatio = totalFiles > 0 ? barrelExports / (totalFiles * 0.1) : 0;
   entryPointScore += Math.round(Math.min(5, barrelRatio * 5));
   entryPointScore = Math.min(100, entryPointScore);
-  const untypedRatio = totalExports > 0 ? untypedExports / totalExports : 0;
-  const apiClarityScore = Math.max(0, Math.round(100 - untypedRatio * 70));
-  const inconsistencyRatio = domainVocabularySize > 0 ? inconsistentDomainTerms / domainVocabularySize : 0;
+  const apiClarityScore = Math.max(
+    0,
+    Math.round(
+      100 - (totalExports > 0 ? untypedExports / totalExports * 70 : 0)
+    )
+  );
   const domainConsistencyScore = Math.max(
     0,
-    Math.round(100 - inconsistencyRatio * 80)
+    Math.round(
+      100 - (domainVocabularySize > 0 ? inconsistentDomainTerms / domainVocabularySize * 80 : 0)
+    )
   );
   const score = Math.round(
     structureClarityScore * 0.2 + selfDocumentationScore * 0.25 + entryPointScore * 0.2 + apiClarityScore * 0.15 + domainConsistencyScore * 0.2
@@ -2042,35 +1937,30 @@ function calculateAgentGrounding(params) {
   else if (score >= 30) rating = "poor";
   else rating = "disorienting";
   const recommendations = [];
-  if (structureClarityScore < 70) {
+  if (structureClarityScore < 70)
     recommendations.push(
       `Flatten ${deepDirectories} overly-deep directories to improve agent navigation`
     );
-  }
-  if (selfDocumentationScore < 70) {
+  if (selfDocumentationScore < 70)
     recommendations.push(
       `Rename ${vagueFileNames} vague files (utils, helpers, misc) to domain-specific names`
     );
-  }
-  if (!hasRootReadme) {
+  if (!hasRootReadme)
     recommendations.push(
       "Add a root README.md so agents understand the project context immediately"
     );
-  } else if (!readmeIsFresh) {
+  else if (!readmeIsFresh)
     recommendations.push(
       "Update README.md \u2014 stale entry-point documentation disorients agents"
     );
-  }
-  if (apiClarityScore < 70) {
+  if (apiClarityScore < 70)
     recommendations.push(
       `Add TypeScript types to ${untypedExports} untyped exports to improve API discoverability`
     );
-  }
-  if (domainConsistencyScore < 70) {
+  if (domainConsistencyScore < 70)
     recommendations.push(
       `Unify ${inconsistentDomainTerms} inconsistent domain terms \u2014 agents need one word per concept`
     );
-  }
   return {
     score,
     rating,
@@ -2084,6 +1974,8 @@ function calculateAgentGrounding(params) {
     recommendations
   };
 }
+
+// src/metrics/testability-index.ts
 function calculateTestabilityIndex(params) {
   const {
     testFiles,
@@ -2099,16 +1991,27 @@ function calculateTestabilityIndex(params) {
   } = params;
   const rawCoverageRatio = sourceFiles > 0 ? testFiles / sourceFiles : 0;
   const testCoverageRatio = Math.min(100, Math.round(rawCoverageRatio * 100));
-  const purityRatio = totalFunctions > 0 ? pureFunctions / totalFunctions : 0.5;
-  const purityScore = Math.round(purityRatio * 100);
-  const injectionRatio = totalClasses > 0 ? injectionPatterns / totalClasses : 0.5;
+  const purityScore = Math.round(
+    (totalFunctions > 0 ? pureFunctions / totalFunctions : 0.5) * 100
+  );
   const dependencyInjectionScore = Math.round(
-    Math.min(100, injectionRatio * 100)
+    Math.min(
+      100,
+      (totalClasses > 0 ? injectionPatterns / totalClasses : 0.5) * 100
+    )
+  );
+  const interfaceFocusScore = Math.max(
+    0,
+    Math.round(
+      100 - (totalInterfaces > 0 ? bloatedInterfaces / totalInterfaces * 80 : 0)
+    )
+  );
+  const observabilityScore = Math.max(
+    0,
+    Math.round(
+      100 - (totalFunctions > 0 ? externalStateMutations / totalFunctions * 100 : 0)
+    )
   );
-  const bloatedRatio = totalInterfaces > 0 ? bloatedInterfaces / totalInterfaces : 0;
-  const interfaceFocusScore = Math.max(0, Math.round(100 - bloatedRatio * 80));
-  const mutationRatio = totalFunctions > 0 ? externalStateMutations / totalFunctions : 0;
-  const observabilityScore = Math.max(0, Math.round(100 - mutationRatio * 100));
   const frameworkWeight = hasTestFramework ? 1 : 0.8;
   const rawScore = (testCoverageRatio * 0.3 + purityScore * 0.25 + dependencyInjectionScore * 0.2 + interfaceFocusScore * 0.1 + observabilityScore * 0.15) * frameworkWeight;
   const score = Math.max(0, Math.min(100, Math.round(rawScore)));
@@ -2125,32 +2028,28 @@ function calculateTestabilityIndex(params) {
   else if (rawCoverageRatio > 0) aiChangeSafetyRating = "high-risk";
   else aiChangeSafetyRating = "blind-risk";
   const recommendations = [];
-  if (!hasTestFramework) {
+  if (!hasTestFramework)
     recommendations.push(
       "Add a testing framework (Jest, Vitest, pytest) \u2014 AI changes cannot be verified without tests"
     );
-  }
   if (rawCoverageRatio < 0.3) {
     const neededTests = Math.round(sourceFiles * 0.3 - testFiles);
     recommendations.push(
       `Add ~${neededTests} test files to reach 30% coverage ratio \u2014 minimum for safe AI assistance`
     );
   }
-  if (purityScore < 50) {
+  if (purityScore < 50)
     recommendations.push(
       "Extract pure functions from side-effectful code \u2014 pure functions are trivially AI-testable"
     );
-  }
-  if (dependencyInjectionScore < 50 && totalClasses > 0) {
+  if (dependencyInjectionScore < 50 && totalClasses > 0)
     recommendations.push(
       "Adopt dependency injection \u2014 makes classes mockable and AI-generated code verifiable"
     );
-  }
-  if (externalStateMutations > totalFunctions * 0.3) {
+  if (externalStateMutations > totalFunctions * 0.3)
     recommendations.push(
       "Reduce direct state mutations \u2014 return values instead to improve observability"
     );
-  }
   return {
     score,
     rating,
@@ -2165,6 +2064,8 @@ function calculateTestabilityIndex(params) {
     recommendations
   };
 }
+
+// src/metrics/doc-drift.ts
 function calculateDocDrift(params) {
   const {
     uncommentedExports,
@@ -2187,21 +2088,18 @@ function calculateDocDrift(params) {
   else if (finalScore < 85) rating = "high";
   else rating = "severe";
   const recommendations = [];
-  if (outdatedComments > 0) {
+  if (outdatedComments > 0)
     recommendations.push(
       `Update or remove ${outdatedComments} outdated comments that contradict the code.`
     );
-  }
-  if (uncommentedRatio > 0.3) {
+  if (uncommentedRatio > 0.3)
     recommendations.push(
       `Add JSDoc to ${uncommentedExports} uncommented exports.`
     );
-  }
-  if (undocumentedComplexity > 0) {
+  if (undocumentedComplexity > 0)
     recommendations.push(
       `Explain the business logic for ${undocumentedComplexity} highly complex functions.`
     );
-  }
   return {
     score: finalScore,
     rating,
@@ -2213,6 +2111,8 @@ function calculateDocDrift(params) {
     recommendations
   };
 }
+
+// src/metrics/dependency-health.ts
 function calculateDependencyHealth(params) {
   const {
     totalPackages,
@@ -2225,8 +2125,12 @@ function calculateDependencyHealth(params) {
   const outdatedScore = Math.max(0, 100 - outdatedRatio * 200);
   const deprecatedScore = Math.max(0, 100 - deprecatedRatio * 500);
   const skewScore = Math.max(0, 100 - trainingCutoffSkew * 100);
-  const rawScore = outdatedScore * 0.3 + deprecatedScore * 0.4 + skewScore * 0.3;
-  const score = Math.round(Math.min(100, Math.max(0, rawScore)));
+  const score = Math.round(
+    Math.min(
+      100,
+      Math.max(0, outdatedScore * 0.3 + deprecatedScore * 0.4 + skewScore * 0.3)
+    )
+  );
   let rating;
   if (score >= 85) rating = "excellent";
   else if (score >= 70) rating = "good";
@@ -2241,33 +2145,22 @@ function calculateDependencyHealth(params) {
   else if (trainingCutoffSkew < 0.8) aiKnowledgeConfidence = "low";
   else aiKnowledgeConfidence = "blind";
   const recommendations = [];
-  if (deprecatedPackages > 0) {
-    recommendations.push(
-      `Replace ${deprecatedPackages} deprecated packages, as AI will struggle to find modern solutions.`
-    );
-  }
-  if (outdatedRatio > 0.2) {
-    recommendations.push(
-      `Update ${outdatedPackages} outdated packages to keep APIs aligned with AI training data.`
-    );
-  }
-  if (trainingCutoffSkew > 0.5) {
-    recommendations.push(
-      "High training cutoff skew detected. AI may hallucinate APIs that were introduced recently."
-    );
-  }
+  if (deprecatedPackages > 0)
+    recommendations.push(`Replace ${deprecatedPackages} deprecated packages.`);
+  if (outdatedRatio > 0.2)
+    recommendations.push(`Update ${outdatedPackages} outdated packages.`);
+  if (trainingCutoffSkew > 0.5)
+    recommendations.push("High training cutoff skew detected.");
   return {
     score,
     rating,
-    dimensions: {
-      outdatedPackages,
-      deprecatedPackages,
-      trainingCutoffSkew
-    },
+    dimensions: { outdatedPackages, deprecatedPackages, trainingCutoffSkew },
     aiKnowledgeConfidence,
     recommendations
   };
 }
+
+// src/metrics/change-amplification.ts
 function calculateChangeAmplification(params) {
   const { files } = params;
   if (files.length === 0) {
@@ -2280,15 +2173,16 @@ function calculateChangeAmplification(params) {
       recommendations: []
     };
   }
-  const hotspots = files.map((f) => {
-    const amplificationFactor = f.fanOut + f.fanIn * 0.5;
-    return { ...f, amplificationFactor };
-  }).sort((a, b) => b.amplificationFactor - a.amplificationFactor);
+  const hotspots = files.map((f) => ({ ...f, amplificationFactor: f.fanOut + f.fanIn * 0.5 })).sort((a, b) => b.amplificationFactor - a.amplificationFactor);
   const maxAmplification = hotspots[0].amplificationFactor;
   const avgAmplification = hotspots.reduce((sum, h) => sum + h.amplificationFactor, 0) / hotspots.length;
-  let score = 100 - avgAmplification * 5;
-  if (maxAmplification > 20) score -= maxAmplification - 20;
-  score = Math.max(0, Math.min(100, score));
+  let score = Math.max(
+    0,
+    Math.min(
+      100,
+      100 - avgAmplification * 5 - (maxAmplification > 20 ? maxAmplification - 20 : 0)
+    )
+  );
   let rating = "isolated";
   if (score < 40) rating = "explosive";
   else if (score < 70) rating = "amplified";
@@ -2296,12 +2190,12 @@ function calculateChangeAmplification(params) {
   const recommendations = [];
   if (score < 70 && hotspots.length > 0) {
     recommendations.push(
-      `Refactor top hotspot '${hotspots[0].file}' to reduce coupling (fan-out: ${hotspots[0].fanOut}, fan-in: ${hotspots[0].fanIn}).`
+      `Refactor top hotspot '${hotspots[0].file}' to reduce coupling.`
     );
   }
   if (maxAmplification > 30) {
     recommendations.push(
-      `Break down key bottlenecks with amplification factor > 30.`
+      "Break down key bottlenecks with amplification factor > 30."
     );
   }
   return {
@@ -2313,6 +2207,61 @@ function calculateChangeAmplification(params) {
     recommendations
   };
 }
+
+// src/future-proof-metrics.ts
+function calculateFutureProofScore(params) {
+  const loadScore = 100 - params.cognitiveLoad.score;
+  const entropyScore = 100 - params.patternEntropy.entropy * 100;
+  const cohesionScore = params.conceptCohesion.score * 100;
+  const overall = Math.round(
+    loadScore * 0.4 + entropyScore * 0.3 + cohesionScore * 0.3
+  );
+  const factors = [
+    {
+      name: "Cognitive Load",
+      impact: Math.round(loadScore - 50),
+      description: params.cognitiveLoad.rating
+    },
+    {
+      name: "Pattern Entropy",
+      impact: Math.round(entropyScore - 50),
+      description: params.patternEntropy.rating
+    },
+    {
+      name: "Concept Cohesion",
+      impact: Math.round(cohesionScore - 50),
+      description: params.conceptCohesion.rating
+    }
+  ];
+  const recommendations = [];
+  for (const rec of params.patternEntropy.recommendations) {
+    recommendations.push({
+      action: rec,
+      estimatedImpact: 5,
+      priority: "medium"
+    });
+  }
+  if (params.conceptCohesion.rating === "poor") {
+    recommendations.push({
+      action: "Improve concept cohesion by grouping related exports",
+      estimatedImpact: 8,
+      priority: "high"
+    });
+  }
+  const semanticDistanceAvg = params.semanticDistances?.length ? params.semanticDistances.reduce((s, d) => s + d.distance, 0) / params.semanticDistances.length : 0;
+  return {
+    toolName: "future-proof",
+    score: overall,
+    rawMetrics: {
+      cognitiveLoadScore: params.cognitiveLoad.score,
+      entropyScore: params.patternEntropy.entropy,
+      cohesionScore: params.conceptCohesion.score,
+      semanticDistanceAvg
+    },
+    factors,
+    recommendations
+  };
+}
 function calculateExtendedFutureProofScore(params) {
   const loadScore = 100 - params.cognitiveLoad.score;
   const entropyScore = 100 - params.patternEntropy.entropy * 100;
@@ -2321,7 +2270,7 @@ function calculateExtendedFutureProofScore(params) {
   const groundingScore = params.agentGrounding.score;
   const testabilityScore = params.testability.score;
   const docDriftScore = params.docDrift ? 100 - params.docDrift.score : 100;
-  const depsHealthScore = params.dependencyHealth ? params.dependencyHealth.score : 100;
+  const depsHealthScore = params.dependencyHealth?.score ?? 100;
   let totalWeight = 0.8;
   let overall = loadScore * 0.15 + entropyScore * 0.1 + cohesionScore * 0.1 + aiSignalClarityScore * 0.15 + groundingScore * 0.15 + testabilityScore * 0.15;
   if (params.docDrift) {
@@ -2352,7 +2301,7 @@ function calculateExtendedFutureProofScore(params) {
     {
       name: "AI Signal Clarity",
       impact: Math.round(aiSignalClarityScore - 50),
-      description: `${params.aiSignalClarity.rating} risk (${params.aiSignalClarity.score}/100 raw)`
+      description: `${params.aiSignalClarity.rating} risk`
     },
     {
       name: "Agent Grounding",
@@ -2362,60 +2311,25 @@ function calculateExtendedFutureProofScore(params) {
     {
       name: "Testability",
       impact: Math.round(testabilityScore - 50),
-      description: `${params.testability.rating} \u2014 AI changes are ${params.testability.aiChangeSafetyRating}`
+      description: params.testability.rating
     }
   ];
   if (params.docDrift) {
     factors.push({
       name: "Documentation Drift",
       impact: Math.round(docDriftScore - 50),
-      description: `${params.docDrift.rating} risk of AI signal clarity from drift`
+      description: params.docDrift.rating
     });
   }
   if (params.dependencyHealth) {
     factors.push({
       name: "Dependency Health",
       impact: Math.round(depsHealthScore - 50),
-      description: `${params.dependencyHealth.rating} health \u2014 AI knowledge is ${params.dependencyHealth.aiKnowledgeConfidence}`
+      description: params.dependencyHealth.rating
     });
   }
-  const recommendations = [];
-  for (const rec of params.aiSignalClarity.recommendations) {
-    recommendations.push({ action: rec, estimatedImpact: 8, priority: "high" });
-  }
-  for (const rec of params.agentGrounding.recommendations) {
-    recommendations.push({
-      action: rec,
-      estimatedImpact: 6,
-      priority: "medium"
-    });
-  }
-  for (const rec of params.testability.recommendations) {
-    const priority = params.testability.aiChangeSafetyRating === "blind-risk" ? "high" : "medium";
-    recommendations.push({ action: rec, estimatedImpact: 10, priority });
-  }
-  for (const rec of params.patternEntropy.recommendations) {
-    recommendations.push({ action: rec, estimatedImpact: 5, priority: "low" });
-  }
-  if (params.docDrift) {
-    for (const rec of params.docDrift.recommendations) {
-      recommendations.push({
-        action: rec,
-        estimatedImpact: 8,
-        priority: "high"
-      });
-    }
-  }
-  if (params.dependencyHealth) {
-    for (const rec of params.dependencyHealth.recommendations) {
-      recommendations.push({
-        action: rec,
-        estimatedImpact: 7,
-        priority: "medium"
-      });
-    }
-  }
-  const semanticDistanceAvg = params.semanticDistances && params.semanticDistances.length > 0 ? params.semanticDistances.reduce((s, d) => s + d.distance, 0) / params.semanticDistances.length : 0;
+  const recommendations = collectFutureProofRecommendations(params);
+  const semanticDistanceAvg = params.semanticDistances?.length ? params.semanticDistances.reduce((s, d) => s + d.distance, 0) / params.semanticDistances.length : 0;
   return {
     toolName: "future-proof",
     score: overall,
@@ -2591,16 +2505,19 @@ export {
   ParseError,
   ParserFactory,
   PythonParser,
+  SEVERITY_TIME_ESTIMATES,
   SIZE_ADJUSTED_THRESHOLDS,
   TOOL_NAME_MAP,
   TypeScriptParser,
   VAGUE_FILE_NAMES,
   calculateAgentGrounding,
   calculateAiSignalClarity,
+  calculateBusinessROI,
   calculateChangeAmplification,
   calculateCognitiveLoad,
   calculateComprehensionDifficulty,
   calculateConceptCohesion,
+  calculateDebtInterest,
   calculateDependencyHealth,
   calculateDocDrift,
   calculateExtendedFutureProofScore,
@@ -2611,10 +2528,8 @@ export {
   calculateOverallScore,
   calculatePatternEntropy,
   calculateProductivityImpact,
-  calculateRemediationVelocity,
-  calculateScoreTrend,
   calculateSemanticDistance,
-  calculateTechnicalDebtInterest,
+  calculateTechnicalValueChain,
   calculateTestabilityIndex,
   calculateTokenBudget,
   clearHistory,
@@ -2630,7 +2545,6 @@ export {
   formatToolScore,
   generateHTML,
   generateValueChain,
-  getDebtBreakdown,
   getElapsedTime,
   getFileCommitTimestamps,
   getFileExtension,
@@ -2644,6 +2558,9 @@ export {
   getRatingWithContext,
   getRecommendedThreshold,
   getRepoMetadata,
+  getSafetyIcon,
+  getScoreBar,
+  getSeverityColor,
   getSupportedLanguages,
   getToolWeight,
   handleCLIError,
@@ -2663,5 +2580,6 @@ export {
   resolveOutputPath,
   saveScoreEntry,
   scanEntries,
-  scanFiles
+  scanFiles,
+  validateSpokeOutput
 };