kardo_core/scoring/

engine.rs

//! Main scoring engine: weighted average + floor penalties.

use crate::analysis::{
    AgentSetupResult, ConfigQualityResult, FreshnessResult, IntegrityResult, StructureResult,
};

use super::types::*;

/// Scoring weights from Blueprint Section 4.
const W_FRESHNESS: f64 = 0.30;
const W_CONFIGURATION: f64 = 0.25;
const W_INTEGRITY: f64 = 0.20;
const W_AGENT_SETUP: f64 = 0.15;
const W_STRUCTURE: f64 = 0.10;

/// Floor penalty thresholds.
/// Calibrated 2026-02-23 on 84-repo benchmark (batch 3).
/// CAP_ZERO lowered from 0.45 to 0.20 to match expert scores for
/// repos with no AI config (experts rate ~20%).
const FLOOR_LOW_THRESHOLD: f64 = 0.2;
const FLOOR_ZERO_THRESHOLD: f64 = 0.001;
const CAP_ZERO: f64 = 0.20;

/// Computes the overall AI-Readiness Score from component analysis results.
pub struct ScoringEngine;

impl ScoringEngine {
    /// Compute the AI-Readiness Score from analysis results.
    #[must_use]
    pub fn score(
        freshness: &FreshnessResult,
        integrity: &IntegrityResult,
        config_quality: &ConfigQualityResult,
        agent_setup: &AgentSetupResult,
        structure: &StructureResult,
    ) -> ProjectScore {
        let components = ComponentScores {
            freshness: freshness.score,
            configuration: config_quality.score,
            integrity: integrity.score,
            agent_setup: agent_setup.score,
            structure: structure.score,
        };

        // Weighted average
        let mut total = W_FRESHNESS * components.freshness
            + W_CONFIGURATION * components.configuration
            + W_INTEGRITY * components.integrity
            + W_AGENT_SETUP * components.agent_setup
            + W_STRUCTURE * components.structure;

        let all_scores = [
            components.freshness,
            components.configuration,
            components.integrity,
            components.agent_setup,
            components.structure,
        ];

        // BUG-3 fix: Bonus for exceptional quality — applied BEFORE floor penalties.
        // Rewards repos where ALL components are strong, lifting the ~80.6 ceiling.
        let min_component = all_scores.iter().cloned().fold(f64::INFINITY, f64::min);
        let bonus = if min_component >= 0.85 {
            // All components excellent: bonus up to +0.08
            ((min_component - 0.85) * 0.8).min(0.08)
        } else if min_component >= 0.75 {
            // All components good: small bonus up to +0.03
            (min_component - 0.75) * 0.3
        } else {
            0.0
        };
        total = (total + bonus).min(1.0); // Cap at 1.0 to preserve perfect-score semantics

        // Floor penalties
        if all_scores.iter().any(|&s| s < FLOOR_ZERO_THRESHOLD) {
            total = total.min(CAP_ZERO);
        } else if all_scores.iter().any(|&s| s < FLOOR_LOW_THRESHOLD) {
            // BUG-2 fix: Dynamic CAP_LOW based on severity and count of low components.
            // Replaces flat 0.55 cap that caused 9-repo cluster in benchmark.
            let low_count = all_scores
                .iter()
                .filter(|&&s| (FLOOR_ZERO_THRESHOLD..FLOOR_LOW_THRESHOLD).contains(&s))
                .count();
            let avg_low_deficit = if low_count > 0 {
                all_scores
                    .iter()
                    .filter(|&&s| (FLOOR_ZERO_THRESHOLD..FLOOR_LOW_THRESHOLD).contains(&s))
                    .map(|&s| FLOOR_LOW_THRESHOLD - s)
                    .sum::<f64>()
                    / low_count as f64
            } else {
                0.0
            };

            // Cap range: 0.45 (severe, multiple low) to 0.65 (mild, single slightly-low)
            let dynamic_cap = if low_count >= 3 {
                0.45
            } else if low_count == 2 {
                0.50
            } else {
                // Single low component: scale 0.55–0.65 based on deficit severity
                // deficit 0.0 (just at threshold) → cap 0.65
                // deficit 0.2 (component=0, but > FLOOR_ZERO_THRESHOLD) → cap 0.45
                (0.65 - avg_low_deficit * 1.0).clamp(0.45, 0.65)
            };
            total = total.min(dynamic_cap);
        }

        let traffic_light = TrafficLight::from_score(total);

        // Generate issues from analysis results
        let mut issues = Vec::new();
        Self::generate_freshness_issues(freshness, &mut issues);
        Self::generate_integrity_issues(integrity, &mut issues);
        Self::generate_config_issues(config_quality, &mut issues);

        // Enrich issues with priority metadata
        for issue in &mut issues {
            Self::enrich_issue(issue, &components);
        }

        // Sort by severity rank (Blocking first, then High, Medium, Low)
        issues.sort_by_key(|i| (i.severity.rank(), std::cmp::Reverse(i.priority_score)));

        ProjectScore {
            total,
            components,
            traffic_light,
            issues,
        }
    }

