@ngocsangairvds/vsaf 3.2.14 → 3.2.16

package/tools/vds-scripts/audit_orchestrator/src/vds_audit_orchestrator/agents/synthesis_agent.py

@@ -1,1463 +0,0 @@
-"""Synthesis Agent (TSK-049) - PydanticAI Migration.
-
-This agent aggregates results from other agents (code, docs, security) and
-synthesizes them into a comprehensive audit report with maturity scoring.
-
-Uses PydanticAI patterns from pydantic_base.py for structured outputs
-and dependency injection.
-"""
-
-from __future__ import annotations
-
-import json
-import re
-from collections.abc import Callable
-from enum import StrEnum
-from typing import TYPE_CHECKING, Any, Literal
-
-from pydantic import BaseModel, Field, ValidationError
-
-from vds_audit_orchestrator.agents.base import AgentResult, BaseAgent
-from vds_audit_orchestrator.agents.pydantic_base import (
-    GapSummary,
-    SynthesisResult,
-    build_deps,
-)
-from vds_audit_orchestrator.engine.provider_failure_classifier import (
-    SynthesisFallbackCause,
-)
-from vds_audit_orchestrator.errors import AUDIT_ERROR_CODES, AuditError
-from vds_audit_orchestrator.evidence.corpus import EvidenceCorpus, deserialize_evidence_corpus
-from vds_audit_orchestrator.models.evidence import EvidenceBundle
-
-if TYPE_CHECKING:
-    from vds_audit_orchestrator.models.task import AuditTask
-
-
-class MaturityLevel(StrEnum):
-    """Repository maturity levels based on overall score."""
-
-    CRITICAL = "Critical"  # 0-25: Major gaps, immediate action required
-    DEVELOPING = "Developing"  # 26-50: Basic practices, significant improvements needed
-    ESTABLISHED = "Established"  # 51-75: Good practices, some gaps remain
-    OPTIMIZING = "Optimizing"  # 76-90: Strong practices, continuous improvement
-    LEADING = "Leading"  # 91-100: Best-in-class, exemplary practices
-
-
-class FindingSeverity(StrEnum):
-    """Severity levels for findings."""
-
-    CRITICAL = "critical"
-    HIGH = "high"
-    MEDIUM = "medium"
-    LOW = "low"
-    INFO = "info"
-
-
-# Severity weights for scoring
-SEVERITY_WEIGHTS: dict[str, float] = {
-    "critical": 25.0,
-    "high": 15.0,
-    "medium": 8.0,
-    "low": 3.0,
-    "info": 0.0,
-}
-
-# Finding type to severity mapping
-FINDING_TYPE_SEVERITY: dict[str, str] = {
-    "security_vulnerability": "critical",
-    "security_risk": "high",
-    "technical_debt": "medium",
-    "doc_quality": "low",
-}
-
-# =============================================================================
-# PydanticAI Agent Output Models
-# =============================================================================
-
-
-class RecommendationOutput(BaseModel):
-    """Structured recommendation output from the LLM."""
-
-    priority: Literal["critical", "high", "medium", "low"]
-    title: str
-    description: str
-    category: Literal["security", "code", "docs", "process", "cross_cutting"]
-    effort: Literal["low", "medium", "high"]
-
-
-class RecommendationsResult(BaseModel):
-    """Wrapper for recommendations list with confidence."""
-
-    recommendations: list[RecommendationOutput] = Field(default_factory=list)
-    confidence: float = Field(
-        default=0.8,
-        ge=0.0,
-        le=1.0,
-        description="Confidence level of the recommendations",
-    )
-
-
-class ExecutiveSummaryResult(BaseModel):
-    """Structured executive summary output with confidence."""
-
-    summary: str = Field(..., description="Executive summary text")
-    confidence: float = Field(
-        default=0.8,
-        ge=0.0,
-        le=1.0,
-        description="Confidence level of the summary",
-    )
-
-
-# =============================================================================
-# PydanticAI Agents for Synthesis Tasks
-# =============================================================================
-
-_RECOMMENDATIONS_SYSTEM_PROMPT = """You are a senior software architect reviewing audit findings.
-Generate actionable recommendations based on the critical gaps identified.
-
-Focus on:
-1. Security vulnerabilities first
-2. Technical debt that blocks velocity
-3. Documentation gaps affecting knowledge transfer
-4. Process improvements for sustainability
-
-Limit to 5 most impactful recommendations.
-Provide high confidence (>0.7) only when gaps are clear and actionable."""
-
-_EXECUTIVE_SUMMARY_SYSTEM_PROMPT = """You are a technical writer creating an executive summary for a software audit.
-Write a concise 3-4 paragraph summary that:
-1. States the overall maturity assessment
-2. Highlights key strengths
-3. Summarizes critical concerns
-4. Provides a forward-looking statement
-
-Keep it professional and actionable. Maximum 250 words.
-Provide high confidence (>0.7) when you have sufficient context."""
-
-# Create PydanticAI agents using the factory (lazy to avoid import-time side effects)
-_recommendations_agent = None
-_summary_agent = None
-
-CODE_QUALITY_FLOOR_CONFIDENCE = 0.6
-CODE_QUALITY_FLOOR_GROUNDEDNESS = 0.5
-
-
-# =============================================================================
-# SynthesisAgent Class
-# =============================================================================
-
-
-class SynthesisAgent(BaseAgent):
-    """Agent for aggregating and synthesizing results from other agents.
-
-    This agent receives results from CodeAnalysisAgent, DocumentationAgent,
-    and SecurityAgent, then produces a comprehensive synthesis including:
-    - Overall maturity score
-    - Critical gaps requiring immediate attention
-    - Aligned practices (what's working well)
-    - Prioritized recommendations
-    - Executive summary for stakeholders
-
-    Uses PydanticAI agents for LLM-powered recommendations and summaries
-    with structured outputs and confidence validation.
-    """
-
-    def __init__(self, *args, evidence_corpus: EvidenceCorpus | None = None, **kwargs) -> None:
-        super().__init__(*args, **kwargs)
-        self._evidence_corpus = evidence_corpus
-
-    async def analyze(self, evidence: EvidenceBundle | dict | AuditTask) -> AgentResult:
-        """Perform analysis on the evidence bundle.
-
-        This method maintains interface compatibility with BaseAgent.
-        For synthesis operations, use synthesize() which accepts agent results.
-
-        Args:
-            evidence: Evidence bundle (used for context when no agent results available)
-
-        Returns:
-            AgentResult with synthesis metadata
-        """
-        # Extract evidence bundle if wrapped in dict
-        if isinstance(evidence, dict):
-            bundle = evidence.get("evidence_bundle") or evidence.get("evidence")
-            agent_results = evidence.get("agent_results", [])
-            self._evidence_corpus = deserialize_evidence_corpus(evidence.get("evidence_corpus"))
-            if bundle and isinstance(bundle, EvidenceBundle):
-                evidence = bundle
-        else:
-            agent_results = []
-
-        if not isinstance(evidence, EvidenceBundle):
-            return self._result(
-                agent_name="SynthesisAgent",
-                success=False,
-                error=AuditError(
-                    code=AUDIT_ERROR_CODES["AGENT_EVIDENCE_MISSING"],
-                    message="Evidence bundle missing",
-                    template_params={"agent_name": "SynthesisAgent"},
-                ),
-            )
-
-        # If we have agent results, delegate to synthesize
-        if agent_results:
-            synthesis = await self.synthesize(
-                repository=evidence.repository,
-                agent_results=agent_results,
-            )
-            return self._result(
-                agent_name="SynthesisAgent",
-                success=True,
-                findings=[{"type": "synthesis", "data": self._synthesis_to_dict(synthesis)}],
-                metadata={
-                    "overall_score": synthesis.overall_score,
-                    "maturity_level": synthesis.maturity_level,
-                    "critical_gap_count": len(synthesis.gaps),
-                    "recommendation_count": len(synthesis.recommendations),
-                },
-            )
-
-        # Fallback: create minimal synthesis from evidence alone
-        return self._result(
-            agent_name="SynthesisAgent",
-            success=True,
-            findings=[],
-            metadata={
-                "message": "No agent results provided. Use synthesize() for full analysis.",
-                "repository": evidence.repository,
-                "evidence_count": evidence.total_evidence,
-            },
-        )
-
-    async def synthesize(
-        self,
-        repository: str,
-        agent_results: list[AgentResult],
-    ) -> SynthesisResult:
-        """Synthesize results from multiple agents into a comprehensive report.
-
-        Args:
-            repository: Repository identifier being audited
-            agent_results: List of AgentResult from other agents (code, docs, security)
-
-        Returns:
-            SynthesisResult with aggregated findings and recommendations
-        """
-        self.logger.info(
-            "synthesis_started",
-            repository=repository,
-            agent_count=len(agent_results),
-        )
-
-        gated_results = self._apply_code_quality_floor(agent_results)
-
-        # Aggregate all findings
-        all_findings = self._aggregate_findings(gated_results)
-
-        # Calculate agent-specific scores
-        agent_scores = self._calculate_agent_scores(gated_results)
-
-        # Identify cross-cutting concerns
-        cross_cutting = self._identify_cross_cutting_concerns(all_findings)
-
-        # Prioritize findings by severity
-        prioritized = self._prioritize_findings(all_findings)
-
-        # Calculate preliminary overall score (before elevation)
-        preliminary_gaps = self._extract_critical_gaps(prioritized)
-        preliminary_score = self._calculate_overall_score(agent_scores, preliminary_gaps)
-
-        # TSK-304: Elevate critical findings based on score
-        critical_gaps = self._elevate_critical_findings(prioritized, preliminary_score)
-
-        # Recalculate final score with elevated gaps
-        overall_score = self._calculate_overall_score(agent_scores, critical_gaps)
-
-        # Extract aligned practices
-        aligned_practices = self._extract_aligned_practices(gated_results)
-
-        # Determine maturity level
-        maturity_level = self._determine_maturity_level(overall_score)
-
-        # Generate recommendations using PydanticAI agent
-        recommendations = await self._generate_recommendations(
-            repository=repository,
-            critical_gaps=critical_gaps,
-            cross_cutting=cross_cutting,
-            maturity_level=maturity_level,
-        )
-
-        # TSK-304.2: Generate coherent base recommendations
-        _, coherent_recs = self._generate_coherent_recommendations(
-            score=overall_score,
-            critical_gaps=critical_gaps,
-        )
-
-        # Merge coherent recommendations with LLM/rule-based ones
-        for crec in coherent_recs:
-            if not any(r.get("title") == crec.get("title") for r in recommendations):
-                recommendations.insert(0, crec)
-
-        # Generate executive summary using PydanticAI agent
-        executive_summary = await self._generate_executive_summary(
-            repository=repository,
-            overall_score=overall_score,
-            maturity_level=maturity_level,
-            critical_gaps=critical_gaps,
-            aligned_practices=aligned_practices,
-            agent_results=gated_results,
-        )
-
-        # TSK-304.4: Validate synthesis coherence
-        coherent_output = self._validate_synthesis_coherence(
-            score=overall_score,
-            critical_gaps=critical_gaps,
-            recommendations=recommendations,
-            executive_summary=executive_summary,
-        )
-        if not coherent_output:
-            self.logger.warning(
-                "synthesis_summary_replaced_with_template",
-                score=overall_score,
-                critical_gaps=len(critical_gaps),
-            )
-            executive_summary = self._get_template_summary(
-                repository=repository,
-                overall_score=overall_score,
-                maturity_level=maturity_level,
-                critical_gaps=critical_gaps,
-                aligned_practices=aligned_practices,
-            )
-
-        # Convert to SynthesisResult format from pydantic_base
-        gaps = [
-            GapSummary(
-                check_id=f"gap_{i}",
-                severity=gap.get("severity", "medium"),
-                category=gap.get("type", "unknown"),
-                description=gap.get("title", "Unknown issue"),
-                recommendation=gap.get("impact", ""),
-                location=gap.get("location"),
-            )
-            for i, gap in enumerate(critical_gaps)
-        ]
-
-        result = SynthesisResult(
-            overall_score=overall_score,
-            maturity_level=maturity_level,
-            gaps=gaps,
-            aligned_practices=aligned_practices,
-            recommendations=recommendations,
-            confidence=0.85,  # High confidence for deterministic aggregation
-            executive_summary=executive_summary,
-            component_scores=agent_scores,
-            cross_cutting_concerns=cross_cutting,
-        )
-
-        self.logger.info(
-            "synthesis_completed",
-            repository=repository,
-            overall_score=overall_score,
-            maturity_level=maturity_level,
-            critical_gap_count=len(critical_gaps),
-        )
-
-        return result
-
-    @staticmethod
-    def _is_code_agent_result(result: AgentResult) -> bool:
-        return result.agent_name.lower() == "codeanalysisagent"
-
-    @staticmethod
-    def _normalize_location_for_semantic_key(value: Any) -> str:
-        location = str(value or "").strip().lower()
-        if not location:
-            return "unknown"
-        if ":" in location:
-            return location.split(":", 1)[0]
-        return location
-
-    @staticmethod
-    def _is_grounded_location(value: Any) -> bool:
-        location = str(value or "").strip().lower()
-        return bool(location and location not in {"unknown", "n/a"})
-
-    def _compute_code_groundedness(self, findings: list[dict[str, Any]]) -> float:
-        if not findings:
-            return 1.0
-        grounded = 0
-        for finding in findings:
-            location = finding.get("location")
-            if self._is_grounded_location(location):
-                grounded += 1
-                continue
-            details = finding.get("details")
-            if isinstance(details, dict) and self._is_grounded_location(details.get("file_path")):
-                grounded += 1
-        return grounded / len(findings)
-
-    def _apply_code_quality_floor(self, agent_results: list[AgentResult]) -> list[AgentResult]:
-        """Apply FR-76 quality floor before synthesis aggregation."""
-        gated_results: list[AgentResult] = []
-        for result in agent_results:
-            if not result.success or not self._is_code_agent_result(result):
-                gated_results.append(result)
-                continue
-            metadata = result.metadata if isinstance(result.metadata, dict) else {}
-            has_quality_signals = any(
-                key in metadata for key in ("confidence", "llm_summary", "agentic_tool_efficiency")
-            )
-            if not has_quality_signals:
-                gated_results.append(result)
-                continue
-            confidence = float(metadata.get("confidence") or 1.0)
-            groundedness = self._compute_code_groundedness(result.findings)
-            passed = confidence >= CODE_QUALITY_FLOOR_CONFIDENCE and groundedness >= CODE_QUALITY_FLOOR_GROUNDEDNESS
-            quality_gate = {
-                "passed": passed,
-                "confidence": round(confidence, 3),
-                "groundedness": round(groundedness, 3),
-                "min_confidence": CODE_QUALITY_FLOOR_CONFIDENCE,
-                "min_groundedness": CODE_QUALITY_FLOOR_GROUNDEDNESS,
-            }
-            if passed:
-                result.metadata["quality_floor"] = quality_gate
-                gated_results.append(result)
-                continue
-            self.logger.warning(
-                "synthesis_code_quality_floor_blocked",
-                agent_name=result.agent_name,
-                confidence=quality_gate["confidence"],
-                groundedness=quality_gate["groundedness"],
-                min_confidence=quality_gate["min_confidence"],
-                min_groundedness=quality_gate["min_groundedness"],
-            )
-            gated_results.append(
-                AgentResult(
-                    agent_name=result.agent_name,
-                    success=False,
-                    findings=[],
-                    metadata={**metadata, "quality_floor": quality_gate},
-                    error=(
-                        "code-agent quality floor unsatisfied: "
-                        f"confidence={quality_gate['confidence']} groundedness={quality_gate['groundedness']}"
-                    ),
-                )
-            )
-        return gated_results
-
-    def _synthesis_to_dict(self, synthesis: SynthesisResult) -> dict[str, Any]:
-        """Convert SynthesisResult to dictionary for backward compatibility."""
-        return {
-            "overall_score": synthesis.overall_score,
-            "maturity_level": synthesis.maturity_level,
-            "critical_gaps": [g.model_dump() for g in synthesis.gaps],
-            "aligned_practices": synthesis.aligned_practices,
-            "recommendations": synthesis.recommendations,
-            "executive_summary": synthesis.executive_summary,
-            "agent_scores": synthesis.component_scores,
-            "cross_cutting_concerns": synthesis.cross_cutting_concerns,
-        }
-
-    def _aggregate_findings(self, agent_results: list[AgentResult]) -> list[dict[str, Any]]:
-        """Aggregate findings from all agents with source attribution."""
-        aggregated: list[dict[str, Any]] = []
-
-        for result in agent_results:
-            if not result.success:
-                continue
-
-            for finding in result.findings:
-                enriched = {
-                    **finding,
-                    "source_agent": result.agent_name,
-                    "severity": self._normalize_severity(finding),
-                }
-                aggregated.append(enriched)
-
-        return self._dedupe_semantic_security_findings(aggregated)
-
-    @staticmethod
-    def _normalize_security_signature_text(finding: dict[str, Any]) -> str:
-        raw = " ".join(str(finding.get(part, "") or "") for part in ("title", "description", "summary")).lower()
-        raw = re.sub(r"[^a-z0-9\s]+", " ", raw)
-        tokens = [token for token in raw.split() if token]
-        stopwords = {
-            "potential",
-            "possible",
-            "issue",
-            "security",
-            "vulnerability",
-            "risk",
-            "found",
-            "detected",
-            "via",
-        }
-        canonical_aliases = {
-            "password": "secret",
-            "token": "secret",
-            "credential": "secret",
-            "credentials": "secret",
-            "api": "secret",
-            "apikey": "secret",
-            "concat": "concatenation",
-            "concatenated": "concatenation",
-            "injected": "injection",
-            "inject": "injection",
-        }
-        normalized: list[str] = []
-        for token in tokens:
-            if token in stopwords:
-                continue
-            normalized.append(canonical_aliases.get(token, token))
-        return " ".join(sorted(set(normalized)))
-
-    def _dedupe_semantic_security_findings(self, findings: list[dict[str, Any]]) -> list[dict[str, Any]]:
-        """Apply FR-77 semantic deduplication for security findings before synthesis."""
-        if not findings:
-            return findings
-        deduped: list[dict[str, Any]] = []
-        dedupe_index: dict[tuple[str, str, str], int] = {}
-        severity_rank = {"critical": 0, "high": 1, "medium": 2, "low": 3, "info": 4}
-        semantic_clusters = {
-            "secret": {"secret", "password", "credential", "token"},
-            "injection": {"injection", "sql", "query", "concatenation"},
-            "transport": {"ssl", "tls", "certificate", "verify", "verification"},
-            "auth": {"auth", "authentication", "authorization", "bypass"},
-        }
-
-        for finding in findings:
-            finding_type = str(finding.get("type", "") or "").lower()
-            if "security" not in finding_type:
-                deduped.append(finding)
-                continue
-            location_key = self._normalize_location_for_semantic_key(finding.get("location"))
-            signature_text = self._normalize_security_signature_text(finding)
-            if not signature_text:
-                deduped.append(finding)
-                continue
-            tokens = set(signature_text.split())
-            semantic_cluster = next(
-                (cluster_name for cluster_name, cluster_tokens in semantic_clusters.items() if tokens & cluster_tokens),
-                signature_text,
-            )
-            dedupe_key = (location_key, finding_type, semantic_cluster)
-            current_index = dedupe_index.get(dedupe_key)
-            if current_index is None:
-                dedupe_index[dedupe_key] = len(deduped)
-                deduped.append(finding)
-                continue
-            existing = deduped[current_index]
-            existing_rank = severity_rank.get(str(existing.get("severity", "medium")).lower(), 2)
-            incoming_rank = severity_rank.get(str(finding.get("severity", "medium")).lower(), 2)
-            if incoming_rank < existing_rank:
-                deduped[current_index] = finding
-
-        if len(deduped) != len(findings):
-            self.logger.info(
-                "synthesis_semantic_security_dedup_applied",
-                original=len(findings),
-                deduped=len(deduped),
-                removed=len(findings) - len(deduped),
-            )
-        return deduped
-
-    def _determine_severity(self, finding: dict[str, Any]) -> str:
-        """Determine severity of a finding based on its type."""
-        finding_type = finding.get("type", "")
-        return FINDING_TYPE_SEVERITY.get(finding_type, "medium")
-
-    def _normalize_severity(self, finding: dict[str, Any]) -> str:
-        """Normalize severity using explicit value or mapped type."""
-        raw = finding.get("severity")
-        if isinstance(raw, str):
-            normalized = raw.lower().strip()
-            if normalized in SEVERITY_WEIGHTS:
-                return normalized
-        mapped = self._determine_severity(finding)
-        return mapped.lower() if isinstance(mapped, str) else "medium"
-
-    def _dedupe_items(
-        self,
-        items: list[dict[str, Any]],
-        key_fn: Callable[[dict[str, Any]], Any],
-        label: str,
-    ) -> list[dict[str, Any]]:
-        """Deduplicate items while preserving order."""
-        seen: set[tuple[Any, ...]] = set()
-        deduped: list[dict[str, Any]] = []
-        for item in items:
-            key = key_fn(item)
-            if key in seen:
-                continue
-            seen.add(key)
-            deduped.append(item)
-        if len(deduped) != len(items):
-            self.logger.debug(
-                "dedupe_applied",
-                label=label,
-                original=len(items),
-                deduped=len(deduped),
-            )
-        return deduped
-
-    def _calculate_agent_scores(self, agent_results: list[AgentResult]) -> dict[str, float]:
-        """Calculate individual scores for each agent's domain."""
-        scores: dict[str, float] = {}
-
-        for result in agent_results:
-            if not result.success:
-                scores[result.agent_name] = 0.0
-                continue
-
-            # Base score starts at 100, deduct based on findings
-            base_score = 100.0
-            deductions = 0.0
-
-            for finding in result.findings:
-                severity = self._determine_severity(finding)
-                deductions += SEVERITY_WEIGHTS.get(severity, 5.0)
-
-            # Cap deductions at 100
-            final_score = max(0.0, base_score - min(deductions, 100.0))
-            scores[result.agent_name] = round(final_score, 2)
-
-        return scores
-
-    def _identify_cross_cutting_concerns(self, all_findings: list[dict[str, Any]]) -> list[dict[str, Any]]:
-        """Identify concerns that span multiple agents/domains."""
-        cross_cutting: list[dict[str, Any]] = []
-
-        # Group findings by location
-        by_location: dict[str, list[dict[str, Any]]] = {}
-        for finding in all_findings:
-            location = finding.get("location", "unknown")
-            if location not in by_location:
-                by_location[location] = []
-            by_location[location].append(finding)
-
-        # Identify locations with findings from multiple agents
-        for location, findings in by_location.items():
-            agents = {f.get("source_agent") for f in findings}
-            if len(agents) > 1:
-                agents_str = ", ".join(str(a) for a in agents if a)
-                cross_cutting.append(
-                    {
-                        "location": location,
-                        "affected_domains": list(agents),
-                        "finding_count": len(findings),
-                        "findings": findings,
-                        "description": f"Multiple concerns at {location} spanning {agents_str}",
-                    }
-                )
-
-        # Also check for pattern-based cross-cutting (e.g., security + tech debt)
-        security_files = {
-            f.get("location") for f in all_findings if f.get("type") in ("security_vulnerability", "security_risk")
-        }
-        debt_files = {f.get("location") for f in all_findings if f.get("type") == "technical_debt"}
-        overlap = security_files & debt_files
-        if overlap:
-            cross_cutting.append(
-                {
-                    "pattern": "security_debt_overlap",
-                    "description": "Files with both security issues and technical debt",
-                    "locations": list(overlap),
-                    "severity": "high",
-                }
-            )
-
-        return cross_cutting
-
-    def _prioritize_findings(self, findings: list[dict[str, Any]]) -> list[dict[str, Any]]:
-        """Sort findings by severity for prioritization."""
-        severity_order = {"critical": 0, "high": 1, "medium": 2, "low": 3, "info": 4}
-
-        return sorted(
-            findings,
-            key=lambda f: (
-                severity_order.get(f.get("severity", "medium"), 2),
-                f.get("source_agent", ""),
-            ),
-        )
-
-    def _elevate_critical_findings(
-        self,
-        prioritized_findings: list[dict[str, Any]],
-        overall_score: float,
-    ) -> list[dict[str, Any]]:
-        """Elevate findings to critical_gaps based on severity and score.
-
-        TSK-304.1: Implements score-aware elevation:
-        - CRITICAL severity → always add to critical_gaps
-        - HIGH severity with score < 40 → add to critical_gaps
-        - Track finding source (agent name) for auditability
-
-        Args:
-            prioritized_findings: Findings sorted by severity.
-            overall_score: The calculated overall audit score.
-
-        Returns:
-            List of elevated critical gaps (max 10).
-        """
-        elevated: list[dict[str, Any]] = []
-        elevated_index: dict[tuple[Any, ...], int] = {}
-        source_sets: dict[tuple[Any, ...], set[str]] = {}
-        candidate_count = 0
-
-        for finding in prioritized_findings:
-            severity = self._normalize_severity(finding)
-
-            # CRITICAL always elevated
-            should_elevate = severity == "critical"
-
-            # HIGH elevated when score < 40 (poor audit result)
-            if severity == "high" and overall_score < 40:
-                should_elevate = True
-
-            if should_elevate:
-                candidate_count += 1
-                title = finding.get("title") or finding.get("description") or finding.get("summary") or "Unknown issue"
-                normalized_title = self._normalize_title_for_dedupe(title)
-                elevated_reason = "critical_severity" if severity == "critical" else "high_with_low_score"
-                source_agent = str(finding.get("source_agent", "unknown"))
-                key = (
-                    str(finding.get("type", "unknown")).lower(),
-                    str(finding.get("location", "unknown")).lower(),
-                    normalized_title,
-                    severity,
-                    elevated_reason,
-                )
-                source_sets.setdefault(key, set()).add(source_agent)
-
-                if key in elevated_index:
-                    continue
-
-                elevated_index[key] = len(elevated)
-                elevated.append(
-                    {
-                        "title": title,
-                        "type": finding.get("type", "unknown"),
-                        "severity": severity,
-                        "location": finding.get("location", "unknown"),
-                        "source_agent": source_agent,
-                        "impact": self._assess_impact(finding),
-                        "elevated_reason": elevated_reason,
-                    }
-                )
-
-                # Keep per-item elevation diagnostics at debug level to avoid
-                # flooding run logs when a repository has many similar findings.
-                self.logger.debug(
-                    "synthesis_agent_critical_elevated",
-                    finding_type=finding.get("type"),
-                    severity=severity,
-                    source=source_agent,
-                    score=overall_score,
-                )
-
-        for item in elevated:
-            key = (
-                str(item.get("type", "unknown")).lower(),
-                str(item.get("location", "unknown")).lower(),
-                self._normalize_title_for_dedupe(str(item.get("title", "Unknown issue"))),
-                str(item.get("severity", "medium")).lower(),
-                str(item.get("elevated_reason", "")),
-            )
-            item["source_agents"] = sorted(source_sets.get(key, {str(item.get("source_agent", "unknown"))}))
-
-        # Limit to top 10 by severity + impact
-        deduped_count = len(elevated)
-        elevated = elevated[:10]
-
-        self.logger.info(
-            "synthesis_agent_elevation_complete",
-            total_findings=len(prioritized_findings),
-            candidate_count=candidate_count,
-            deduped_count=deduped_count,
-            elevated_count=len(elevated),
-            score=overall_score,
-        )
-
-        return elevated
-
-    def _normalize_title_for_dedupe(self, value: str) -> str:
-        """Normalize finding title/description for stable deduplication."""
-        normalized = str(value or "").strip().lower()
-        # Collapse prompt-introduced wrappers that duplicate the same base issue text.
-        for prefix in ("potential security issue:", "potential issue:", "issue:"):
-            if normalized.startswith(prefix):
-                normalized = normalized[len(prefix) :].strip()
-        return normalized
-
-    def _generate_coherent_recommendations(
-        self,
-        score: float,
-        critical_gaps: list[dict[str, Any]],
-    ) -> tuple[str, list[dict[str, Any]]]:
-        """Generate recommendations that are coherent with the score.
-
-        TSK-304.2: Ensures recommendations match score severity:
-        - Score 0-30: "CRITICAL: Immediate action required..."
-        - Score 31-50: "HIGH PRIORITY: Address within 2 weeks..."
-        - Score 51-70: "MEDIUM: Schedule for next sprint..."
-        - Score 71-100: "MAINTENANCE: Continue monitoring..."
-
-        Args:
-            score: Overall audit score (0-100).
-            critical_gaps: List of critical gaps identified.
-
-        Returns:
-            Tuple of (severity_prefix, base_recommendations).
-        """
-        # Determine severity prefix based on score
-        if score <= 30:
-            prefix = "CRITICAL"
-            urgency = "Immediate action required. Address these issues before any new development."
-            base_priority = "critical"
-        elif score <= 50:
-            prefix = "HIGH PRIORITY"
-            urgency = "Address within 2 weeks. These issues pose significant risk."
-            base_priority = "high"
-        elif score <= 70:
-            prefix = "MEDIUM"
-            urgency = "Schedule for next sprint. Plan improvements systematically."
-            base_priority = "medium"
-        else:
-            prefix = "MAINTENANCE"
-            urgency = "Continue monitoring. Current practices are working well."
-            base_priority = "low"
-
-        recommendations: list[dict[str, Any]] = []
-
-        # Generate recommendations based on critical gaps
-        if critical_gaps:
-            gap_types = {g.get("type", "unknown") for g in critical_gaps}
-
-            if any("security" in t for t in gap_types):
-                recommendations.append(
-                    {
-                        "priority": base_priority,
-                        "title": f"{prefix}: Address security vulnerabilities",
-                        "description": urgency + " Security issues detected that need remediation.",
-                        "category": "security",
-                        "effort": "high" if score <= 50 else "medium",
-                    }
-                )
-
-            if any(t in ("technical_debt", "code_quality") for t in gap_types):
-                recommendations.append(
-                    {
-                        "priority": base_priority,
-                        "title": f"{prefix}: Reduce technical debt",
-                        "description": urgency + " Code quality issues impacting maintainability.",
-                        "category": "code",
-                        "effort": "medium",
-                    }
-                )
-
-            if any("doc" in t for t in gap_types):
-                recommendations.append(
-                    {
-                        "priority": base_priority,
-                        "title": f"{prefix}: Improve documentation",
-                        "description": urgency + " Documentation gaps affecting team productivity.",
-                        "category": "docs",
-                        "effort": "low",
-                    }
-                )
-
-        self.logger.info(
-            "synthesis_agent_recommendations_generated",
-            score=score,
-            severity_prefix=prefix,
-            recommendation_count=len(recommendations),
-        )
-
-        return prefix, recommendations
-
-    def _validate_synthesis_coherence(
-        self,
-        score: float,
-        critical_gaps: list[dict[str, Any]],
-        recommendations: list[dict[str, Any]],
-        executive_summary: str,
-    ) -> bool:
-        """Validate that synthesis output is internally coherent.
-
-        TSK-304.4: Ensures no contradictory statements:
-        - Low score should not have "continue current practices" recommendation
-        - High gap count should be reflected in summary
-
-        Args:
-            score: Overall audit score.
-            critical_gaps: List of critical gaps.
-            recommendations: Generated recommendations.
-            executive_summary: Executive summary text.
-
-        Returns:
-            True if coherent, False if contradictions detected.
-        """
-        coherent = True
-
-        # Check 1: Low score should not have positive-only recommendations
-        if score <= 30:
-            positive_phrases = ["continue current", "maintain existing", "well positioned"]
-            summary_lower = executive_summary.lower()
-            for phrase in positive_phrases:
-                if phrase in summary_lower:
-                    self.logger.warning(
-                        "synthesis_coherence_violation",
-                        issue="positive_summary_with_low_score",
-                        score=score,
-                        phrase=phrase,
-                    )
-                    coherent = False
-
-        # Check 2: Many critical gaps should be reflected
-        if len(critical_gaps) >= 5 and "critical" not in executive_summary.lower():
-            self.logger.warning(
-                "synthesis_coherence_violation",
-                issue="many_gaps_not_mentioned",
-                gap_count=len(critical_gaps),
-            )
-            # This is a warning, not a failure
-            pass
-
-        self.logger.info(
-            "synthesis_agent_output_validated",
-            coherence_check="passed" if coherent else "failed",
-            score=score,
-            critical_gaps=len(critical_gaps),
-        )
-
-        return coherent
-
-    def _extract_critical_gaps(self, prioritized_findings: list[dict[str, Any]]) -> list[dict[str, Any]]:
-        """Extract findings that represent critical gaps.
-
-        Note: For score-aware elevation, use _elevate_critical_findings instead.
-        This method is kept for backward compatibility.
-        """
-        critical_gaps: list[dict[str, Any]] = []
-        candidate_count = 0
-
-        for finding in prioritized_findings:
-            severity = self._normalize_severity(finding)
-            if severity in ("critical", "high"):
-                candidate_count += 1
-                title = finding.get("title") or finding.get("description") or finding.get("summary") or "Unknown issue"
-                critical_gaps.append(
-                    {
-                        "title": title,
-                        "type": finding.get("type", "unknown"),
-                        "severity": severity,
-                        "location": finding.get("location", "unknown"),
-                        "source_agent": finding.get("source_agent", "unknown"),
-                        "impact": self._assess_impact(finding),
-                    }
-                )
-
-        def _gap_key(gap: dict[str, Any]) -> tuple[Any, ...]:
-            return (
-                str(gap.get("type", "")).lower(),
-                str(gap.get("location", "")).lower(),
-                str(gap.get("title", "")).lower(),
-            )
-
-        deduped = self._dedupe_items(critical_gaps, _gap_key, label="critical_gaps")
-        self.logger.info(
-            "critical_gaps_extracted",
-            candidate_count=candidate_count,
-            deduped_count=len(deduped),
-        )
-        return deduped
-
-    def _assess_impact(self, finding: dict[str, Any]) -> str:
-        """Assess the business impact of a finding."""
-        finding_type = finding.get("type", "")
-
-        impact_map = {
-            "security_vulnerability": "High risk of security breach or data exposure",
-            "security_risk": "Potential security weakness that could be exploited",
-            "technical_debt": "Increased maintenance burden and reduced velocity",
-            "doc_quality": "Knowledge gaps affecting team productivity",
-        }
-
-        return impact_map.get(finding_type, "Potential quality or compliance issue")
-
-    def _extract_aligned_practices(self, agent_results: list[AgentResult]) -> list[dict[str, Any]]:
-        """Extract areas where the repository follows good practices."""
-        aligned: list[dict[str, Any]] = []
-
-        for result in agent_results:
-            if not result.success:
-                continue
-
-            # Agents with no critical/high findings are aligned
-            critical_count = sum(1 for f in result.findings if self._normalize_severity(f) in ("critical", "high"))
-
-            if critical_count == 0:
-                aligned.append(
-                    {
-                        "domain": result.agent_name.replace("Agent", ""),
-                        "status": "Aligned",
-                        "description": f"No critical issues found in {result.agent_name} analysis",
-                        "finding_count": len(result.findings),
-                    }
-                )
-
-        return aligned
-
-    def _calculate_overall_score(
-        self,
-        agent_scores: dict[str, float],
-        critical_gaps: list[dict[str, Any]],
-    ) -> float:
-        """Calculate overall maturity score."""
-        if not agent_scores:
-            return 0.0
-
-        # Weighted average of agent scores
-        weights = {
-            "SecurityAgent": 0.35,
-            "CodeAnalysisAgent": 0.35,
-            "DocumentationAgent": 0.30,
-        }
-
-        weighted_sum = 0.0
-        total_weight = 0.0
-
-        for agent, score in agent_scores.items():
-            weight = weights.get(agent, 0.25)
-            weighted_sum += score * weight
-            total_weight += weight
-
-        base_score = weighted_sum / total_weight if total_weight > 0 else 0.0
-
-        # Apply penalty for critical gaps
-        critical_count = sum(1 for g in critical_gaps if g.get("severity") == "critical")
-        high_count = sum(1 for g in critical_gaps if g.get("severity") == "high")
-
-        penalty = (critical_count * 10) + (high_count * 5)
-        final_score = max(0.0, base_score - penalty)
-
-        return round(final_score, 2)
-
-    def _determine_maturity_level(self, score: float) -> str:
-        """Determine maturity level from overall score."""
-        if score <= 25:
-            return MaturityLevel.CRITICAL.value
-        elif score <= 50:
-            return MaturityLevel.DEVELOPING.value
-        elif score <= 75:
-            return MaturityLevel.ESTABLISHED.value
-        elif score <= 90:
-            return MaturityLevel.OPTIMIZING.value
-        else:
-            return MaturityLevel.LEADING.value
-
-    async def _generate_recommendations(
-        self,
-        repository: str,
-        critical_gaps: list[dict[str, Any]],
-        cross_cutting: list[dict[str, Any]],
-        maturity_level: str,
-    ) -> list[dict[str, Any]]:
-        """Generate prioritized recommendations based on findings."""
-        recommendations: list[dict[str, Any]] = []
-        llm_count = 0
-        rule_count = 0
-        cross_cutting_count = 0
-        fallback_cause: SynthesisFallbackCause | None = None
-
-        # Use PydanticAI agent if LLM is available
-        if self.settings.enabled and critical_gaps:
-            try:
-                llm_recommendations = await self._get_llm_recommendations(
-                    repository=repository,
-                    critical_gaps=critical_gaps,
-                    cross_cutting=cross_cutting,
-                    maturity_level=maturity_level,
-                )
-                llm_count = len(llm_recommendations)
-                recommendations.extend(llm_recommendations)
-                if not llm_recommendations:
-                    fallback_cause = SynthesisFallbackCause.EMPTY_LLM_OUTPUT
-                    self.logger.info(
-                        "llm_recommendations_empty", repository=repository, fallback_cause=fallback_cause.value
-                    )
-                    fallback = self._get_rule_based_recommendations(critical_gaps, maturity_level)
-                    rule_count = len(fallback)
-                    recommendations.extend(fallback)
-            except Exception as e:
-                # Phase 166: Classify the failure cause for structured telemetry.
-                fallback_cause = self._classify_synthesis_fallback_cause(e)
-                self.logger.warning("llm_recommendations_failed", error=str(e), fallback_cause=fallback_cause.value)
-                # Fall back to rule-based recommendations
-                fallback = self._get_rule_based_recommendations(critical_gaps, maturity_level)
-                rule_count = len(fallback)
-                recommendations.extend(fallback)
-        else:
-            # Rule-based recommendations when LLM not available
-            fallback = self._get_rule_based_recommendations(critical_gaps, maturity_level)
-            rule_count = len(fallback)
-            recommendations.extend(fallback)
-
-        # Add cross-cutting concern recommendations
-        for concern in cross_cutting:
-            priority = "high"
-            concern_severity = str(concern.get("severity", "")).lower()
-            if concern_severity not in ("critical", "high"):
-                has_high = any(
-                    self._normalize_severity(f) in ("critical", "high")
-                    for f in concern.get("findings", [])
-                    if isinstance(f, dict)
-                )
-                priority = "high" if has_high else "medium"
-
-            if priority == "high" or critical_gaps:
-                recommendations.append(
-                    {
-                        "priority": priority,
-                        "title": f"Address cross-cutting issues at {concern.get('location', 'multiple locations')}",
-                        "description": concern.get("description", ""),
-                        "category": "cross_cutting",
-                        "effort": "medium",
-                    }
-                )
-                cross_cutting_count += 1
-
-        normalized: list[dict[str, Any]] = []
-        dropped = 0
-        for rec in recommendations:
-            normalized_rec = self._normalize_recommendation(rec)
-            if normalized_rec is None:
-                dropped += 1
-                continue
-            normalized.append(normalized_rec)
-
-        def _rec_key(rec: dict[str, Any]) -> tuple[Any, ...]:
-            return (
-                str(rec.get("title", "")).lower(),
-                str(rec.get("category", "")).lower(),
-            )
-
-        normalized = self._dedupe_items(normalized, _rec_key, label="recommendations")
-
-        # Sort by priority
-        priority_order = {"critical": 0, "high": 1, "medium": 2, "low": 3}
-        normalized.sort(key=lambda r: priority_order.get(r.get("priority", "medium"), 2))
-
-        trimmed = 0
-        if len(normalized) > 5:
-            trimmed = len(normalized) - 5
-            normalized = normalized[:5]
-
-        self.logger.info(
-            "recommendations_generated",
-            repository=repository,
-            llm_count=llm_count,
-            rule_count=rule_count,
-            cross_cutting_count=cross_cutting_count,
-            dropped_count=dropped,
-            final_count=len(normalized),
-            trimmed_count=trimmed,
-            fallback_cause=fallback_cause.value if fallback_cause else None,
-        )
-
-        return normalized
-
-    def _normalize_recommendation(self, rec: dict[str, Any]) -> dict[str, Any] | None:
-        """Normalize recommendation fields and drop invalid entries."""
-        if not isinstance(rec, dict):
-            return None
-        title = str(rec.get("title", "")).strip()
-        description = str(rec.get("description", "")).strip()
-        if not title or not description:
-            return None
-
-        priority = str(rec.get("priority", "medium")).lower()
-        if priority not in ("critical", "high", "medium", "low"):
-            priority = "medium"
-
-        category = str(rec.get("category", "process")).lower()
-        if category not in ("security", "code", "docs", "process", "cross_cutting"):
-            category = "process"
-
-        effort = str(rec.get("effort", "medium")).lower()
-        if effort not in ("low", "medium", "high"):
-            effort = "medium"
-
-        normalized = dict(rec)
-        normalized.update(
-            {
-                "title": title,
-                "description": description,
-                "priority": priority,
-                "category": category,
-                "effort": effort,
-            }
-        )
-        return normalized
-
-    async def _get_llm_recommendations(
-        self,
-        repository: str,
-        critical_gaps: list[dict[str, Any]],
-        cross_cutting: list[dict[str, Any]],
-        maturity_level: str,
-    ) -> list[dict[str, Any]]:
-        """Use PydanticAI agent to generate intelligent recommendations."""
-        evidence_context = ""
-        if self._evidence_corpus:
-            evidence_context = "\n\n" + self._evidence_corpus.get_context_summary(max_chars=2500)
-
-        user_prompt = f"""Repository: {repository}
-Maturity Level: {maturity_level}
-
-Critical Gaps:
-{json.dumps(critical_gaps[:10], indent=2)}
-
-Cross-Cutting Concerns:
-{json.dumps(cross_cutting[:5], indent=2)}
-
-Generate prioritized recommendations to improve this repository.{evidence_context}"""
-
-        # Build dependencies for the agent using AuditDeps
-        deps = build_deps(
-            settings=self.settings,
-            repo_path=repository,
-            project_id=repository,
-            profile={"maturity_level": maturity_level},
-            evidence_corpus=self._evidence_corpus,
-        )
-
-        try:
-            output = await self._run_pydantic_agent(
-                system_prompt=_RECOMMENDATIONS_SYSTEM_PROMPT,
-                user_prompt=user_prompt,
-                result_type=RecommendationsResult,
-                complexity="complex",
-                deps=deps,
-            )
-            return [rec.model_dump() for rec in output.recommendations]
-        except Exception as e:
-            fallback_cause = self._classify_synthesis_fallback_cause(e)
-            self.logger.warning("llm_parse_failed", error=str(e), fallback_cause=fallback_cause.value)
-            return []
-
-    def _get_rule_based_recommendations(
-        self,
-        critical_gaps: list[dict[str, Any]],
-        maturity_level: str,
-    ) -> list[dict[str, Any]]:
-        """Generate rule-based recommendations without LLM."""
-        recommendations: list[dict[str, Any]] = []
-
-        # Security-related recommendations
-        security_gaps = [g for g in critical_gaps if "security" in g.get("type", "").lower()]
-        if security_gaps:
-            sec_count = len(security_gaps)
-            recommendations.append(
-                {
-                    "priority": "critical",
-                    "title": "Address security vulnerabilities immediately",
-                    "description": f"Found {sec_count} security issues requiring immediate attention",
-                    "category": "security",
-                    "effort": "high",
-                }
-            )
-
-        # Technical debt recommendations
-        debt_gaps = [g for g in critical_gaps if g.get("type") == "technical_debt"]
-        if debt_gaps:
-            recommendations.append(
-                {
-                    "priority": "high",
-                    "title": "Reduce technical debt",
-                    "description": f"Address {len(debt_gaps)} technical debt items to improve maintainability",
-                    "category": "code",
-                    "effort": "medium",
-                }
-            )
-
-        # Maturity-level specific recommendations
-        if maturity_level in (MaturityLevel.CRITICAL.value, MaturityLevel.DEVELOPING.value):
-            recommendations.append(
-                {
-                    "priority": "high",
-                    "title": "Establish baseline practices",
-                    "description": "Focus on establishing fundamental practices before optimization",
-                    "category": "process",
-                    "effort": "medium",
-                }
-            )
-
-        return recommendations
-
-    async def _generate_executive_summary(
-        self,
-        repository: str,
-        overall_score: float,
-        maturity_level: str,
-        critical_gaps: list[dict[str, Any]],
-        aligned_practices: list[dict[str, Any]],
-        agent_results: list[AgentResult],
-    ) -> str:
-        """Generate an executive summary of the audit."""
-        # Use PydanticAI agent if available
-        summary_fallback_cause: SynthesisFallbackCause | None = None
-        if self.settings.enabled:
-            try:
-                summary = await self._get_llm_summary(
-                    repository=repository,
-                    overall_score=overall_score,
-                    maturity_level=maturity_level,
-                    critical_gaps=critical_gaps,
-                    aligned_practices=aligned_practices,
-                    agent_results=agent_results,
-                )
-                self.logger.info(
-                    "executive_summary_generated",
-                    repository=repository,
-                    source="llm",
-                    fallback_cause=None,
-                )
-                return summary
-            except Exception as e:
-                summary_fallback_cause = self._classify_synthesis_fallback_cause(e)
-                self.logger.warning("llm_summary_failed", error=str(e), fallback_cause=summary_fallback_cause.value)
-
-        # Fallback to template-based summary
-        template_summary = self._get_template_summary(
-            repository=repository,
-            overall_score=overall_score,
-            maturity_level=maturity_level,
-            critical_gaps=critical_gaps,
-            aligned_practices=aligned_practices,
-        )
-        self.logger.info(
-            "executive_summary_generated",
-            repository=repository,
-            source="template",
-            fallback_cause=summary_fallback_cause.value if summary_fallback_cause else None,
-        )
-        return template_summary
-
-    async def _get_llm_summary(
-        self,
-        repository: str,
-        overall_score: float,
-        maturity_level: str,
-        critical_gaps: list[dict[str, Any]],
-        aligned_practices: list[dict[str, Any]],
-        agent_results: list[AgentResult],
-    ) -> str:
-        """Use PydanticAI agent to generate executive summary."""
-        agents_summary = ", ".join(f"{r.agent_name}: {len(r.findings)} findings" for r in agent_results if r.success)
-        evidence_context = ""
-        if self._evidence_corpus:
-            evidence_context = "\n\n" + self._evidence_corpus.get_context_summary(max_chars=2500)
-
-        user_prompt = f"""Repository: {repository}
-Overall Score: {overall_score}/100
-Maturity Level: {maturity_level}
-
-Agents Analyzed: {agents_summary}
-
-Critical Gaps ({len(critical_gaps)}):
-{json.dumps([g.get("title") for g in critical_gaps[:5]], indent=2)}
-
-Aligned Practices ({len(aligned_practices)}):
-{json.dumps([a.get("domain") for a in aligned_practices], indent=2)}
-
-Write an executive summary for stakeholders.{evidence_context}"""
-
-        # Build dependencies for the agent using AuditDeps
-        deps = build_deps(
-            settings=self.settings,
-            repo_path=repository,
-            project_id=repository,
-            profile={"maturity_level": maturity_level, "overall_score": overall_score},
-            evidence_corpus=self._evidence_corpus,
-        )
-
-        result = await self._run_pydantic_agent(
-            system_prompt=_EXECUTIVE_SUMMARY_SYSTEM_PROMPT,
-            user_prompt=user_prompt,
-            result_type=ExecutiveSummaryResult,
-            complexity="standard",
-            deps=deps,
-        )
-        return result.summary
-
-    def _classify_synthesis_fallback_cause(self, exc: Exception) -> SynthesisFallbackCause:
-        """Phase 166: Classify the cause of synthesis fallback for structured telemetry."""
-        # Precise type check before string matching to avoid false positives.
-        if isinstance(exc, ValidationError):
-            return SynthesisFallbackCause.PARSE_VALIDATION_FAILED
-        message = str(exc).lower()
-        # Check for provider-route or failover exhaustion signals
-        if "provider_route_unavailable" in message or "no credentials for provider" in message:
-            return SynthesisFallbackCause.FAILOVER_EXHAUSTED
-        if "failover_exhausted" in message or "timeout_failover_exhausted" in message:
-            return SynthesisFallbackCause.FAILOVER_EXHAUSTED
-        if "retry_exhausted" in message or "provider_retry_exhausted" in message:
-            return SynthesisFallbackCause.RETRY_EXHAUSTED
-        # Check for terminal auth
-        if (
-            "authentication" in message
-            or "unauthorized" in message
-            or "forbidden" in message
-            or "invalid api key" in message
-        ):
-            return SynthesisFallbackCause.TERMINAL_AUTH
-        # Check for parse/validation failures via message when not a typed ValidationError
-        if "validationerror" in message or "json decode" in message or "unexpected model" in message:
-            return SynthesisFallbackCause.PARSE_VALIDATION_FAILED
-        # Default: retry exhausted (most common unclassified case)
-        return SynthesisFallbackCause.RETRY_EXHAUSTED
-
-    def _get_template_summary(
-        self,
-        repository: str,
-        overall_score: float,
-        maturity_level: str,
-        critical_gaps: list[dict[str, Any]],
-        aligned_practices: list[dict[str, Any]],
-    ) -> str:
-        """Generate template-based summary without LLM."""
-        gap_count = len(critical_gaps)
-        aligned_count = len(aligned_practices)
-
-        severity_status = (
-            "requires immediate attention"
-            if overall_score < 50
-            else ("shows room for improvement" if overall_score < 75 else "demonstrates strong practices")
-        )
-
-        if gap_count > 0:
-            recommendation = "Prioritize addressing security and high-severity issues."
-        elif overall_score < 50:
-            recommendation = "Investigate low-score drivers and close evidence or coverage gaps before proceeding."
-        elif overall_score < 75:
-            recommendation = "Plan medium-priority improvements and re-evaluate in the next sprint."
-        else:
-            recommendation = "Continue current practices while monitoring for issues."
-
-        summary = f"The repository scored {overall_score}/100, "
-        summary += f"placing it at the **{maturity_level}** maturity level. "
-        summary += f"This assessment {severity_status}."
-
-        return f"""**Audit Summary for {repository}**
-
-{summary}
-
-**Key Findings:**
-- {gap_count} critical gap(s) identified requiring attention
-- {aligned_count} domain(s) showing aligned practices
-
-**Recommendation:** {recommendation}"""