@aiready/core 0.9.35 → 0.9.37

package/dist/client.d.mts

@@ -52,6 +52,29 @@ interface CostConfig {
     /** Days per month (default: 30) */
     daysPerMonth: number;
 }
+/**
+ * Token budget metrics (v0.13+)
+ * Technology-agnostic unit economics for AI impact.
+ */
+interface TokenBudget {
+    /** Total tokens required for full task context */
+    totalContextTokens: number;
+    /** Estimated tokens generated in response */
+    estimatedResponseTokens: number;
+    /** Tokens wasted on redundant/duplicated context */
+    wastedTokens: {
+        total: number;
+        bySource: {
+            duplication: number;
+            fragmentation: number;
+            chattiness: number;
+        };
+    };
+    /** Context efficiency ratio (0-1). 1.0 = perfect efficiency. */
+    efficiencyRatio: number;
+    /** Estimated tokens saved if recommendations are followed */
+    potentialRetrievableTokens: number;
+}
 /**
  * Productivity impact estimates
  */
@@ -109,19 +132,52 @@ interface ComprehensionDifficulty {
     /** Interpretation */
     rating: 'trivial' | 'easy' | 'moderate' | 'difficult' | 'expert';
 }
+/**
+/**
+ * Technical Value Chain
+ * Traces a technical issue through its impact on AI and developer outcomes.
+ */
+interface TechnicalValueChain {
+    issueType: string;
+    technicalMetric: string;
+    technicalValue: number;
+    aiImpact: {
+        description: string;
+        scoreImpact: number;
+    };
+    developerImpact: {
+        description: string;
+        productivityLoss: number;
+    };
+    businessOutcome: {
+        directCost: number;
+        opportunityCost: number;
+        riskLevel: 'low' | 'moderate' | 'high' | 'critical';
+    };
+}
 /**
  * Extended report with business metrics
  */
 interface BusinessReport extends Report {
     businessMetrics: {
-        /** Estimated monthly cost impact of AI context waste */
-        estimatedMonthlyCost: number;
+        /** Token-based unit economics (v0.13+) */
+        tokenBudget: TokenBudget;
+        /** @deprecated Use tokenBudget instead. Estimated monthly cost impact of AI context waste */
+        estimatedMonthlyCost: {
+            total: number;
+            range: [number, number];
+            confidence: number;
+        };
+        /** Opportunity cost of project delay due to technical debt */
+        opportunityCost: number;
         /** Estimated developer hours to address issues */
         estimatedDeveloperHours: number;
         /** Predicted AI suggestion acceptance rate */
         aiAcceptanceRate: number;
         /** Comprehension difficulty assessment */
         comprehensionDifficulty: ComprehensionDifficulty;
+        /** Traces for specific critical issues */
+        valueChains?: TechnicalValueChain[];
         /** Timestamp for trend tracking */
         period?: string;
     };
@@ -252,6 +308,8 @@ interface GraphMetadata {
     majorIssues: number;
     minorIssues: number;
     infoIssues: number;
+    /** AI token budget unit economics (v0.13+) */
+    tokenBudget?: TokenBudget;
 }
 /**
  * Complete graph data structure for visualization
@@ -446,6 +504,8 @@ interface ToolScoringOutput {
     toolName: string;
     /** Normalized 0-100 score for this tool */
     score: number;
+    /** AI token budget unit economics (v0.13+) */
+    tokenBudget?: TokenBudget;
     /** Raw metrics used to calculate the score */
     rawMetrics: Record<string, any>;
     /** Factors that influenced the score */
@@ -615,4 +675,4 @@ declare function formatToolScore(output: ToolScoringOutput): string;
  */
 declare function generateHTML(graph: GraphData): string;
 
-export { type AIReadyConfig, type AcceptancePrediction, type AnalysisResult, type BusinessReport, CONTEXT_TIER_THRESHOLDS, type CommonASTNode, type ComprehensionDifficulty, type CostConfig, DEFAULT_TOOL_WEIGHTS, type ExportInfo, type GraphData, type GraphEdge, type GraphIssueSeverity, type GraphMetadata, type GraphNode, type ImportInfo, type Issue, type IssueType, LANGUAGE_EXTENSIONS, Language, type LanguageConfig, type LanguageParser, type Location, type Metrics, type ModelContextTier, type NamingConvention, ParseError, type ParseResult, type ParseStatistics, type ProductivityImpact, type Report, SIZE_ADJUSTED_THRESHOLDS, type ScanOptions, type ScoringConfig, type ScoringResult, type SourceLocation, type SourceRange, TOOL_NAME_MAP, type ToolScoringOutput, calculateOverallScore, formatScore, formatToolScore, generateHTML, getProjectSizeTier, getRating, getRatingDisplay, getRatingWithContext, getRecommendedThreshold, getToolWeight, normalizeToolName, parseWeightString };
+export { type AIReadyConfig, type AcceptancePrediction, type AnalysisResult, type BusinessReport, CONTEXT_TIER_THRESHOLDS, type CommonASTNode, type ComprehensionDifficulty, type CostConfig, DEFAULT_TOOL_WEIGHTS, type ExportInfo, type GraphData, type GraphEdge, type GraphIssueSeverity, type GraphMetadata, type GraphNode, type ImportInfo, type Issue, type IssueType, LANGUAGE_EXTENSIONS, Language, type LanguageConfig, type LanguageParser, type Location, type Metrics, type ModelContextTier, type NamingConvention, ParseError, type ParseResult, type ParseStatistics, type ProductivityImpact, type Report, SIZE_ADJUSTED_THRESHOLDS, type ScanOptions, type ScoringConfig, type ScoringResult, type SourceLocation, type SourceRange, TOOL_NAME_MAP, type TechnicalValueChain, type TokenBudget, type ToolScoringOutput, calculateOverallScore, formatScore, formatToolScore, generateHTML, getProjectSizeTier, getRating, getRatingDisplay, getRatingWithContext, getRecommendedThreshold, getToolWeight, normalizeToolName, parseWeightString };

package/dist/client.d.ts

@@ -52,6 +52,29 @@ interface CostConfig {
     /** Days per month (default: 30) */
     daysPerMonth: number;
 }
+/**
+ * Token budget metrics (v0.13+)
+ * Technology-agnostic unit economics for AI impact.
+ */
+interface TokenBudget {
+    /** Total tokens required for full task context */
+    totalContextTokens: number;
+    /** Estimated tokens generated in response */
+    estimatedResponseTokens: number;
+    /** Tokens wasted on redundant/duplicated context */
+    wastedTokens: {
+        total: number;
+        bySource: {
+            duplication: number;
+            fragmentation: number;
+            chattiness: number;
+        };
+    };
+    /** Context efficiency ratio (0-1). 1.0 = perfect efficiency. */
+    efficiencyRatio: number;
+    /** Estimated tokens saved if recommendations are followed */
+    potentialRetrievableTokens: number;
+}
 /**
  * Productivity impact estimates
  */
@@ -109,19 +132,52 @@ interface ComprehensionDifficulty {
     /** Interpretation */
     rating: 'trivial' | 'easy' | 'moderate' | 'difficult' | 'expert';
 }
+/**
+/**
+ * Technical Value Chain
+ * Traces a technical issue through its impact on AI and developer outcomes.
+ */
+interface TechnicalValueChain {
+    issueType: string;
+    technicalMetric: string;
+    technicalValue: number;
+    aiImpact: {
+        description: string;
+        scoreImpact: number;
+    };
+    developerImpact: {
+        description: string;
+        productivityLoss: number;
+    };
+    businessOutcome: {
+        directCost: number;
+        opportunityCost: number;
+        riskLevel: 'low' | 'moderate' | 'high' | 'critical';
+    };
+}
 /**
  * Extended report with business metrics
  */
 interface BusinessReport extends Report {
     businessMetrics: {
-        /** Estimated monthly cost impact of AI context waste */
-        estimatedMonthlyCost: number;
+        /** Token-based unit economics (v0.13+) */
+        tokenBudget: TokenBudget;
+        /** @deprecated Use tokenBudget instead. Estimated monthly cost impact of AI context waste */
+        estimatedMonthlyCost: {
+            total: number;
+            range: [number, number];
+            confidence: number;
+        };
+        /** Opportunity cost of project delay due to technical debt */
+        opportunityCost: number;
         /** Estimated developer hours to address issues */
         estimatedDeveloperHours: number;
         /** Predicted AI suggestion acceptance rate */
         aiAcceptanceRate: number;
         /** Comprehension difficulty assessment */
         comprehensionDifficulty: ComprehensionDifficulty;
+        /** Traces for specific critical issues */
+        valueChains?: TechnicalValueChain[];
         /** Timestamp for trend tracking */
         period?: string;
     };
@@ -252,6 +308,8 @@ interface GraphMetadata {
     majorIssues: number;
     minorIssues: number;
     infoIssues: number;
+    /** AI token budget unit economics (v0.13+) */
+    tokenBudget?: TokenBudget;
 }
 /**
  * Complete graph data structure for visualization
@@ -446,6 +504,8 @@ interface ToolScoringOutput {
     toolName: string;
     /** Normalized 0-100 score for this tool */
     score: number;
+    /** AI token budget unit economics (v0.13+) */
+    tokenBudget?: TokenBudget;
     /** Raw metrics used to calculate the score */
     rawMetrics: Record<string, any>;
     /** Factors that influenced the score */
@@ -615,4 +675,4 @@ declare function formatToolScore(output: ToolScoringOutput): string;
  */
 declare function generateHTML(graph: GraphData): string;
 
-export { type AIReadyConfig, type AcceptancePrediction, type AnalysisResult, type BusinessReport, CONTEXT_TIER_THRESHOLDS, type CommonASTNode, type ComprehensionDifficulty, type CostConfig, DEFAULT_TOOL_WEIGHTS, type ExportInfo, type GraphData, type GraphEdge, type GraphIssueSeverity, type GraphMetadata, type GraphNode, type ImportInfo, type Issue, type IssueType, LANGUAGE_EXTENSIONS, Language, type LanguageConfig, type LanguageParser, type Location, type Metrics, type ModelContextTier, type NamingConvention, ParseError, type ParseResult, type ParseStatistics, type ProductivityImpact, type Report, SIZE_ADJUSTED_THRESHOLDS, type ScanOptions, type ScoringConfig, type ScoringResult, type SourceLocation, type SourceRange, TOOL_NAME_MAP, type ToolScoringOutput, calculateOverallScore, formatScore, formatToolScore, generateHTML, getProjectSizeTier, getRating, getRatingDisplay, getRatingWithContext, getRecommendedThreshold, getToolWeight, normalizeToolName, parseWeightString };
+export { type AIReadyConfig, type AcceptancePrediction, type AnalysisResult, type BusinessReport, CONTEXT_TIER_THRESHOLDS, type CommonASTNode, type ComprehensionDifficulty, type CostConfig, DEFAULT_TOOL_WEIGHTS, type ExportInfo, type GraphData, type GraphEdge, type GraphIssueSeverity, type GraphMetadata, type GraphNode, type ImportInfo, type Issue, type IssueType, LANGUAGE_EXTENSIONS, Language, type LanguageConfig, type LanguageParser, type Location, type Metrics, type ModelContextTier, type NamingConvention, ParseError, type ParseResult, type ParseStatistics, type ProductivityImpact, type Report, SIZE_ADJUSTED_THRESHOLDS, type ScanOptions, type ScoringConfig, type ScoringResult, type SourceLocation, type SourceRange, TOOL_NAME_MAP, type TechnicalValueChain, type TokenBudget, type ToolScoringOutput, calculateOverallScore, formatScore, formatToolScore, generateHTML, getProjectSizeTier, getRating, getRatingDisplay, getRatingWithContext, getRecommendedThreshold, getToolWeight, normalizeToolName, parseWeightString };

package/dist/index.d.mts

@@ -1,4 +1,4 @@
-import { ScanOptions, AIReadyConfig, CostConfig, ModelContextTier, ComprehensionDifficulty, ProductivityImpact, ToolScoringOutput, AcceptancePrediction, LanguageParser, Language, ParseResult, NamingConvention } from './client.mjs';
+import { ScanOptions, AIReadyConfig, CostConfig, ModelContextTier, ComprehensionDifficulty, ProductivityImpact, TokenBudget, TechnicalValueChain, ToolScoringOutput, AcceptancePrediction, LanguageParser, Language, ParseResult, NamingConvention } from './client.mjs';
 export { AnalysisResult, BusinessReport, CONTEXT_TIER_THRESHOLDS, CommonASTNode, DEFAULT_TOOL_WEIGHTS, ExportInfo, GraphData, GraphEdge, GraphIssueSeverity, GraphMetadata, GraphNode, ImportInfo, Issue, IssueType, LANGUAGE_EXTENSIONS, LanguageConfig, Location, Metrics, ParseError, ParseStatistics, Report, SIZE_ADJUSTED_THRESHOLDS, ScoringConfig, ScoringResult, SourceLocation, SourceRange, TOOL_NAME_MAP, calculateOverallScore, formatScore, formatToolScore, generateHTML, getProjectSizeTier, getRating, getRatingDisplay, getRatingWithContext, getRecommendedThreshold, getToolWeight, normalizeToolName, parseWeightString } from './client.mjs';
 
 declare const DEFAULT_EXCLUDE: string[];
@@ -148,7 +148,7 @@ interface ModelPricingPreset {
 }
 declare const MODEL_PRICING_PRESETS: Record<string, ModelPricingPreset>;
 /**
- * Get a model pricing preset by ID, with fallback to gpt-4o
+ * Get a model pricing preset by ID, with fallback to claude-4.6 (2026 default)
  */
 declare function getModelPreset(modelId: string): ModelPricingPreset;
 /**
@@ -237,11 +237,38 @@ interface DebtBreakdown {
  */
 declare const DEFAULT_COST_CONFIG: CostConfig;
 /**
- * Calculate estimated monthly cost of AI context waste
+ * @deprecated Since v0.13. Use calculateTokenBudget() + estimateCostFromBudget() instead.
+ * Dollar costs are volatile based on technology; token budgets are stable unit economics.
  *
- * Formula: (tokenWaste / 1000) × pricePer1K × queriesPerDev × devCount × days
+ * Calculate estimated monthly cost of AI context waste with confidence intervals.
  */
-declare function calculateMonthlyCost(tokenWaste: number, config?: Partial<CostConfig>): number;
+declare function calculateMonthlyCost(tokenWaste: number, config?: Partial<CostConfig>): {
+    total: number;
+    range: [number, number];
+    confidence: number;
+};
+/**
+ * Calculate token budget and unit economics for AI interactions.
+ * Technology-agnostic metric that remains valid across model generations.
+ */
+declare function calculateTokenBudget(params: {
+    totalContextTokens: number;
+    estimatedResponseTokens?: number;
+    wastedTokens: {
+        duplication: number;
+        fragmentation: number;
+        chattiness: number;
+    };
+}): TokenBudget;
+/**
+ * Estimate dollar cost from a token budget using model presets.
+ * Note: Use this for presentation only. Token budgets are the primary metric.
+ */
+declare function estimateCostFromBudget(budget: TokenBudget, model: ModelPricingPreset, config?: Partial<CostConfig>): {
+    total: number;
+    range: [number, number];
+    confidence: number;
+};
 /**
  * Calculate productivity impact from issues
  */
@@ -253,9 +280,10 @@ declare function calculateProductivityImpact(issues: {
  *
  * Calibration notes (v0.12):
  * - GitHub Copilot reports ~30% industry average acceptance rate (2023 blog)
+ * - Research (Ziegler et al., 2022) indicates acceptance rate is a proxy for productivity
  * - Internal teams with high-consistency codebases report 40-55%
  * - Teams with semantic duplication report 20-25% (AI suggests wrong variant)
- * - Context efficiency is the strongest single predictor
+ * - Context efficiency is the strongest single predictor (empirical correlation: r=0.68)
  *
  * Confidence levels:
  * - 3 tools: 0.75 (triangulated estimate)
@@ -325,6 +353,14 @@ declare function calculateTechnicalDebtInterest(params: {
  * Get debt breakdown by category
  */
 declare function getDebtBreakdown(patternCost: number, contextCost: number, consistencyCost: number): DebtBreakdown[];
+/**
+ * Generate a Technical Value Chain for a specific issue
+ */
+declare function generateValueChain(params: {
+    issueType: string;
+    count: number;
+    severity: 'critical' | 'major' | 'minor';
+}): TechnicalValueChain;
 
 /**
  * Parser Factory - Manages language-specific parsers
@@ -843,5 +879,14 @@ declare function getFileCommitTimestamps(file: string): Record<number, number>;
  * Get the latest commit timestamp for a line range
  */
 declare function getLineRangeLastModifiedCached(lineStamps: Record<number, number>, startLine: number, endLine: number): number;
+/**
+ * Get repository metadata (URL, branch, commit, author)
+ */
+declare function getRepoMetadata(directory: string): {
+    url?: string;
+    branch?: string;
+    commit?: string;
+    author?: string;
+};
 
-export { AIReadyConfig, type ASTNode, AcceptancePrediction, type AgentGroundingScore, type AiSignalClarity, type AiSignalClaritySignal, type CLIOptions, type ChangeAmplificationScore, type CognitiveLoad, ComprehensionDifficulty, type ConceptCohesion, CostConfig, DEFAULT_COST_CONFIG, DEFAULT_EXCLUDE, type DebtBreakdown, type DependencyHealthScore, type DocDriftRisk, type ExportWithImports, type FileImport, type FileWithDomain, type KnowledgeConcentrationRisk, Language, LanguageParser, type LoadFactor, MODEL_PRICING_PRESETS, ModelContextTier, type ModelPricingPreset, NamingConvention, ParseResult, ParserFactory, type PatternEntropy, ProductivityImpact, PythonParser, type RemediationVelocity, ScanOptions, type ScoreHistoryEntry, type ScoreTrend, type SemanticDistance, type TechnicalDebtInterest, type TestabilityIndex, ToolScoringOutput, TypeScriptParser, VAGUE_FILE_NAMES, calculateAgentGrounding, calculateAiSignalClarity, calculateChangeAmplification, calculateCognitiveLoad, calculateComprehensionDifficulty, calculateConceptCohesion, calculateDependencyHealth, calculateDocDrift, calculateExtendedFutureProofScore, calculateFutureProofScore, calculateImportSimilarity, calculateKnowledgeConcentration, calculateMonthlyCost, calculatePatternEntropy, calculateProductivityImpact, calculateRemediationVelocity, calculateScoreTrend, calculateSemanticDistance, calculateTechnicalDebtInterest, calculateTestabilityIndex, clearHistory, estimateTokens, exportHistory, extractFunctions, extractImports, formatAcceptanceRate, formatCost, formatHours, getDebtBreakdown, getElapsedTime, getFileCommitTimestamps, getFileExtension, getHistorySummary, getLineRangeLastModifiedCached, getModelPreset, getParser, getSupportedLanguages, handleCLIError, handleJSONOutput, isFileSupported, isSourceFile, loadConfig, loadMergedConfig, loadScoreHistory, mergeConfigWithDefaults, parseCode, parseFileExports, predictAcceptanceRate, readFileContent, resolveOutputPath, saveScoreEntry, scanEntries, scanFiles };
+export { AIReadyConfig, type ASTNode, AcceptancePrediction, type AgentGroundingScore, type AiSignalClarity, type AiSignalClaritySignal, type CLIOptions, type ChangeAmplificationScore, type CognitiveLoad, ComprehensionDifficulty, type ConceptCohesion, CostConfig, DEFAULT_COST_CONFIG, DEFAULT_EXCLUDE, type DebtBreakdown, type DependencyHealthScore, type DocDriftRisk, type ExportWithImports, type FileImport, type FileWithDomain, type KnowledgeConcentrationRisk, Language, LanguageParser, type LoadFactor, MODEL_PRICING_PRESETS, ModelContextTier, type ModelPricingPreset, NamingConvention, ParseResult, ParserFactory, type PatternEntropy, ProductivityImpact, PythonParser, type RemediationVelocity, ScanOptions, type ScoreHistoryEntry, type ScoreTrend, type SemanticDistance, type TechnicalDebtInterest, TechnicalValueChain, type TestabilityIndex, TokenBudget, ToolScoringOutput, TypeScriptParser, VAGUE_FILE_NAMES, calculateAgentGrounding, calculateAiSignalClarity, calculateChangeAmplification, calculateCognitiveLoad, calculateComprehensionDifficulty, calculateConceptCohesion, calculateDependencyHealth, calculateDocDrift, calculateExtendedFutureProofScore, calculateFutureProofScore, calculateImportSimilarity, calculateKnowledgeConcentration, calculateMonthlyCost, calculatePatternEntropy, calculateProductivityImpact, calculateRemediationVelocity, calculateScoreTrend, calculateSemanticDistance, calculateTechnicalDebtInterest, calculateTestabilityIndex, calculateTokenBudget, clearHistory, estimateCostFromBudget, estimateTokens, exportHistory, extractFunctions, extractImports, formatAcceptanceRate, formatCost, formatHours, generateValueChain, getDebtBreakdown, getElapsedTime, getFileCommitTimestamps, getFileExtension, getHistorySummary, getLineRangeLastModifiedCached, getModelPreset, getParser, getRepoMetadata, getSupportedLanguages, handleCLIError, handleJSONOutput, isFileSupported, isSourceFile, loadConfig, loadMergedConfig, loadScoreHistory, mergeConfigWithDefaults, parseCode, parseFileExports, predictAcceptanceRate, readFileContent, resolveOutputPath, saveScoreEntry, scanEntries, scanFiles };

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { ScanOptions, AIReadyConfig, CostConfig, ModelContextTier, ComprehensionDifficulty, ProductivityImpact, ToolScoringOutput, AcceptancePrediction, LanguageParser, Language, ParseResult, NamingConvention } from './client.js';
+import { ScanOptions, AIReadyConfig, CostConfig, ModelContextTier, ComprehensionDifficulty, ProductivityImpact, TokenBudget, TechnicalValueChain, ToolScoringOutput, AcceptancePrediction, LanguageParser, Language, ParseResult, NamingConvention } from './client.js';
 export { AnalysisResult, BusinessReport, CONTEXT_TIER_THRESHOLDS, CommonASTNode, DEFAULT_TOOL_WEIGHTS, ExportInfo, GraphData, GraphEdge, GraphIssueSeverity, GraphMetadata, GraphNode, ImportInfo, Issue, IssueType, LANGUAGE_EXTENSIONS, LanguageConfig, Location, Metrics, ParseError, ParseStatistics, Report, SIZE_ADJUSTED_THRESHOLDS, ScoringConfig, ScoringResult, SourceLocation, SourceRange, TOOL_NAME_MAP, calculateOverallScore, formatScore, formatToolScore, generateHTML, getProjectSizeTier, getRating, getRatingDisplay, getRatingWithContext, getRecommendedThreshold, getToolWeight, normalizeToolName, parseWeightString } from './client.js';
 
 declare const DEFAULT_EXCLUDE: string[];
@@ -148,7 +148,7 @@ interface ModelPricingPreset {
 }
 declare const MODEL_PRICING_PRESETS: Record<string, ModelPricingPreset>;
 /**
- * Get a model pricing preset by ID, with fallback to gpt-4o
+ * Get a model pricing preset by ID, with fallback to claude-4.6 (2026 default)
  */
 declare function getModelPreset(modelId: string): ModelPricingPreset;
 /**
@@ -237,11 +237,38 @@ interface DebtBreakdown {
  */
 declare const DEFAULT_COST_CONFIG: CostConfig;
 /**
- * Calculate estimated monthly cost of AI context waste
+ * @deprecated Since v0.13. Use calculateTokenBudget() + estimateCostFromBudget() instead.
+ * Dollar costs are volatile based on technology; token budgets are stable unit economics.
  *
- * Formula: (tokenWaste / 1000) × pricePer1K × queriesPerDev × devCount × days
+ * Calculate estimated monthly cost of AI context waste with confidence intervals.
  */
-declare function calculateMonthlyCost(tokenWaste: number, config?: Partial<CostConfig>): number;
+declare function calculateMonthlyCost(tokenWaste: number, config?: Partial<CostConfig>): {
+    total: number;
+    range: [number, number];
+    confidence: number;
+};
+/**
+ * Calculate token budget and unit economics for AI interactions.
+ * Technology-agnostic metric that remains valid across model generations.
+ */
+declare function calculateTokenBudget(params: {
+    totalContextTokens: number;
+    estimatedResponseTokens?: number;
+    wastedTokens: {
+        duplication: number;
+        fragmentation: number;
+        chattiness: number;
+    };
+}): TokenBudget;
+/**
+ * Estimate dollar cost from a token budget using model presets.
+ * Note: Use this for presentation only. Token budgets are the primary metric.
+ */
+declare function estimateCostFromBudget(budget: TokenBudget, model: ModelPricingPreset, config?: Partial<CostConfig>): {
+    total: number;
+    range: [number, number];
+    confidence: number;
+};
 /**
  * Calculate productivity impact from issues
  */
@@ -253,9 +280,10 @@ declare function calculateProductivityImpact(issues: {
  *
  * Calibration notes (v0.12):
  * - GitHub Copilot reports ~30% industry average acceptance rate (2023 blog)
+ * - Research (Ziegler et al., 2022) indicates acceptance rate is a proxy for productivity
  * - Internal teams with high-consistency codebases report 40-55%
  * - Teams with semantic duplication report 20-25% (AI suggests wrong variant)
- * - Context efficiency is the strongest single predictor
+ * - Context efficiency is the strongest single predictor (empirical correlation: r=0.68)
  *
  * Confidence levels:
  * - 3 tools: 0.75 (triangulated estimate)
@@ -325,6 +353,14 @@ declare function calculateTechnicalDebtInterest(params: {
  * Get debt breakdown by category
  */
 declare function getDebtBreakdown(patternCost: number, contextCost: number, consistencyCost: number): DebtBreakdown[];
+/**
+ * Generate a Technical Value Chain for a specific issue
+ */
+declare function generateValueChain(params: {
+    issueType: string;
+    count: number;
+    severity: 'critical' | 'major' | 'minor';
+}): TechnicalValueChain;
 
 /**
  * Parser Factory - Manages language-specific parsers
@@ -843,5 +879,14 @@ declare function getFileCommitTimestamps(file: string): Record<number, number>;
  * Get the latest commit timestamp for a line range
  */
 declare function getLineRangeLastModifiedCached(lineStamps: Record<number, number>, startLine: number, endLine: number): number;
+/**
+ * Get repository metadata (URL, branch, commit, author)
+ */
+declare function getRepoMetadata(directory: string): {
+    url?: string;
+    branch?: string;
+    commit?: string;
+    author?: string;
+};
 
-export { AIReadyConfig, type ASTNode, AcceptancePrediction, type AgentGroundingScore, type AiSignalClarity, type AiSignalClaritySignal, type CLIOptions, type ChangeAmplificationScore, type CognitiveLoad, ComprehensionDifficulty, type ConceptCohesion, CostConfig, DEFAULT_COST_CONFIG, DEFAULT_EXCLUDE, type DebtBreakdown, type DependencyHealthScore, type DocDriftRisk, type ExportWithImports, type FileImport, type FileWithDomain, type KnowledgeConcentrationRisk, Language, LanguageParser, type LoadFactor, MODEL_PRICING_PRESETS, ModelContextTier, type ModelPricingPreset, NamingConvention, ParseResult, ParserFactory, type PatternEntropy, ProductivityImpact, PythonParser, type RemediationVelocity, ScanOptions, type ScoreHistoryEntry, type ScoreTrend, type SemanticDistance, type TechnicalDebtInterest, type TestabilityIndex, ToolScoringOutput, TypeScriptParser, VAGUE_FILE_NAMES, calculateAgentGrounding, calculateAiSignalClarity, calculateChangeAmplification, calculateCognitiveLoad, calculateComprehensionDifficulty, calculateConceptCohesion, calculateDependencyHealth, calculateDocDrift, calculateExtendedFutureProofScore, calculateFutureProofScore, calculateImportSimilarity, calculateKnowledgeConcentration, calculateMonthlyCost, calculatePatternEntropy, calculateProductivityImpact, calculateRemediationVelocity, calculateScoreTrend, calculateSemanticDistance, calculateTechnicalDebtInterest, calculateTestabilityIndex, clearHistory, estimateTokens, exportHistory, extractFunctions, extractImports, formatAcceptanceRate, formatCost, formatHours, getDebtBreakdown, getElapsedTime, getFileCommitTimestamps, getFileExtension, getHistorySummary, getLineRangeLastModifiedCached, getModelPreset, getParser, getSupportedLanguages, handleCLIError, handleJSONOutput, isFileSupported, isSourceFile, loadConfig, loadMergedConfig, loadScoreHistory, mergeConfigWithDefaults, parseCode, parseFileExports, predictAcceptanceRate, readFileContent, resolveOutputPath, saveScoreEntry, scanEntries, scanFiles };
+export { AIReadyConfig, type ASTNode, AcceptancePrediction, type AgentGroundingScore, type AiSignalClarity, type AiSignalClaritySignal, type CLIOptions, type ChangeAmplificationScore, type CognitiveLoad, ComprehensionDifficulty, type ConceptCohesion, CostConfig, DEFAULT_COST_CONFIG, DEFAULT_EXCLUDE, type DebtBreakdown, type DependencyHealthScore, type DocDriftRisk, type ExportWithImports, type FileImport, type FileWithDomain, type KnowledgeConcentrationRisk, Language, LanguageParser, type LoadFactor, MODEL_PRICING_PRESETS, ModelContextTier, type ModelPricingPreset, NamingConvention, ParseResult, ParserFactory, type PatternEntropy, ProductivityImpact, PythonParser, type RemediationVelocity, ScanOptions, type ScoreHistoryEntry, type ScoreTrend, type SemanticDistance, type TechnicalDebtInterest, TechnicalValueChain, type TestabilityIndex, TokenBudget, ToolScoringOutput, TypeScriptParser, VAGUE_FILE_NAMES, calculateAgentGrounding, calculateAiSignalClarity, calculateChangeAmplification, calculateCognitiveLoad, calculateComprehensionDifficulty, calculateConceptCohesion, calculateDependencyHealth, calculateDocDrift, calculateExtendedFutureProofScore, calculateFutureProofScore, calculateImportSimilarity, calculateKnowledgeConcentration, calculateMonthlyCost, calculatePatternEntropy, calculateProductivityImpact, calculateRemediationVelocity, calculateScoreTrend, calculateSemanticDistance, calculateTechnicalDebtInterest, calculateTestabilityIndex, calculateTokenBudget, clearHistory, estimateCostFromBudget, estimateTokens, exportHistory, extractFunctions, extractImports, formatAcceptanceRate, formatCost, formatHours, generateValueChain, getDebtBreakdown, getElapsedTime, getFileCommitTimestamps, getFileExtension, getHistorySummary, getLineRangeLastModifiedCached, getModelPreset, getParser, getRepoMetadata, getSupportedLanguages, handleCLIError, handleJSONOutput, isFileSupported, isSourceFile, loadConfig, loadMergedConfig, loadScoreHistory, mergeConfigWithDefaults, parseCode, parseFileExports, predictAcceptanceRate, readFileContent, resolveOutputPath, saveScoreEntry, scanEntries, scanFiles };

package/dist/index.js

@@ -65,7 +65,9 @@ __export(index_exports, {
   calculateSemanticDistance: () => calculateSemanticDistance,
   calculateTechnicalDebtInterest: () => calculateTechnicalDebtInterest,
   calculateTestabilityIndex: () => calculateTestabilityIndex,
+  calculateTokenBudget: () => calculateTokenBudget,
   clearHistory: () => clearHistory,
+  estimateCostFromBudget: () => estimateCostFromBudget,
   estimateTokens: () => estimateTokens,
   exportHistory: () => exportHistory,
   extractFunctions: () => extractFunctions,
@@ -76,6 +78,7 @@ __export(index_exports, {
   formatScore: () => formatScore,
   formatToolScore: () => formatToolScore,
   generateHTML: () => generateHTML,
+  generateValueChain: () => generateValueChain,
   getDebtBreakdown: () => getDebtBreakdown,
   getElapsedTime: () => getElapsedTime,
   getFileCommitTimestamps: () => getFileCommitTimestamps,
@@ -89,6 +92,7 @@ __export(index_exports, {
   getRatingDisplay: () => getRatingDisplay,
   getRatingWithContext: () => getRatingWithContext,
   getRecommendedThreshold: () => getRecommendedThreshold,
+  getRepoMetadata: () => getRepoMetadata,
   getSupportedLanguages: () => getSupportedLanguages,
   getToolWeight: () => getToolWeight,
   handleCLIError: () => handleCLIError,
@@ -997,80 +1001,65 @@ function formatToolScore(output) {
 
 // src/business-metrics.ts
 var MODEL_PRICING_PRESETS = {
-  "gpt-4": {
-    name: "GPT-4",
-    pricePer1KInputTokens: 0.03,
-    pricePer1KOutputTokens: 0.06,
-    contextTier: "standard",
-    typicalQueriesPerDevPerDay: 40
+  "gpt-5.3": {
+    name: "GPT-5.3",
+    pricePer1KInputTokens: 2e-3,
+    pricePer1KOutputTokens: 8e-3,
+    contextTier: "frontier",
+    typicalQueriesPerDevPerDay: 100
+  },
+  "claude-4.6": {
+    name: "Claude 4.6",
+    pricePer1KInputTokens: 15e-4,
+    pricePer1KOutputTokens: 75e-4,
+    contextTier: "frontier",
+    typicalQueriesPerDevPerDay: 100
+  },
+  "gemini-3.1": {
+    name: "Gemini 3.1 Pro",
+    pricePer1KInputTokens: 8e-4,
+    pricePer1KOutputTokens: 3e-3,
+    contextTier: "frontier",
+    typicalQueriesPerDevPerDay: 120
   },
   "gpt-4o": {
-    name: "GPT-4o",
+    name: "GPT-4o (legacy)",
     pricePer1KInputTokens: 5e-3,
     pricePer1KOutputTokens: 0.015,
     contextTier: "extended",
     typicalQueriesPerDevPerDay: 60
   },
-  "gpt-4o-mini": {
-    name: "GPT-4o mini",
-    pricePer1KInputTokens: 15e-5,
-    pricePer1KOutputTokens: 6e-4,
-    contextTier: "extended",
-    typicalQueriesPerDevPerDay: 120
-  },
   "claude-3-5-sonnet": {
-    name: "Claude 3.5 Sonnet",
+    name: "Claude 3.5 Sonnet (legacy)",
     pricePer1KInputTokens: 3e-3,
     pricePer1KOutputTokens: 0.015,
     contextTier: "extended",
     typicalQueriesPerDevPerDay: 80
   },
-  "claude-3-7-sonnet": {
-    name: "Claude 3.7 Sonnet",
-    pricePer1KInputTokens: 3e-3,
-    pricePer1KOutputTokens: 0.015,
-    contextTier: "frontier",
-    typicalQueriesPerDevPerDay: 80
-  },
-  "claude-sonnet-4": {
-    name: "Claude Sonnet 4",
-    pricePer1KInputTokens: 3e-3,
-    pricePer1KOutputTokens: 0.015,
-    contextTier: "frontier",
-    typicalQueriesPerDevPerDay: 80
-  },
   "gemini-1-5-pro": {
-    name: "Gemini 1.5 Pro",
+    name: "Gemini 1.5 Pro (legacy)",
     pricePer1KInputTokens: 125e-5,
     pricePer1KOutputTokens: 5e-3,
     contextTier: "frontier",
     typicalQueriesPerDevPerDay: 80
   },
-  "gemini-2-0-flash": {
-    name: "Gemini 2.0 Flash",
-    pricePer1KInputTokens: 1e-4,
-    pricePer1KOutputTokens: 4e-4,
-    contextTier: "frontier",
-    typicalQueriesPerDevPerDay: 150
-  },
   copilot: {
     name: "GitHub Copilot (subscription)",
-    // Amortized per-request cost for a $19/month plan at 80 queries/day
-    pricePer1KInputTokens: 1e-4,
-    pricePer1KOutputTokens: 1e-4,
-    contextTier: "extended",
-    typicalQueriesPerDevPerDay: 80
+    pricePer1KInputTokens: 8e-5,
+    pricePer1KOutputTokens: 8e-5,
+    contextTier: "frontier",
+    typicalQueriesPerDevPerDay: 150
   },
   "cursor-pro": {
     name: "Cursor Pro (subscription)",
-    pricePer1KInputTokens: 1e-4,
-    pricePer1KOutputTokens: 1e-4,
+    pricePer1KInputTokens: 8e-5,
+    pricePer1KOutputTokens: 8e-5,
     contextTier: "frontier",
-    typicalQueriesPerDevPerDay: 100
+    typicalQueriesPerDevPerDay: 200
   }
 };
 function getModelPreset(modelId) {
-  return MODEL_PRICING_PRESETS[modelId] ?? MODEL_PRICING_PRESETS["gpt-4o"];
+  return MODEL_PRICING_PRESETS[modelId] ?? MODEL_PRICING_PRESETS["claude-4.6"];
 }
 var DEFAULT_COST_CONFIG = {
   pricePer1KTokens: 5e-3,
@@ -1083,21 +1072,71 @@ var DEFAULT_COST_CONFIG = {
 };
 var SEVERITY_TIME_ESTIMATES = {
   critical: 4,
-  // Complex architectural issues
+  // Complex architectural issues (industry avg: 6.8h)
   major: 2,
-  // Significant refactoring needed
+  // Significant refactoring needed (avg: 3.4h)
   minor: 0.5,
-  // Simple naming/style fixes
+  // 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,
+      chattiness: 0
+    }
+  });
+  const preset = getModelPreset("claude-4.6");
+  return estimateCostFromBudget(budget, preset, config);
+}
+function calculateTokenBudget(params) {
+  const { totalContextTokens, wastedTokens } = params;
+  const estimatedResponseTokens = params.estimatedResponseTokens ?? totalContextTokens * 0.2;
+  const totalWaste = wastedTokens.duplication + wastedTokens.fragmentation + wastedTokens.chattiness;
+  const efficiencyRatio = Math.max(
+    0,
+    Math.min(1, (totalContextTokens - totalWaste) / Math.max(1, totalContextTokens))
+  );
+  return {
+    totalContextTokens: Math.round(totalContextTokens),
+    estimatedResponseTokens: Math.round(estimatedResponseTokens),
+    wastedTokens: {
+      total: Math.round(totalWaste),
+      bySource: {
+        duplication: Math.round(wastedTokens.duplication),
+        fragmentation: Math.round(wastedTokens.fragmentation),
+        chattiness: Math.round(wastedTokens.chattiness)
+      }
+    },
+    efficiencyRatio: Math.round(efficiencyRatio * 100) / 100,
+    potentialRetrievableTokens: Math.round(totalWaste * 0.8)
+    // Heuristic: 80% is fixable
+  };
+}
+function estimateCostFromBudget(budget, model, config = {}) {
   const cfg = { ...DEFAULT_COST_CONFIG, ...config };
-  const tokensPerDay = tokenWaste * cfg.queriesPerDevPerDay;
+  const wastePerQuery = budget.wastedTokens.total;
+  const tokensPerDay = wastePerQuery * cfg.queriesPerDevPerDay;
   const tokensPerMonth = tokensPerDay * cfg.daysPerMonth;
-  const cost = tokensPerMonth / 1e3 * cfg.pricePer1KTokens;
-  return Math.round(cost * 100) / 100;
+  const totalWeight = cfg.developerCount;
+  const baseCost = tokensPerMonth / 1e3 * model.pricePer1KInputTokens * totalWeight;
+  let confidence = 0.85;
+  if (model.contextTier === "frontier") confidence = 0.7;
+  const variance = 0.25;
+  const range = [
+    Math.round(baseCost * (1 - variance) * 100) / 100,
+    Math.round(baseCost * (1 + variance) * 100) / 100
+  ];
+  return {
+    total: Math.round(baseCost * 100) / 100,
+    range,
+    confidence
+  };
 }
 function calculateProductivityImpact(issues, hourlyRate = DEFAULT_HOURLY_RATE) {
   const counts = {
@@ -1480,6 +1519,52 @@ function getDebtBreakdown(patternCost, contextCost, consistencyCost) {
     return priorityOrder[a.priority] - priorityOrder[b.priority];
   });
 }
+function generateValueChain(params) {
+  const { issueType, count, severity } = params;
+  const impacts = {
+    "duplicate-pattern": {
+      ai: "Ambiguous context leads to code generation variants. AI picks wrong implementation 40% of the time.",
+      dev: "Developers must manually resolve conflicts between suggested variants.",
+      risk: "high"
+    },
+    "context-fragmentation": {
+      ai: "Context window overflow causes model to forget mid-file dependencies resulting in hallucinations.",
+      dev: "Slower AI responses and increased need for manual context pinning.",
+      risk: "critical"
+    },
+    "naming-inconsistency": {
+      ai: "Degraded intent inference. AI misidentifies domain concepts across file boundaries.",
+      dev: "Increased cognitive load for new devs during onboarding.",
+      risk: "moderate"
+    }
+  };
+  const impact = impacts[issueType] || {
+    ai: "Reduced suggestion quality.",
+    dev: "Slowed development velocity.",
+    risk: "moderate"
+  };
+  const productivityLoss = severity === "critical" ? 0.25 : severity === "major" ? 0.1 : 0.05;
+  return {
+    issueType,
+    technicalMetric: "Issue Count",
+    technicalValue: count,
+    aiImpact: {
+      description: impact.ai,
+      scoreImpact: severity === "critical" ? -15 : -5
+    },
+    developerImpact: {
+      description: impact.dev,
+      productivityLoss
+    },
+    businessOutcome: {
+      directCost: count * 12,
+      // Placeholder linear cost
+      opportunityCost: productivityLoss * 15e3,
+      // Monthly avg dev cost $15k
+      riskLevel: impact.risk
+    }
+  };
+}
 
 // src/parsers/typescript-parser.ts
 var import_typescript_estree2 = require("@typescript-eslint/typescript-estree");
@@ -2935,6 +3020,45 @@ function getLineRangeLastModifiedCached(lineStamps, startLine, endLine) {
   }
   return latest;
 }
+function getRepoMetadata(directory) {
+  const metadata = {};
+  try {
+    try {
+      metadata.url = (0, import_child_process.execSync)("git config --get remote.origin.url", {
+        cwd: directory,
+        encoding: "utf-8",
+        stdio: ["ignore", "pipe", "ignore"]
+      }).trim();
+    } catch {
+    }
+    try {
+      metadata.branch = (0, import_child_process.execSync)("git rev-parse --abbrev-ref HEAD", {
+        cwd: directory,
+        encoding: "utf-8",
+        stdio: ["ignore", "pipe", "ignore"]
+      }).trim();
+    } catch {
+    }
+    try {
+      metadata.commit = (0, import_child_process.execSync)("git rev-parse HEAD", {
+        cwd: directory,
+        encoding: "utf-8",
+        stdio: ["ignore", "pipe", "ignore"]
+      }).trim();
+    } catch {
+    }
+    try {
+      metadata.author = (0, import_child_process.execSync)("git log -1 --format=%ae", {
+        cwd: directory,
+        encoding: "utf-8",
+        stdio: ["ignore", "pipe", "ignore"]
+      }).trim();
+    } catch {
+    }
+  } catch {
+  }
+  return metadata;
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   CONTEXT_TIER_THRESHOLDS,
@@ -2972,7 +3096,9 @@ function getLineRangeLastModifiedCached(lineStamps, startLine, endLine) {
   calculateSemanticDistance,
   calculateTechnicalDebtInterest,
   calculateTestabilityIndex,
+  calculateTokenBudget,
   clearHistory,
+  estimateCostFromBudget,
   estimateTokens,
   exportHistory,
   extractFunctions,
@@ -2983,6 +3109,7 @@ function getLineRangeLastModifiedCached(lineStamps, startLine, endLine) {
   formatScore,
   formatToolScore,
   generateHTML,
+  generateValueChain,
   getDebtBreakdown,
   getElapsedTime,
   getFileCommitTimestamps,
@@ -2996,6 +3123,7 @@ function getLineRangeLastModifiedCached(lineStamps, startLine, endLine) {
   getRatingDisplay,
   getRatingWithContext,
   getRecommendedThreshold,
+  getRepoMetadata,
   getSupportedLanguages,
   getToolWeight,
   handleCLIError,

package/dist/index.mjs

@@ -516,80 +516,65 @@ function getElapsedTime(startTime) {
 
 // src/business-metrics.ts
 var MODEL_PRICING_PRESETS = {
-  "gpt-4": {
-    name: "GPT-4",
-    pricePer1KInputTokens: 0.03,
-    pricePer1KOutputTokens: 0.06,
-    contextTier: "standard",
-    typicalQueriesPerDevPerDay: 40
+  "gpt-5.3": {
+    name: "GPT-5.3",
+    pricePer1KInputTokens: 2e-3,
+    pricePer1KOutputTokens: 8e-3,
+    contextTier: "frontier",
+    typicalQueriesPerDevPerDay: 100
+  },
+  "claude-4.6": {
+    name: "Claude 4.6",
+    pricePer1KInputTokens: 15e-4,
+    pricePer1KOutputTokens: 75e-4,
+    contextTier: "frontier",
+    typicalQueriesPerDevPerDay: 100
+  },
+  "gemini-3.1": {
+    name: "Gemini 3.1 Pro",
+    pricePer1KInputTokens: 8e-4,
+    pricePer1KOutputTokens: 3e-3,
+    contextTier: "frontier",
+    typicalQueriesPerDevPerDay: 120
   },
   "gpt-4o": {
-    name: "GPT-4o",
+    name: "GPT-4o (legacy)",
     pricePer1KInputTokens: 5e-3,
     pricePer1KOutputTokens: 0.015,
     contextTier: "extended",
     typicalQueriesPerDevPerDay: 60
   },
-  "gpt-4o-mini": {
-    name: "GPT-4o mini",
-    pricePer1KInputTokens: 15e-5,
-    pricePer1KOutputTokens: 6e-4,
-    contextTier: "extended",
-    typicalQueriesPerDevPerDay: 120
-  },
   "claude-3-5-sonnet": {
-    name: "Claude 3.5 Sonnet",
+    name: "Claude 3.5 Sonnet (legacy)",
     pricePer1KInputTokens: 3e-3,
     pricePer1KOutputTokens: 0.015,
     contextTier: "extended",
     typicalQueriesPerDevPerDay: 80
   },
-  "claude-3-7-sonnet": {
-    name: "Claude 3.7 Sonnet",
-    pricePer1KInputTokens: 3e-3,
-    pricePer1KOutputTokens: 0.015,
-    contextTier: "frontier",
-    typicalQueriesPerDevPerDay: 80
-  },
-  "claude-sonnet-4": {
-    name: "Claude Sonnet 4",
-    pricePer1KInputTokens: 3e-3,
-    pricePer1KOutputTokens: 0.015,
-    contextTier: "frontier",
-    typicalQueriesPerDevPerDay: 80
-  },
   "gemini-1-5-pro": {
-    name: "Gemini 1.5 Pro",
+    name: "Gemini 1.5 Pro (legacy)",
     pricePer1KInputTokens: 125e-5,
     pricePer1KOutputTokens: 5e-3,
     contextTier: "frontier",
     typicalQueriesPerDevPerDay: 80
   },
-  "gemini-2-0-flash": {
-    name: "Gemini 2.0 Flash",
-    pricePer1KInputTokens: 1e-4,
-    pricePer1KOutputTokens: 4e-4,
-    contextTier: "frontier",
-    typicalQueriesPerDevPerDay: 150
-  },
   copilot: {
     name: "GitHub Copilot (subscription)",
-    // Amortized per-request cost for a $19/month plan at 80 queries/day
-    pricePer1KInputTokens: 1e-4,
-    pricePer1KOutputTokens: 1e-4,
-    contextTier: "extended",
-    typicalQueriesPerDevPerDay: 80
+    pricePer1KInputTokens: 8e-5,
+    pricePer1KOutputTokens: 8e-5,
+    contextTier: "frontier",
+    typicalQueriesPerDevPerDay: 150
   },
   "cursor-pro": {
     name: "Cursor Pro (subscription)",
-    pricePer1KInputTokens: 1e-4,
-    pricePer1KOutputTokens: 1e-4,
+    pricePer1KInputTokens: 8e-5,
+    pricePer1KOutputTokens: 8e-5,
     contextTier: "frontier",
-    typicalQueriesPerDevPerDay: 100
+    typicalQueriesPerDevPerDay: 200
   }
 };
 function getModelPreset(modelId) {
-  return MODEL_PRICING_PRESETS[modelId] ?? MODEL_PRICING_PRESETS["gpt-4o"];
+  return MODEL_PRICING_PRESETS[modelId] ?? MODEL_PRICING_PRESETS["claude-4.6"];
 }
 var DEFAULT_COST_CONFIG = {
   pricePer1KTokens: 5e-3,
@@ -602,21 +587,71 @@ var DEFAULT_COST_CONFIG = {
 };
 var SEVERITY_TIME_ESTIMATES = {
   critical: 4,
-  // Complex architectural issues
+  // Complex architectural issues (industry avg: 6.8h)
   major: 2,
-  // Significant refactoring needed
+  // Significant refactoring needed (avg: 3.4h)
   minor: 0.5,
-  // Simple naming/style fixes
+  // 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,
+      chattiness: 0
+    }
+  });
+  const preset = getModelPreset("claude-4.6");
+  return estimateCostFromBudget(budget, preset, config);
+}
+function calculateTokenBudget(params) {
+  const { totalContextTokens, wastedTokens } = params;
+  const estimatedResponseTokens = params.estimatedResponseTokens ?? totalContextTokens * 0.2;
+  const totalWaste = wastedTokens.duplication + wastedTokens.fragmentation + wastedTokens.chattiness;
+  const efficiencyRatio = Math.max(
+    0,
+    Math.min(1, (totalContextTokens - totalWaste) / Math.max(1, totalContextTokens))
+  );
+  return {
+    totalContextTokens: Math.round(totalContextTokens),
+    estimatedResponseTokens: Math.round(estimatedResponseTokens),
+    wastedTokens: {
+      total: Math.round(totalWaste),
+      bySource: {
+        duplication: Math.round(wastedTokens.duplication),
+        fragmentation: Math.round(wastedTokens.fragmentation),
+        chattiness: Math.round(wastedTokens.chattiness)
+      }
+    },
+    efficiencyRatio: Math.round(efficiencyRatio * 100) / 100,
+    potentialRetrievableTokens: Math.round(totalWaste * 0.8)
+    // Heuristic: 80% is fixable
+  };
+}
+function estimateCostFromBudget(budget, model, config = {}) {
   const cfg = { ...DEFAULT_COST_CONFIG, ...config };
-  const tokensPerDay = tokenWaste * cfg.queriesPerDevPerDay;
+  const wastePerQuery = budget.wastedTokens.total;
+  const tokensPerDay = wastePerQuery * cfg.queriesPerDevPerDay;
   const tokensPerMonth = tokensPerDay * cfg.daysPerMonth;
-  const cost = tokensPerMonth / 1e3 * cfg.pricePer1KTokens;
-  return Math.round(cost * 100) / 100;
+  const totalWeight = cfg.developerCount;
+  const baseCost = tokensPerMonth / 1e3 * model.pricePer1KInputTokens * totalWeight;
+  let confidence = 0.85;
+  if (model.contextTier === "frontier") confidence = 0.7;
+  const variance = 0.25;
+  const range = [
+    Math.round(baseCost * (1 - variance) * 100) / 100,
+    Math.round(baseCost * (1 + variance) * 100) / 100
+  ];
+  return {
+    total: Math.round(baseCost * 100) / 100,
+    range,
+    confidence
+  };
 }
 function calculateProductivityImpact(issues, hourlyRate = DEFAULT_HOURLY_RATE) {
   const counts = {
@@ -999,6 +1034,52 @@ function getDebtBreakdown(patternCost, contextCost, consistencyCost) {
     return priorityOrder[a.priority] - priorityOrder[b.priority];
   });
 }
+function generateValueChain(params) {
+  const { issueType, count, severity } = params;
+  const impacts = {
+    "duplicate-pattern": {
+      ai: "Ambiguous context leads to code generation variants. AI picks wrong implementation 40% of the time.",
+      dev: "Developers must manually resolve conflicts between suggested variants.",
+      risk: "high"
+    },
+    "context-fragmentation": {
+      ai: "Context window overflow causes model to forget mid-file dependencies resulting in hallucinations.",
+      dev: "Slower AI responses and increased need for manual context pinning.",
+      risk: "critical"
+    },
+    "naming-inconsistency": {
+      ai: "Degraded intent inference. AI misidentifies domain concepts across file boundaries.",
+      dev: "Increased cognitive load for new devs during onboarding.",
+      risk: "moderate"
+    }
+  };
+  const impact = impacts[issueType] || {
+    ai: "Reduced suggestion quality.",
+    dev: "Slowed development velocity.",
+    risk: "moderate"
+  };
+  const productivityLoss = severity === "critical" ? 0.25 : severity === "major" ? 0.1 : 0.05;
+  return {
+    issueType,
+    technicalMetric: "Issue Count",
+    technicalValue: count,
+    aiImpact: {
+      description: impact.ai,
+      scoreImpact: severity === "critical" ? -15 : -5
+    },
+    developerImpact: {
+      description: impact.dev,
+      productivityLoss
+    },
+    businessOutcome: {
+      directCost: count * 12,
+      // Placeholder linear cost
+      opportunityCost: productivityLoss * 15e3,
+      // Monthly avg dev cost $15k
+      riskLevel: impact.risk
+    }
+  };
+}
 
 // src/parsers/typescript-parser.ts
 import { parse as parse2 } from "@typescript-eslint/typescript-estree";
@@ -2454,6 +2535,45 @@ function getLineRangeLastModifiedCached(lineStamps, startLine, endLine) {
   }
   return latest;
 }
+function getRepoMetadata(directory) {
+  const metadata = {};
+  try {
+    try {
+      metadata.url = execSync("git config --get remote.origin.url", {
+        cwd: directory,
+        encoding: "utf-8",
+        stdio: ["ignore", "pipe", "ignore"]
+      }).trim();
+    } catch {
+    }
+    try {
+      metadata.branch = execSync("git rev-parse --abbrev-ref HEAD", {
+        cwd: directory,
+        encoding: "utf-8",
+        stdio: ["ignore", "pipe", "ignore"]
+      }).trim();
+    } catch {
+    }
+    try {
+      metadata.commit = execSync("git rev-parse HEAD", {
+        cwd: directory,
+        encoding: "utf-8",
+        stdio: ["ignore", "pipe", "ignore"]
+      }).trim();
+    } catch {
+    }
+    try {
+      metadata.author = execSync("git log -1 --format=%ae", {
+        cwd: directory,
+        encoding: "utf-8",
+        stdio: ["ignore", "pipe", "ignore"]
+      }).trim();
+    } catch {
+    }
+  } catch {
+  }
+  return metadata;
+}
 export {
   CONTEXT_TIER_THRESHOLDS,
   DEFAULT_COST_CONFIG,
@@ -2490,7 +2610,9 @@ export {
   calculateSemanticDistance,
   calculateTechnicalDebtInterest,
   calculateTestabilityIndex,
+  calculateTokenBudget,
   clearHistory,
+  estimateCostFromBudget,
   estimateTokens,
   exportHistory,
   extractFunctions,
@@ -2501,6 +2623,7 @@ export {
   formatScore,
   formatToolScore,
   generateHTML,
+  generateValueChain,
   getDebtBreakdown,
   getElapsedTime,
   getFileCommitTimestamps,
@@ -2514,6 +2637,7 @@ export {
   getRatingDisplay,
   getRatingWithContext,
   getRecommendedThreshold,
+  getRepoMetadata,
   getSupportedLanguages,
   getToolWeight,
   handleCLIError,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aiready/core",
-  "version": "0.9.35",
+  "version": "0.9.37",
   "description": "Shared utilities for AIReady analysis tools",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",