    /// Enrich a single issue with fix_type, effort, score_delta, and priority_score.
    fn enrich_issue(issue: &mut QualityIssue, components: &ComponentScores) {
        // Assign fix_type and effort based on issue id pattern
        let (fix_type, effort) = Self::classify_fix(&issue.id);
        issue.fix_type = fix_type;
        issue.effort_minutes = Some(effort);

        // Estimate score delta
        issue.score_delta_est = Some(Self::estimate_score_delta(issue.severity, issue.category, components));

        // Compute composite priority
        issue.priority_score = Self::compute_priority(issue);
    }

    /// Map issue id pattern to fix type and estimated effort (minutes).
    fn classify_fix(issue_id: &str) -> (FixType, u32) {
        if issue_id.starts_with("config-missing-") {
            (FixType::Scaffold, 1)
        } else if issue_id.starts_with("freshness-stale-") {
            (FixType::Update, 5)
        } else if issue_id.starts_with("freshness-aging-") {
            (FixType::Manual, 15)
        } else if issue_id.starts_with("freshness-coupling-") {
            (FixType::Update, 5)
        } else if issue_id.starts_with("integrity-") {
            // Distinguish by severity set during generation
            if issue_id.contains("HeadingNotFound") {
                (FixType::Update, 2)
            } else {
                (FixType::Manual, 5)
            }
        } else if issue_id.starts_with("config-short-") {
            (FixType::Update, 10)
        } else if issue_id.starts_with("config-generic-") {
            (FixType::Manual, 20)
        } else {
            (FixType::NoFix, 0)
        }
    }

    /// Estimate score improvement (percentage points) from fixing one issue.
    fn estimate_score_delta(severity: IssueSeverity, category: IssueCategory, components: &ComponentScores) -> f64 {
        let weight = match category {
            IssueCategory::Freshness => W_FRESHNESS,
            IssueCategory::Configuration => W_CONFIGURATION,
            IssueCategory::Integrity => W_INTEGRITY,
            IssueCategory::AgentSetup => W_AGENT_SETUP,
            IssueCategory::Structure => W_STRUCTURE,
        };

        let component_score = match category {
            IssueCategory::Freshness => components.freshness,
            IssueCategory::Configuration => components.configuration,
            IssueCategory::Integrity => components.integrity,
            IssueCategory::AgentSetup => components.agent_setup,
            IssueCategory::Structure => components.structure,
        };

        // Base impact varies by severity
        let base_impact = match severity {
            IssueSeverity::Blocking => 0.25,
            IssueSeverity::High => 0.15,
            IssueSeverity::Medium => 0.08,
            IssueSeverity::Low => 0.03,
        };

        // Scale by component weight and how low the component is (more room to improve)
        let room = 1.0 - component_score;
        (base_impact * weight * room * 100.0).round().max(0.5)
    }

