@ngocsangairvds/vsaf 3.2.13 → 3.2.15

package/tools/vds-scripts/audit_orchestrator/src/vds_audit_orchestrator/engine/readiness_synthesizer.py

@@ -1,730 +0,0 @@
-"""LLM-based readiness report synthesis (Phase 85 WP-85.3).
-
-Single LLM call per repo produces a complete ReadinessReport.
-Single LLM call per project produces a ProjectReadinessReport.
-"""
-
-from __future__ import annotations
-
-import json
-from collections.abc import Callable
-from typing import TYPE_CHECKING
-
-import structlog
-
-from vds_audit_orchestrator.models.readiness import (
-    ChecklistDriftSummary,
-    ClassificationTier,
-    ExecutiveSummary,
-    ProjectReadinessReport,
-    ReadinessReport,
-    RepoReadinessSummary,
-    SeverityLevel,
-)
-
-if TYPE_CHECKING:
-    from pydantic import BaseModel
-
-    from vds_audit_orchestrator.engine.readiness_extractor import ReadinessContext
-
-logger = structlog.get_logger(__name__)
-
-_MAX_ROWS_IN_PROMPT = 50
-
-# ---------------------------------------------------------------------------
-# System prompt constants (TSK-850.9)
-# ---------------------------------------------------------------------------
-
-READINESS_REPO_SYSTEM_PROMPT = """\
-You are a software quality assessment expert. Generate a packaging readiness report in Vietnamese.
-
-Report Structure:
-1. Tóm tắt điều hành (Executive Summary) - classification tier, score, confidence, narrative
-2. Ma trận mức độ nghiêm trọng (Severity Matrix) - P0/P1/P2 items with consequences
-3. Dự báo cải thiện (Improvement Forecast) - action groups with effort and projected impact
-4. Khuyến nghị (Recommendations) - short-term and long-term action items
-5. Ghi chú chất lượng dữ liệu (Data Quality Notes) - insufficient data and conflicting evidence flags
-6. Tóm tắt thay đổi checklist (Checklist Drift Summary) - requirement changes since prior run (if provided)
-
-Classification Tiers:
-- commercially_ready: Score >= 80%, no P0 issues
-- internally_ready: Score >= 60%, no more than 2 P0 issues
-- in_progress: Score >= 40%
-- not_ready: Score < 40% or critical blocking issues
-
-Severity:
-- P0_CRITICAL: Blocks packaging/deployment
-- P1_HIGH: Significant risk requiring immediate attention
-- P2_MEDIUM: Improvement opportunity
-
-Reporting Principles:
-- Insufficient data -> reduced confidence, NEVER fabricated assessment
-- Conflicting evidence -> resolve using priority: Log > Code > Documentation
-- All narrative fields MUST be in Vietnamese
-
-Expected JSON output:
-{
-  "executive_summary": {
-    "readiness_score_pct": <float 0-100>,
-    "classification": "<commercially_ready|internally_ready|in_progress|not_ready>",
-    "confidence": "<LOW|MEDIUM|HIGH>",
-    "confidence_pct": <float 0-100>,
-    "general_assessment": "<Vietnamese narrative>"
-  },
-  "heatmap_weakest_categories": ["<category1>"],
-  "top_critical_issues": ["<issue1>"],
-  "severity_matrix": [
-    {
-      "category": "<category>",
-      "sub_criterion": "<sub_criterion>",
-      "key_issue": "<Vietnamese description>",
-      "severity": "<P0_CRITICAL|P1_HIGH|P2_MEDIUM>",
-      "consequence": "<Vietnamese consequence>"
-    }
-  ],
-  "improvement_forecast": [
-    {
-      "action_group": "<group name>",
-      "estimated_effort": "<effort description>",
-      "expected_score_increase_pct": <float>,
-      "projected_score_after_pct": <float 0-100>
-    }
-  ],
-  "total_potential_score_pct": <float 0-100>,
-  "short_term_recommendations": [
-    {"category": "<cat>", "action": "<Vietnamese action>", "timeframe": "<time>", "score_impact": "<impact>"}
-  ],
-  "long_term_recommendations": [
-    {"category": "<cat>", "action": "<Vietnamese action>", "timeframe": "<time>", "score_impact": "<impact>"}
-  ],
-  "validation_items": [
-    {
-      "rule": "<rule>",
-      "sub_criterion": "<sub>",
-      "issue_to_clarify": "<Vietnamese issue>",
-      "proposed_action": "<Vietnamese action>",
-      "score_impact": "<impact>"
-    }
-  ],
-  "reporting_principles": {
-    "insufficient_data_handling": "<description>",
-    "evidence_priority": "Log > Code > Documentation"
-  }
-}
-
-Return ONLY the JSON object, no additional text.
-"""
-
-READINESS_PROJECT_SYSTEM_PROMPT = """\
-You are a software quality assessment expert. Generate a project-level packaging readiness report \
-in Vietnamese by aggregating multiple repository readiness reports.
-
-Report Structure:
-1. Tóm tắt điều hành (Executive Summary) - aggregate classification, weighted score, confidence, narrative
-2. Ma trận mức độ nghiêm trọng (Severity Matrix) - cross-repo P0/P1/P2 patterns
-3. Dự báo cải thiện (Improvement Forecast) - project-wide improvement actions
-4. Khuyến nghị (Recommendations) - short-term and long-term project actions
-5. Ghi chú chất lượng dữ liệu (Data Quality Notes) - cross-repo data quality observations
-6. Tóm tắt thay đổi checklist (Checklist Drift Summary) - requirement changes since prior run (if provided)
-
-Classification Tiers:
-- commercially_ready: Score >= 80%, no P0 issues across all repos
-- internally_ready: Score >= 60%, no more than 2 P0 issues total
-- in_progress: Score >= 40%
-- not_ready: Score < 40% or critical blocking issues
-
-Severity:
-- P0_CRITICAL: Blocks packaging/deployment
-- P1_HIGH: Significant risk requiring immediate attention
-- P2_MEDIUM: Improvement opportunity
-
-Reporting Principles:
-- Insufficient data -> reduced confidence, NEVER fabricated assessment
-- Conflicting evidence -> resolve using priority: Log > Code > Documentation
-- All narrative fields MUST be in Vietnamese
-- Identify cross-repo patterns: common weaknesses, shared improvements
-
-Expected JSON output:
-{
-  "executive_summary": {
-    "readiness_score_pct": <float 0-100>,
-    "classification": "<commercially_ready|internally_ready|in_progress|not_ready>",
-    "confidence": "<LOW|MEDIUM|HIGH>",
-    "confidence_pct": <float 0-100>,
-    "general_assessment": "<Vietnamese narrative>"
-  },
-  "repo_readiness": [
-    {"name": "<repo>", "score": <float 0-100>, "classification": "<tier>", "top_issues": ["<issue>"]}
-  ],
-  "cross_repo_severity_matrix": [
-    {
-      "category": "<category>",
-      "sub_criterion": "<sub>",
-      "key_issue": "<Vietnamese>",
-      "severity": "<P0_CRITICAL|P1_HIGH|P2_MEDIUM>",
-      "consequence": "<Vietnamese>"
-    }
-  ],
-  "improvement_forecast": [
-    {
-      "action_group": "<group>",
-      "estimated_effort": "<effort>",
-      "expected_score_increase_pct": <float>,
-      "projected_score_after_pct": <float 0-100>
-    }
-  ],
-  "short_term_recommendations": [
-    {"category": "<cat>", "action": "<Vietnamese action>", "timeframe": "<time>", "score_impact": "<impact>"}
-  ],
-  "long_term_recommendations": [
-    {"category": "<cat>", "action": "<Vietnamese action>", "timeframe": "<time>", "score_impact": "<impact>"}
-  ],
-  "data_quality_notes": ["<Vietnamese observation>"]
-}
-
-Return ONLY the JSON object, no additional text.
-"""
-
-
-# ---------------------------------------------------------------------------
-# Helpers
-# ---------------------------------------------------------------------------
-
-
-def _derive_classification(score_pct: float, p0_count: int) -> ClassificationTier:
-    """Derive classification tier from score and P0 issue count."""
-    if score_pct >= 80 and p0_count == 0:
-        return ClassificationTier.commercially_ready
-    if score_pct >= 60 and p0_count <= 2:
-        return ClassificationTier.internally_ready
-    if score_pct >= 40:
-        return ClassificationTier.in_progress
-    return ClassificationTier.not_ready
-
-
-def _extract_json_text(raw: str) -> str:
-    """Extract JSON string from raw LLM output, handling markdown fences."""
-    text = raw.strip()
-    if "```json" in text:
-        start = text.find("```json") + 7
-        end = text.find("```", start)
-        if end > start:
-            return text[start:end].strip()
-    if "```" in text:
-        start = text.find("```") + 3
-        end = text.find("```", start)
-        if end > start:
-            return text[start:end].strip()
-    return text
-
-
-# ---------------------------------------------------------------------------
-# Synthesizer
-# ---------------------------------------------------------------------------
-
-
-class ReadinessSynthesizer:
-    """LLM-based readiness report synthesizer.
-
-    Accepts an ``llm_call`` callable with the signature
-    ``(system_prompt: str, user_prompt: str) -> str`` so the actual LLM
-    transport is fully injectable -- making unit testing trivial with mocks.
-    """
-
-    def __init__(self, llm_call: Callable[[str, str], str]) -> None:
-        """Initialise with an LLM callable.
-
-        Args:
-            llm_call: ``callable(system_prompt, user_prompt) -> raw_text``.
-                      Must raise on transport / auth errors.
-        """
-        self._llm_call = llm_call
-
-    # ------------------------------------------------------------------
-    # Public API
-    # ------------------------------------------------------------------
-
-    def synthesize_repo(
-        self,
-        context: ReadinessContext,
-        product_name: str,
-        version: str,
-        *,
-        checklist_drift: ChecklistDriftSummary | None = None,
-    ) -> ReadinessReport:
-        """Synthesize a ReadinessReport from extraction context via single LLM call.
-
-        Args:
-            context: Extraction context with row data, scores, etc.
-            product_name: Repository / product name.
-            version: Template version string.
-            checklist_drift: Optional drift summary from Phase 114 drift
-                detection.  When provided the drift data is included in the
-                LLM prompt so the model can factor requirement changes into
-                the readiness narrative (FR-114.9, AC-114.9.2).
-
-        Error handling:
-        - JSON parse failure: 1 structured repair retry.
-        - Pydantic validation failure after repair: partial report.
-        - LLM transport / auth failure: fail fast (synthesis_failed).
-        - Empty response: fail fast (synthesis_failed).
-        """
-        if checklist_drift is not None:
-            logger.info(
-                "readiness_synthesis_with_drift",
-                product=product_name,
-                drift_detection_enabled=checklist_drift.drift_detection_enabled,
-                any_drift_detected=checklist_drift.any_drift_detected,
-                rows_major_change=checklist_drift.rows_major_change,
-                rows_breaking_change=checklist_drift.rows_breaking_change,
-                rows_added=checklist_drift.rows_added,
-                rows_removed=checklist_drift.rows_removed,
-                prior_run_id=checklist_drift.prior_run_id or None,
-            )
-
-        system = READINESS_REPO_SYSTEM_PROMPT
-        user = self._build_repo_user_prompt(context, checklist_drift=checklist_drift)
-
-        # -- Attempt LLM call --
-        try:
-            raw_text = self._llm_call(system, user)
-        except Exception:
-            logger.exception("readiness_llm_transport_error", product=product_name)
-            return self._failed_report(context, product_name, version)
-
-        if not raw_text or not raw_text.strip():
-            logger.warning("readiness_llm_empty_response", product=product_name)
-            return self._failed_report(context, product_name, version)
-
-        # -- First parse attempt --
-        report, error_msg = self._try_parse_repo(raw_text, product_name, version)
-        if report is not None:
-            return report
-
-        # -- Repair retry (1 attempt) --
-        repair_user = self._build_repair_prompt(user, error_msg)
-        try:
-            raw_text_2 = self._llm_call(system, repair_user)
-        except Exception:
-            logger.exception("readiness_llm_repair_transport_error", product=product_name)
-            return self._partial_report(context, product_name, version)
-
-        report, _ = self._try_parse_repo(raw_text_2, product_name, version)
-        if report is not None:
-            return report
-
-        return self._partial_report(context, product_name, version)
-
-    def synthesize_project(
-        self,
-        repo_reports: list[ReadinessReport],
-        project_name: str,
-        *,
-        checklist_drift: ChecklistDriftSummary | None = None,
-    ) -> ProjectReadinessReport:
-        """Synthesize a ProjectReadinessReport from per-repo reports via single LLM call.
-
-        Args:
-            repo_reports: Per-repo readiness reports to aggregate.
-            project_name: Human-readable project name.
-            checklist_drift: Optional aggregate drift summary across repos
-                (FR-114.9, AC-114.9.2).  When provided, drift counts are
-                appended to the project-level prompt context.
-
-        Same error handling contract as :meth:`synthesize_repo`.
-        """
-        if checklist_drift is not None:
-            logger.info(
-                "readiness_project_synthesis_with_drift",
-                project=project_name,
-                drift_detection_enabled=checklist_drift.drift_detection_enabled,
-                any_drift_detected=checklist_drift.any_drift_detected,
-                rows_major_change=checklist_drift.rows_major_change,
-                rows_breaking_change=checklist_drift.rows_breaking_change,
-                rows_added=checklist_drift.rows_added,
-                rows_removed=checklist_drift.rows_removed,
-                prior_run_id=checklist_drift.prior_run_id or None,
-            )
-
-        system = READINESS_PROJECT_SYSTEM_PROMPT
-        user = self._build_project_user_prompt(repo_reports, project_name, checklist_drift=checklist_drift)
-
-        # -- Attempt LLM call --
-        try:
-            raw_text = self._llm_call(system, user)
-        except Exception:
-            logger.exception("readiness_project_llm_transport_error", project=project_name)
-            return self._failed_project_report(repo_reports, project_name)
-
-        if not raw_text or not raw_text.strip():
-            logger.warning("readiness_project_llm_empty_response", project=project_name)
-            return self._failed_project_report(repo_reports, project_name)
-
-        # -- First parse --
-        report, error_msg = self._try_parse_project(raw_text, project_name)
-        if report is not None:
-            return report
-
-        # -- Repair retry --
-        repair_user = self._build_repair_prompt(user, error_msg, schema_model=ProjectReadinessReport)
-        try:
-            raw_text_2 = self._llm_call(system, repair_user)
-        except Exception:
-            logger.exception("readiness_project_llm_repair_transport_error", project=project_name)
-            return self._partial_project_report(repo_reports, project_name)
-
-        report, _ = self._try_parse_project(raw_text_2, project_name)
-        if report is not None:
-            return report
-
-        return self._partial_project_report(repo_reports, project_name)
-
-    # ------------------------------------------------------------------
-    # User prompt construction (TSK-850.10)
-    # ------------------------------------------------------------------
-
-    @staticmethod
-    def _build_repo_user_prompt(
-        context: ReadinessContext,
-        *,
-        checklist_drift: ChecklistDriftSummary | None = None,
-    ) -> str:
-        """Serialize ReadinessContext into structured user prompt text."""
-        parts: list[str] = []
-
-        # Summary statistics
-        parts.append("## Thong tin chung")
-        parts.append(f"- Repo: {context['repo_name']}")
-        parts.append(f"- Template: {context['template_name']} v{context['template_version']}")
-        parts.append(f"- Total rows: {context['total_rows']}")
-        parts.append(f"- weighted_score_pct: {context['weighted_score_pct']}%")
-        parts.append("")
-
-        # Status distribution
-        parts.append("## Status Distribution")
-        parts.append(json.dumps(context["status_distribution"], ensure_ascii=False))
-        parts.append("")
-
-        # Severity candidates
-        parts.append("## severity_candidates")
-        if context["severity_candidates"]:
-            parts.append(json.dumps(context["severity_candidates"], ensure_ascii=False, indent=2))
-        else:
-            parts.append("(none)")
-        parts.append("")
-
-        # Category heatmap
-        parts.append("## Category Heatmap")
-        if context["category_heatmap"]:
-            parts.append(json.dumps(context["category_heatmap"], ensure_ascii=False, indent=2))
-        else:
-            parts.append("(none)")
-        parts.append("")
-
-        # Low confidence rows
-        parts.append("## low_confidence_rows")
-        if context["low_confidence_rows"]:
-            parts.append(json.dumps(context["low_confidence_rows"], ensure_ascii=False, indent=2))
-        else:
-            parts.append("(none)")
-        parts.append("")
-
-        # Conflicting rows
-        parts.append("## conflicting_rows")
-        if context["conflicting_rows"]:
-            parts.append(json.dumps(context["conflicting_rows"], ensure_ascii=False, indent=2))
-        else:
-            parts.append("(none)")
-        parts.append("")
-
-        # Rows (truncated)
-        parts.append("## Row Data")
-        rows = context["rows"]
-        if len(rows) > _MAX_ROWS_IN_PROMPT:
-            parts.append(json.dumps(rows[:_MAX_ROWS_IN_PROMPT], ensure_ascii=False, indent=2))
-            parts.append(f"\n[Truncated: showing {_MAX_ROWS_IN_PROMPT} of {len(rows)} rows]")
-        else:
-            parts.append(json.dumps(rows, ensure_ascii=False, indent=2))
-
-        # Phase 114: Checklist drift summary (FR-114.9, AC-114.9.2)
-        if checklist_drift is not None:
-            parts.append("")
-            parts.append("## Checklist Drift Summary")
-            parts.append("Requirement changes detected since the prior run:")
-            drift_data = {
-                "drift_detection_enabled": checklist_drift.drift_detection_enabled,
-                "any_drift_detected": checklist_drift.any_drift_detected,
-                "prior_run_id": checklist_drift.prior_run_id or "(unknown)",
-                "rows_total": checklist_drift.rows_total,
-                "rows_unchanged": checklist_drift.rows_unchanged,
-                "rows_cosmetic_change": checklist_drift.rows_cosmetic_change,
-                "rows_minor_change": checklist_drift.rows_minor_change,
-                "rows_major_change": checklist_drift.rows_major_change,
-                "rows_breaking_change": checklist_drift.rows_breaking_change,
-                "rows_added": checklist_drift.rows_added,
-                "rows_removed": checklist_drift.rows_removed,
-            }
-            if checklist_drift.prior_page_version is not None:
-                drift_data["prior_page_version"] = checklist_drift.prior_page_version
-            if checklist_drift.current_page_version is not None:
-                drift_data["current_page_version"] = checklist_drift.current_page_version
-            parts.append(json.dumps(drift_data, ensure_ascii=False, indent=2))
-
-        return "\n".join(parts)
-
-    @staticmethod
-    def _build_project_user_prompt(
-        repo_reports: list[ReadinessReport],
-        project_name: str,
-        *,
-        checklist_drift: ChecklistDriftSummary | None = None,
-    ) -> str:
-        """Serialize per-repo ReadinessReport objects into a project-level user prompt."""
-        parts: list[str] = []
-        parts.append(f"## Project: {project_name}")
-        parts.append(f"- Total repos: {len(repo_reports)}")
-        parts.append("")
-
-        for idx, rr in enumerate(repo_reports):
-            parts.append(f"### Repo {idx + 1}: {rr.product_name} (v{rr.version})")
-            parts.append(f"- synthesis_status: {rr.synthesis_status}")
-            parts.append(f"- score: {rr.executive_summary.readiness_score_pct}%")
-            parts.append(f"- classification: {rr.executive_summary.classification.value}")
-            parts.append(f"- confidence: {rr.executive_summary.confidence}")
-            if rr.severity_matrix:
-                parts.append("- severity_matrix:")
-                for entry in rr.severity_matrix:
-                    parts.append(
-                        f"  - [{entry.severity.value}] {entry.category} / {entry.sub_criterion}: {entry.key_issue}"
-                    )
-            if rr.top_critical_issues:
-                parts.append(f"- top_critical_issues: {rr.top_critical_issues}")
-            if rr.heatmap_weakest_categories:
-                parts.append(f"- weakest_categories: {rr.heatmap_weakest_categories}")
-            parts.append("")
-
-        # Phase 114: Checklist drift summary (FR-114.9, AC-114.9.2)
-        if checklist_drift is not None:
-            parts.append("## Checklist Drift Summary (Aggregate)")
-            parts.append("Requirement changes detected across all repos since the prior run:")
-            drift_data = {
-                "drift_detection_enabled": checklist_drift.drift_detection_enabled,
-                "any_drift_detected": checklist_drift.any_drift_detected,
-                "prior_run_id": checklist_drift.prior_run_id or "(unknown)",
-                "rows_total": checklist_drift.rows_total,
-                "rows_unchanged": checklist_drift.rows_unchanged,
-                "rows_cosmetic_change": checklist_drift.rows_cosmetic_change,
-                "rows_minor_change": checklist_drift.rows_minor_change,
-                "rows_major_change": checklist_drift.rows_major_change,
-                "rows_breaking_change": checklist_drift.rows_breaking_change,
-                "rows_added": checklist_drift.rows_added,
-                "rows_removed": checklist_drift.rows_removed,
-            }
-            if checklist_drift.prior_page_version is not None:
-                drift_data["prior_page_version"] = checklist_drift.prior_page_version
-            if checklist_drift.current_page_version is not None:
-                drift_data["current_page_version"] = checklist_drift.current_page_version
-            parts.append(json.dumps(drift_data, ensure_ascii=False, indent=2))
-            parts.append("")
-
-        return "\n".join(parts)
-
-    # ------------------------------------------------------------------
-    # JSON output parsing (TSK-850.11)
-    # ------------------------------------------------------------------
-
-    @staticmethod
-    def _try_parse_repo(
-        raw_text: str,
-        product_name: str,
-        version: str,
-    ) -> tuple[ReadinessReport | None, str]:
-        """Attempt to parse raw LLM text into a ReadinessReport.
-
-        Returns ``(report, "")`` on success or ``(None, error_message)`` on
-        failure.
-        """
-        try:
-            json_text = _extract_json_text(raw_text)
-            data = json.loads(json_text)
-            data["product_name"] = product_name
-            data["version"] = version
-            report = ReadinessReport.model_validate(data)
-            return report, ""
-        except Exception as exc:
-            return None, str(exc)
-
-    @staticmethod
-    def _try_parse_project(
-        raw_text: str,
-        project_name: str,
-    ) -> tuple[ProjectReadinessReport | None, str]:
-        """Attempt to parse raw LLM text into a ProjectReadinessReport."""
-        try:
-            json_text = _extract_json_text(raw_text)
-            data = json.loads(json_text)
-            data["project_name"] = project_name
-            report = ProjectReadinessReport.model_validate(data)
-            return report, ""
-        except Exception as exc:
-            return None, str(exc)
-
-    # ------------------------------------------------------------------
-    # Repair prompt (TSK-850.12)
-    # ------------------------------------------------------------------
-
-    @staticmethod
-    def _build_repair_prompt(
-        original_user_prompt: str,
-        error_msg: str,
-        schema_model: type[BaseModel] = ReadinessReport,
-    ) -> str:
-        """Build a repair prompt including the parse error and expected schema."""
-        schema_hint = json.dumps(
-            schema_model.model_json_schema(),
-            indent=2,
-            ensure_ascii=False,
-        )
-        return (
-            "The previous response could not be parsed.\n\n"
-            f"Parse error:\n{error_msg}\n\n"
-            f"Expected JSON schema:\n{schema_hint}\n\n"
-            "Please fix the JSON output and return ONLY valid JSON.\n\n"
-            "--- Original request ---\n"
-            f"{original_user_prompt}"
-        )
-
-    # ------------------------------------------------------------------
-    # Fallback / degraded report builders
-    # ------------------------------------------------------------------
-
-    @staticmethod
-    def _failed_report(
-        context: ReadinessContext,
-        product_name: str,
-        version: str,
-    ) -> ReadinessReport:
-        """Return a minimal report when LLM call fails entirely."""
-        score = context["weighted_score_pct"]
-        p0_count = len(context["severity_candidates"])
-        return ReadinessReport(
-            product_name=product_name,
-            version=version,
-            executive_summary=ExecutiveSummary(
-                readiness_score_pct=score,
-                classification=_derive_classification(score, p0_count),
-                confidence="LOW",
-                confidence_pct=0.0,
-                general_assessment=("Không thể tổng hợp báo cáo do lỗi kết nối LLM. Điểm số được tính từ dữ liệu thô."),
-            ),
-            synthesis_status="synthesis_failed",
-        )
-
-    @staticmethod
-    def _partial_report(
-        context: ReadinessContext,
-        product_name: str,
-        version: str,
-    ) -> ReadinessReport:
-        """Return a partial report when LLM responded but parsing failed."""
-        score = context["weighted_score_pct"]
-        p0_count = len(context["severity_candidates"])
-        return ReadinessReport(
-            product_name=product_name,
-            version=version,
-            executive_summary=ExecutiveSummary(
-                readiness_score_pct=score,
-                classification=_derive_classification(score, p0_count),
-                confidence="LOW",
-                confidence_pct=10.0,
-                general_assessment=(
-                    "Tổng hợp báo cáo chỉ hoàn thành một phần do lỗi phân tích phản hồi LLM. "
-                    "Điểm số được tính từ dữ liệu thô."
-                ),
-            ),
-            synthesis_status="partial",
-        )
-
-    @staticmethod
-    def _failed_project_report(
-        repo_reports: list[ReadinessReport],
-        project_name: str,
-    ) -> ProjectReadinessReport:
-        """Return a minimal project report when LLM call fails."""
-        summaries = _build_repo_summaries(repo_reports)
-        avg_score = _avg_repo_score(repo_reports)
-        p0_count = _total_p0_count(repo_reports)
-        return ProjectReadinessReport(
-            project_name=project_name,
-            executive_summary=ExecutiveSummary(
-                readiness_score_pct=avg_score,
-                classification=_derive_classification(avg_score, p0_count),
-                confidence="LOW",
-                confidence_pct=0.0,
-                general_assessment=("Không thể tổng hợp báo cáo dự án do lỗi kết nối LLM."),
-            ),
-            repo_readiness=summaries,
-            synthesis_status="synthesis_failed",
-        )
-
-    @staticmethod
-    def _partial_project_report(
-        repo_reports: list[ReadinessReport],
-        project_name: str,
-    ) -> ProjectReadinessReport:
-        """Return a partial project report when parsing fails."""
-        summaries = _build_repo_summaries(repo_reports)
-        avg_score = _avg_repo_score(repo_reports)
-        p0_count = _total_p0_count(repo_reports)
-        return ProjectReadinessReport(
-            project_name=project_name,
-            executive_summary=ExecutiveSummary(
-                readiness_score_pct=avg_score,
-                classification=_derive_classification(avg_score, p0_count),
-                confidence="LOW",
-                confidence_pct=10.0,
-                general_assessment=("Tổng hợp báo cáo dự án chỉ hoàn thành một phần."),
-            ),
-            repo_readiness=summaries,
-            synthesis_status="partial",
-        )
-
-
-# ---------------------------------------------------------------------------
-# Module-level helpers for project aggregation
-# ---------------------------------------------------------------------------
-
-
-def _build_repo_summaries(repo_reports: list[ReadinessReport]) -> list[RepoReadinessSummary]:
-    """Build RepoReadinessSummary list from per-repo reports."""
-    summaries: list[RepoReadinessSummary] = []
-    for rr in repo_reports:
-        summaries.append(
-            RepoReadinessSummary(
-                name=rr.product_name,
-                score=rr.executive_summary.readiness_score_pct,
-                classification=rr.executive_summary.classification,
-                top_issues=list(rr.top_critical_issues[:5]),
-            )
-        )
-    return summaries
-
-
-def _avg_repo_score(repo_reports: list[ReadinessReport]) -> float:
-    """Compute average readiness score across repos (excluding synthesis_failed)."""
-    valid = [
-        rr.executive_summary.readiness_score_pct for rr in repo_reports if rr.synthesis_status != "synthesis_failed"
-    ]
-    if not valid:
-        return 0.0
-    return round(sum(valid) / len(valid), 2)
-
-
-def _total_p0_count(repo_reports: list[ReadinessReport]) -> int:
-    """Count total P0_CRITICAL entries across all repos."""
-    count = 0
-    for rr in repo_reports:
-        if rr.synthesis_status == "synthesis_failed":
-            continue
-        count += sum(1 for e in rr.severity_matrix if e.severity == SeverityLevel.P0_CRITICAL)
-    return count