    /// Compute composite priority score (0-1000).
    /// 50% severity + 30% fixability + 20% delta
    fn compute_priority(issue: &QualityIssue) -> u32 {
        // Severity score: Blocking=1000, High=750, Medium=400, Low=100
        let severity_score = match issue.severity {
            IssueSeverity::Blocking => 1000.0,
            IssueSeverity::High => 750.0,
            IssueSeverity::Medium => 400.0,
            IssueSeverity::Low => 100.0,
        };

        // Fixability: Scaffold=1000, Update=700, Manual=300, NoFix=50
        let fix_score = match issue.fix_type {
            FixType::Scaffold => 1000.0,
            FixType::Update => 700.0,
            FixType::Manual => 300.0,
            FixType::NoFix => 50.0,
        };

        // Delta score: normalize to 0-1000 (assume max delta ~8 pts)
        let delta = issue.score_delta_est.unwrap_or(0.0);
        let delta_score = (delta / 8.0 * 1000.0).min(1000.0);

        let composite = severity_score * 0.5 + fix_score * 0.3 + delta_score * 0.2;
        composite.round() as u32
    }

    /// Compute a "Path to Green" plan from the current score.
    /// Sorts fixable issues by efficiency (delta/effort) and accumulates until Green (76%) or exhausted.
    #[must_use]
    pub fn path_to_green(score: &ProjectScore) -> PathToGreen {
        let green_threshold = 76.0;
        let current = score.total * 100.0;

        if current >= green_threshold {
            return PathToGreen {
                steps: vec![],
                total_delta: 0.0,
                total_effort_minutes: 0,
                projected_score: current,
                reachable: true,
            };
        }

        // Collect fixable issues (Scaffold or Update), sorted by efficiency (delta/effort)
        let mut fixable: Vec<&QualityIssue> = score.issues.iter()
            .filter(|i| matches!(i.fix_type, FixType::Scaffold | FixType::Update))
            .filter(|i| i.score_delta_est.unwrap_or(0.0) > 0.0)
            .collect();

        // Sort by efficiency (delta per minute of effort), descending
        fixable.sort_by(|a, b| {
            let eff_a = a.score_delta_est.unwrap_or(0.0) / a.effort_minutes.unwrap_or(1) as f64;
            let eff_b = b.score_delta_est.unwrap_or(0.0) / b.effort_minutes.unwrap_or(1) as f64;
            eff_b.partial_cmp(&eff_a).unwrap_or(std::cmp::Ordering::Equal)
        });

        let mut steps = Vec::new();
        let mut cumulative = current;
        let mut total_effort = 0u32;
        let mut total_delta = 0.0f64;

        for issue in &fixable {
            let delta = issue.score_delta_est.unwrap_or(0.0);
            let effort = issue.effort_minutes.unwrap_or(0);
            cumulative += delta;
            total_delta += delta;
            total_effort += effort;

            steps.push(PathToGreenStep {
                issue_id: issue.id.clone(),
                title: issue.title.clone(),
                fix_type: issue.fix_type,
                effort_minutes: effort,
                score_delta: delta,
                cumulative_score: cumulative,
            });

            if cumulative >= green_threshold {
                break;
            }
        }

        PathToGreen {
            steps,
            total_delta,
            total_effort_minutes: total_effort,
            projected_score: cumulative,
            reachable: cumulative >= green_threshold,
        }
    }

    fn generate_freshness_issues(result: &FreshnessResult, issues: &mut Vec<QualityIssue>) {
        for file in &result.file_scores {
            if let Some(days) = file.days_since_modified {
                if days > 90 {
                    issues.push(QualityIssue::new(
                        format!("freshness-stale-{}", file.relative_path.replace('/', "-")),
                        Some(file.relative_path.clone()),
                        IssueCategory::Freshness,
                        IssueSeverity::High,
                        format!("{} not updated in {} days", file.relative_path, days),
                        format!(
                            "AI doesn't know about recent project changes because {} hasn't been updated in {} days",
                            file.relative_path, days
                        ),
                        Some(format!("Review and update {} to reflect current project state", file.relative_path)),
                    ));
                } else if days > 30 {
                    issues.push(QualityIssue::new(
                        format!("freshness-aging-{}", file.relative_path.replace('/', "-")),
                        Some(file.relative_path.clone()),
                        IssueCategory::Freshness,
                        IssueSeverity::Medium,
                        format!("{} is {} days old", file.relative_path, days),
                        format!(
                            "AI may be working with outdated context because {} was last updated {} days ago",
                            file.relative_path, days
                        ),
                        Some(format!("Consider updating {} if the project has changed recently", file.relative_path)),
                    ));
                }
            }

            if file.coupling_penalty > 0.1 {
                issues.push(QualityIssue::new(
                    format!("freshness-coupling-{}", file.relative_path.replace('/', "-")),
                    Some(file.relative_path.clone()),
                    IssueCategory::Freshness,
                    IssueSeverity::High,
                    format!("{} references code that changed since last doc update", file.relative_path),
                    format!(
                        "AI may give incorrect answers because {} references code that has been modified since the doc was last updated",
                        file.relative_path
                    ),
                    Some(format!("Update {} to reflect the latest code changes", file.relative_path)),
                ));
            }
        }
    }

    fn generate_integrity_issues(result: &IntegrityResult, issues: &mut Vec<QualityIssue>) {
        for broken in &result.broken {
            let severity = match broken.kind {
                crate::analysis::integrity::BrokenRefKind::FileNotFound => IssueSeverity::High,
                crate::analysis::integrity::BrokenRefKind::HeadingNotFound => IssueSeverity::Medium,
                crate::analysis::integrity::BrokenRefKind::DirectiveReference => IssueSeverity::Blocking,
            };

            issues.push(QualityIssue::new(
                format!(
                    "integrity-{}-{}",
                    broken.source_file.replace('/', "-"),
                    broken.target.replace('/', "-")
                ),
                Some(broken.source_file.clone()),
                IssueCategory::Integrity,
                severity,
                format!("Broken link in {}: {}", broken.source_file, broken.target),
                format!(
                    "AI may follow broken references because {} links to {} which doesn't exist",
                    broken.source_file, broken.target
                ),
                Some(format!(
                    "Fix or remove the reference to {} in {}",
                    broken.target, broken.source_file
                )),
            ));
        }
    }

    fn generate_config_issues(result: &ConfigQualityResult, issues: &mut Vec<QualityIssue>) {
        if !result.has_claude_md {
            issues.push(QualityIssue::new(
                "config-missing-claude-md".to_string(),
                None,
                IssueCategory::Configuration,
                IssueSeverity::Blocking,
                "Missing CLAUDE.md".to_string(),
                "AI has no project-specific instructions because CLAUDE.md is missing"
                    .to_string(),
                Some(
                    "Create a CLAUDE.md with project rules, stack, file structure, and coding conventions"
                        .to_string(),
                ),
            ));
        }

        if !result.has_readme {
            issues.push(QualityIssue::new(
                "config-missing-readme".to_string(),
                None,
                IssueCategory::Configuration,
                IssueSeverity::Medium,
                "Missing README.md".to_string(),
                "AI lacks project overview context because README.md is missing"
                    .to_string(),
                Some(
                    "Create a README.md with project description, setup instructions, and architecture overview"
                        .to_string(),
                ),
            ));
        }

        for detail in &result.details {
            if detail.length_score < 0.3 {
                issues.push(QualityIssue::new(
                    format!("config-short-{}", detail.file.replace('/', "-")),
                    Some(detail.file.clone()),
                    IssueCategory::Configuration,
                    IssueSeverity::Medium,
                    format!("{} is too short", detail.file),
                    format!(
                        "AI receives insufficient guidance because {} lacks detail",
                        detail.file
                    ),
                    Some(format!(
                        "Expand {} with more rules, file paths, and coding conventions",
                        detail.file
                    )),
                ));
            }

            if detail.actionable_score < 0.2 {
                issues.push(QualityIssue::new(
                    format!("config-generic-{}", detail.file.replace('/', "-")),
                    Some(detail.file.clone()),
                    IssueCategory::Configuration,
                    IssueSeverity::Low,
                    format!("{} lacks actionable rules", detail.file),
                    format!(
                        "AI may not follow project conventions because {} doesn't contain clear directives (MUST, NEVER, ALWAYS)",
                        detail.file
                    ),
                    Some(format!(
                        "Add explicit rules with MUST/NEVER/ALWAYS keywords to {}",
                        detail.file
                    )),
                ));
            }
        }
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::analysis::{
        config_quality::ConfigDetail,
        integrity::BrokenReference,
        staleness::FileFreshness,
    };

    fn healthy_freshness() -> FreshnessResult {
        FreshnessResult {
            score: 0.95,
            file_scores: vec![FileFreshness {
                relative_path: "README.md".to_string(),
                score: 0.95,
                days_since_modified: Some(2),
                coupling_penalty: 0.0,
                importance_weight: 1.5,
            }],
        }
    }

    fn healthy_integrity() -> IntegrityResult {
        IntegrityResult {
            score: 1.0,
            total_refs: 5,
            valid_refs: 5,
            broken: vec![],
        }
    }

    fn healthy_config() -> ConfigQualityResult {
        ConfigQualityResult {
            score: 0.85,
            has_claude_md: true,
            has_claude_instructions: true,
            has_readme: true,
            details: vec![ConfigDetail {
                file: "CLAUDE.md".to_string(),
                length_score: 0.9,
                structure_score: 0.8,
                specificity_score: 0.7,
                actionable_score: 0.8,
                file_refs_score: 0.7,
                shell_commands_score: 0.6,
                recency_score: 1.0,
                llm_quality_score: None,
            }],
            llm_adjusted: false,
        }
    }

    fn healthy_agent_setup() -> AgentSetupResult {
        AgentSetupResult {
            score: 0.8,
            claude_md_score: 0.9,
            claude_dir_score: 0.7,
            mcp_score: 0.75,
            cursor_score: 1.0,
            other_ai_score: 0.3,
            details: vec![],
        }
    }

    fn healthy_structure() -> StructureResult {
        StructureResult {
            score: 0.85,
            depth_score: 1.0,
            coverage_score: 1.0,
            naming_score: 1.0,
            standard_score: 0.7,
            organization_score: 0.5,
        }
    }

    fn zero_agent_setup() -> AgentSetupResult {
        AgentSetupResult {
            score: 0.0,
            claude_md_score: 0.0,
            claude_dir_score: 0.0,
            mcp_score: 0.0,
            cursor_score: 0.0,
            other_ai_score: 0.0,
            details: vec![],
        }
    }

    fn zero_structure() -> StructureResult {
        StructureResult {
            score: 0.0,
            depth_score: 0.0,
            coverage_score: 0.0,
            naming_score: 0.0,
            standard_score: 0.0,
            organization_score: 0.0,
        }
    }

    #[test]
    fn test_healthy_project_green() {
        let score = ScoringEngine::score(
            &healthy_freshness(),
            &healthy_integrity(),
            &healthy_config(),
            &healthy_agent_setup(),
            &healthy_structure(),
        );
        assert_eq!(score.traffic_light, TrafficLight::Green);
        assert!(
            score.total >= 0.80,
            "Expected GREEN score >= 0.80, got {}",
            score.total
        );
    }

    #[test]
    fn test_stale_docs_yellow() {
        let freshness = FreshnessResult {
            score: 0.3,
            file_scores: vec![FileFreshness {
                relative_path: "README.md".to_string(),
                score: 0.3,
                days_since_modified: Some(60),
                coupling_penalty: 0.0,
                importance_weight: 1.5,
            }],
        };

        let score = ScoringEngine::score(
            &freshness,
            &healthy_integrity(),
            &healthy_config(),
            &healthy_agent_setup(),
            &healthy_structure(),
        );
        assert_eq!(score.traffic_light, TrafficLight::Yellow);
    }

    #[test]
    fn test_no_claude_md_floor_penalty() {
        let config = ConfigQualityResult {
            score: 0.0,
            has_claude_md: false,
            has_claude_instructions: false,
            has_readme: false,
            details: vec![],
            llm_adjusted: false,
        };

        let score = ScoringEngine::score(
            &healthy_freshness(),
            &healthy_integrity(),
            &config,
            &healthy_agent_setup(),
            &healthy_structure(),
        );
        assert!(
            score.total <= 0.20,
            "Expected capped at 0.20, got {}",
            score.total
        );
        assert_eq!(score.traffic_light, TrafficLight::Red);
    }

    #[test]
    fn test_low_component_floor_penalty() {
        let freshness = FreshnessResult {
            score: 0.15,
            file_scores: vec![],
        };

        let score = ScoringEngine::score(
            &freshness,
            &healthy_integrity(),
            &healthy_config(),
            &healthy_agent_setup(),
            &healthy_structure(),
        );
        // Dynamic cap: single low component (freshness=0.15, deficit=0.05) → cap ≈ 0.60
        assert!(
            score.total <= 0.65,
            "Expected capped by dynamic floor penalty (<= 0.65), got {}",
            score.total
        );
        // Still should be penalized — not reaching full score
        assert!(
            score.total < 0.80,
            "Low component should still be penalized, got {}",
            score.total
        );
    }

    #[test]
    fn test_scoring_formula() {
        let freshness = FreshnessResult {
            score: 1.0,
            file_scores: vec![],
        };
        let integrity = IntegrityResult {
            score: 1.0,
            total_refs: 1,
            valid_refs: 1,
            broken: vec![],
        };
        let config = ConfigQualityResult {
            score: 1.0,
            has_claude_md: true,
            has_claude_instructions: true,
            has_readme: true,
            details: vec![],
            llm_adjusted: false,
        };
        let agent_setup = AgentSetupResult {
            score: 1.0,
            claude_md_score: 1.0,
            claude_dir_score: 1.0,
            mcp_score: 1.0,
            cursor_score: 1.0,
            other_ai_score: 1.0,
            details: vec![],
        };
        let structure = StructureResult {
            score: 1.0,
            depth_score: 1.0,
            coverage_score: 1.0,
            naming_score: 1.0,
            standard_score: 1.0,
            organization_score: 1.0,
        };

        let score = ScoringEngine::score(&freshness, &integrity, &config, &agent_setup, &structure);
        // 0.30*1.0 + 0.25*1.0 + 0.20*1.0 + 0.15*1.0 + 0.10*1.0 = 1.0
        assert!(
            (score.total - 1.0).abs() < 0.01,
            "Expected 1.0, got {}",
            score.total
        );
    }

    #[test]
    fn test_traffic_light_thresholds() {
        // Calibrated thresholds v3: Green >= 76%, Yellow >= 42%, Red < 42%
        assert_eq!(TrafficLight::from_score(0.85), TrafficLight::Green);
        assert_eq!(TrafficLight::from_score(0.76), TrafficLight::Green);
        assert_eq!(TrafficLight::from_score(0.759), TrafficLight::Yellow);
        assert_eq!(TrafficLight::from_score(0.42), TrafficLight::Yellow);
        assert_eq!(TrafficLight::from_score(0.419), TrafficLight::Red);
        assert_eq!(TrafficLight::from_score(0.0), TrafficLight::Red);
    }

    #[test]
    fn test_issues_generated_for_missing_claude_md() {
        let config = ConfigQualityResult {
            score: 0.3,
            has_claude_md: false,
            has_claude_instructions: false,
            has_readme: true,
            details: vec![],
            llm_adjusted: false,
        };

        let score = ScoringEngine::score(
            &healthy_freshness(),
            &healthy_integrity(),
            &config,
            &healthy_agent_setup(),
            &healthy_structure(),
        );

        let config_issues: Vec<_> = score
            .issues
            .iter()
            .filter(|i| i.category == IssueCategory::Configuration)
            .collect();
        assert!(!config_issues.is_empty());
        assert!(config_issues
            .iter()
            .any(|i| i.id == "config-missing-claude-md"));
    }

    #[test]
    fn test_issues_sorted_by_severity() {
        let freshness = FreshnessResult {
            score: 0.1,
            file_scores: vec![FileFreshness {
                relative_path: "old.md".to_string(),
                score: 0.1,
                days_since_modified: Some(100),
                coupling_penalty: 0.2,
                importance_weight: 1.0,
            }],
        };

        let integrity = IntegrityResult {
            score: 0.5,
            total_refs: 2,
            valid_refs: 1,
            broken: vec![BrokenReference {
                source_file: "README.md".to_string(),
                target: "missing.md".to_string(),
                kind: crate::analysis::integrity::BrokenRefKind::FileNotFound,
            }],
        };

        let config = ConfigQualityResult {
            score: 0.0,
            has_claude_md: false,
            has_claude_instructions: false,
            has_readme: false,
            details: vec![],
            llm_adjusted: false,
        };

        let score = ScoringEngine::score(
            &freshness,
            &integrity,
            &config,
            &zero_agent_setup(),
            &zero_structure(),
        );
        if score.issues.len() >= 2 {
            // Missing CLAUDE.md is now Blocking, should be first
            assert_eq!(score.issues[0].severity, IssueSeverity::Blocking);
        }
    }

    #[test]
    fn test_blocking_severity_sorts_first() {
        let config = ConfigQualityResult {
            score: 0.3,
            has_claude_md: false,
            has_claude_instructions: false,
            has_readme: true,
            details: vec![],
            llm_adjusted: false,
        };

        let freshness = FreshnessResult {
            score: 0.1,
            file_scores: vec![FileFreshness {
                relative_path: "old.md".to_string(),
                score: 0.1,
                days_since_modified: Some(100),
                coupling_penalty: 0.0,
                importance_weight: 1.0,
            }],
        };

        let score = ScoringEngine::score(
            &freshness,
            &healthy_integrity(),
            &config,
            &healthy_agent_setup(),
            &healthy_structure(),
        );

        // First issue should be Blocking (missing CLAUDE.md)
        assert!(!score.issues.is_empty());
        assert_eq!(score.issues[0].severity, IssueSeverity::Blocking);
        assert_eq!(score.issues[0].id, "config-missing-claude-md");
    }

    #[test]
    fn test_missing_claude_md_is_blocking() {
        let config = ConfigQualityResult {
            score: 0.3,
            has_claude_md: false,
            has_claude_instructions: false,
            has_readme: true,
            details: vec![],
            llm_adjusted: false,
        };

        let score = ScoringEngine::score(
            &healthy_freshness(),
            &healthy_integrity(),
            &config,
            &healthy_agent_setup(),
            &healthy_structure(),
        );

        let claude_md_issue = score.issues.iter().find(|i| i.id == "config-missing-claude-md");
        assert!(claude_md_issue.is_some());
        assert_eq!(claude_md_issue.unwrap().severity, IssueSeverity::Blocking);
    }

    #[test]
    fn test_priority_score_computation() {
        let config = ConfigQualityResult {
            score: 0.3,
            has_claude_md: false,
            has_claude_instructions: false,
            has_readme: false,
            details: vec![],
            llm_adjusted: false,
        };

        let score = ScoringEngine::score(
            &healthy_freshness(),
            &healthy_integrity(),
            &config,
            &healthy_agent_setup(),
            &healthy_structure(),
        );

        // All issues should have non-zero priority scores
        for issue in &score.issues {
            assert!(issue.priority_score > 0, "Issue {} should have priority > 0", issue.id);
        }

        // Blocking issues should have higher priority than Medium
        let blocking_issues: Vec<_> = score.issues.iter().filter(|i| i.severity == IssueSeverity::Blocking).collect();
        let medium_issues: Vec<_> = score.issues.iter().filter(|i| i.severity == IssueSeverity::Medium).collect();

        if !blocking_issues.is_empty() && !medium_issues.is_empty() {
            assert!(
                blocking_issues[0].priority_score > medium_issues[0].priority_score,
                "Blocking priority {} should exceed Medium priority {}",
                blocking_issues[0].priority_score, medium_issues[0].priority_score
            );
        }
    }

    #[test]
    fn test_fix_type_assignment() {
        let config = ConfigQualityResult {
            score: 0.3,
            has_claude_md: false,
            has_claude_instructions: false,
            has_readme: false,
            details: vec![ConfigDetail {
                file: "CLAUDE.md".to_string(),
                length_score: 0.1,
                structure_score: 0.5,
                specificity_score: 0.5,
                actionable_score: 0.5,
                file_refs_score: 0.5,
                shell_commands_score: 0.5,
                recency_score: 1.0,
                llm_quality_score: None,
            }],
            llm_adjusted: false,
        };

        let freshness = FreshnessResult {
            score: 0.3,
            file_scores: vec![FileFreshness {
                relative_path: "old.md".to_string(),
                score: 0.1,
                days_since_modified: Some(100),
                coupling_penalty: 0.0,
                importance_weight: 1.0,
            }],
        };

        let score = ScoringEngine::score(
            &freshness,
            &healthy_integrity(),
            &config,
            &healthy_agent_setup(),
            &healthy_structure(),
        );

        // Missing CLAUDE.md → Scaffold
        let claude_issue = score.issues.iter().find(|i| i.id == "config-missing-claude-md");
        assert!(claude_issue.is_some());
        assert_eq!(claude_issue.unwrap().fix_type, FixType::Scaffold);
        assert_eq!(claude_issue.unwrap().effort_minutes, Some(1));

        // Stale file → Update
        let stale_issue = score.issues.iter().find(|i| i.id.starts_with("freshness-stale-"));
        assert!(stale_issue.is_some());
        assert_eq!(stale_issue.unwrap().fix_type, FixType::Update);
    }

    #[test]
    fn test_severity_rank_ordering() {
        assert!(IssueSeverity::Blocking.rank() < IssueSeverity::High.rank());
        assert!(IssueSeverity::High.rank() < IssueSeverity::Medium.rank());
        assert!(IssueSeverity::Medium.rank() < IssueSeverity::Low.rank());
    }

    #[test]
    fn test_path_to_green_already_green() {
        let score = ScoringEngine::score(
            &healthy_freshness(),
            &healthy_integrity(),
            &healthy_config(),
            &healthy_agent_setup(),
            &healthy_structure(),
        );
        assert_eq!(score.traffic_light, TrafficLight::Green);

        let p2g = ScoringEngine::path_to_green(&score);
        assert!(p2g.steps.is_empty());
        assert!(p2g.reachable);
        assert_eq!(p2g.total_effort_minutes, 0);
    }

    #[test]
    fn test_path_to_green_not_green() {
        // Use low freshness to get Yellow, which triggers stale issues
        let freshness = FreshnessResult {
            score: 0.3,
            file_scores: vec![FileFreshness {
                relative_path: "README.md".to_string(),
                score: 0.3,
                days_since_modified: Some(100),
                coupling_penalty: 0.0,
                importance_weight: 1.5,
            }],
        };

        let score = ScoringEngine::score(
            &freshness,
            &healthy_integrity(),
            &healthy_config(),
            &healthy_agent_setup(),
            &healthy_structure(),
        );
        assert_ne!(score.traffic_light, TrafficLight::Green,
            "Expected non-Green, got score {}", score.total);

        let p2g = ScoringEngine::path_to_green(&score);
        assert!(!p2g.steps.is_empty());
        assert!(p2g.total_delta > 0.0);
        // Each step should have positive delta
        for step in &p2g.steps {
            assert!(step.score_delta > 0.0);
        }
    }
}