@ngocsangairvds/vsaf 3.2.14 → 3.2.16

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

@@ -1,1201 +0,0 @@
-"""Template-row checklist generator (TSK-180).
-
-Phase 18: Generate audit checklist artifacts with strict 1:1 template row mapping.
-
-This module generates checklist artifacts from audit results, ensuring that
-output rows exactly mirror input template rows (RULERS-informed locked rubrics).
-
-Reference: design.md Section "Phase 18-19 Implementation Reference"
-Research Foundation:
-- RULERS (arXiv:2601.08654): Locked rubrics + evidence-anchored scoring
-- Evaluative Fingerprints (arXiv:2601.05114): Provenance tracking for reproducibility
-"""
-
-from __future__ import annotations
-
-import hashlib
-import json
-import math
-from dataclasses import dataclass, field
-from datetime import UTC, datetime
-from pathlib import Path
-from typing import TYPE_CHECKING, Any
-
-import structlog
-from openpyxl import Workbook, load_workbook
-from openpyxl.styles import Alignment, Border, Font, PatternFill, Side
-from openpyxl.utils import get_column_letter
-
-from vds_audit_orchestrator.engine.checklist_projection import (
-    PROJECTION_PROFILE_VERSION,
-    ChecklistRowProjectionAdapter,
-    base_locked_columns,
-    canonical_excel_columns,
-    confluence_checklist_columns,
-    template_append_columns,
-    validate_base_column_lock,
-)
-from vds_audit_orchestrator.engine.row_evaluator_types import extract_requirement_guidance
-from vds_audit_orchestrator.models.checklist import (
-    VERIFICATION_REASON_EXTRACTED_FROM_FINDING_EVIDENCE,
-    VERIFICATION_REASON_EXTRACTED_FROM_FINDING_EVIDENCE_DATA,
-    VERIFICATION_REASON_EXTRACTED_FROM_FINDING_EVIDENCE_REF,
-    AuditChecklist,
-    ChecklistExportConfig,
-    EvidenceAnchor,
-    RowEvaluation,
-    RowProvenance,
-    RowStatus,
-    ScoreBreakdown,
-    normalize_verification_reason,
-)
-from vds_audit_orchestrator.models.template import AuditCheck, AuditTemplate
-
-if TYPE_CHECKING:
-    from vds_audit_orchestrator.models.evidence import EvidenceBundle
-    from vds_audit_orchestrator.models.findings import CheckFinding
-
-logger = structlog.get_logger(__name__)
-
-
-# Excel styling constants
-_HEADER_FILL = PatternFill(start_color="1F4E79", end_color="1F4E79", fill_type="solid")
-_HEADER_FONT = Font(bold=True, color="FFFFFF", size=11)
-_HEADER_ALIGN = Alignment(horizontal="center", vertical="center", wrap_text=True)
-_CELL_ALIGN = Alignment(vertical="top", wrap_text=True)
-_THIN_BORDER = Border(
-    left=Side(style="thin"),
-    right=Side(style="thin"),
-    top=Side(style="thin"),
-    bottom=Side(style="thin"),
-)
-
-# Status color fills for Excel
-_STATUS_FILLS: dict[RowStatus, PatternFill] = {
-    RowStatus.PASS: PatternFill(start_color="C6EFCE", end_color="C6EFCE", fill_type="solid"),  # Light green
-    RowStatus.PARTIAL: PatternFill(start_color="FFEB9C", end_color="FFEB9C", fill_type="solid"),  # Light yellow
-    RowStatus.FAIL: PatternFill(start_color="FFC7CE", end_color="FFC7CE", fill_type="solid"),  # Light red
-    RowStatus.NA: PatternFill(start_color="D9D9D9", end_color="D9D9D9", fill_type="solid"),  # Light gray
-    RowStatus.ERROR: PatternFill(start_color="FF6B6B", end_color="FF6B6B", fill_type="solid"),  # Darker red
-}
-
-
-def _compute_hash(content: str | bytes, length: int = 16) -> str:
-    """Compute SHA256 hash of content, returning first `length` characters."""
-    if isinstance(content, str):
-        content = content.encode("utf-8")
-    return hashlib.sha256(content).hexdigest()[:length]
-
-
-def _compute_template_hash(template: AuditTemplate) -> str:
-    """Compute deterministic hash of template content."""
-    # Create stable representation for hashing
-    data = {
-        "name": template.name,
-        "version": template.version,
-        "sections": [
-            {
-                "id": s.id,
-                "checks": [{"id": c.id, "description": c.description} for c in s.checks],
-            }
-            for s in template.sections
-        ],
-    }
-    return _compute_hash(json.dumps(data, sort_keys=True))
-
-
-def _compute_evidence_hash(evidence_bundle: EvidenceBundle | None) -> str:
-    """Compute hash of evidence bundle for provenance tracking."""
-    if evidence_bundle is None:
-        return _compute_hash("no-evidence")
-
-    # Use evidence from all sources for deterministic hash
-    evidence_data: list[str] = []
-
-    # Collect all evidence from bundle
-    all_evidence = (
-        evidence_bundle.git_evidence
-        + evidence_bundle.confluence_evidence
-        + evidence_bundle.jira_evidence
-        + evidence_bundle.sonarqube_evidence
-    )
-
-    for evidence in all_evidence:
-        evidence_data.append(f"{evidence.source}:{evidence.source_id}:{evidence.content_hash}")
-
-    return _compute_hash("\n".join(sorted(evidence_data)))
-
-
-@dataclass
-class ScoringGateConfig:
-    """Configuration for score gating conditions (FR-221)."""
-
-    min_evidence_count: int = 0
-    min_confidence: float = 0.0
-    cap_score: float = 30.0  # Cap as percentage (0-100) when gate fails
-
-
-@dataclass
-class ScoringProfile:
-    """Profile-based scoring configuration (FR-220/221/222).
-
-    Allows per-category or per-check-ID weight overrides and gating conditions.
-    """
-
-    weight_overrides: dict[str, float] = field(default_factory=dict)
-    weight_override_mode: str = "absolute"
-    gating: ScoringGateConfig = field(default_factory=ScoringGateConfig)
-    docs_sources_expected: int = 0
-    code_sources_expected: int = 0
-
-
-class ChecklistGenerator:
-    """Generate audit checklist artifacts from audit results.
-
-    Ensures strict 1:1 mapping between template rows and output rows
-    per RULERS locked-rubric pattern.
-
-    Usage:
-        generator = ChecklistGenerator(template, template_hash)
-        checklist = generator.generate_from_audit_result(result, evidence_bundle)
-        generator.export_json(checklist, output_dir / "audit-checklist.json")
-        generator.export_excel(checklist, output_dir / "audit-checklist.xlsx")
-    """
-
-    def __init__(
-        self,
-        template: AuditTemplate,
-        template_hash: str | None = None,
-        *,
-        row_llm_mode: str = "selective",
-        protocol: str | None = None,
-        model: str | None = None,
-        scoring_profile: ScoringProfile | None = None,
-    ) -> None:
-        """Initialize checklist generator.
-
-        Args:
-            template: The audit template defining requirements.
-            template_hash: Pre-computed template hash (computed if None).
-            row_llm_mode: Evaluation mode (off, selective, per-row).
-            protocol: LLM protocol name if applicable.
-            model: LLM model name if applicable.
-        """
-        self.template = template
-        self.template_hash = template_hash or _compute_template_hash(template)
-        self.row_llm_mode = row_llm_mode
-        self.protocol = protocol
-        self.model = model
-        self.scoring_profile = scoring_profile or ScoringProfile()
-
-        # Build check lookup for fast access
-        self._check_lookup: dict[str, tuple[AuditCheck, str]] = {}
-        for section in template.sections:
-            for check in section.checks:
-                self._check_lookup[check.id] = (check, section.id)
-
-        # Count total template rows (checks)
-        self._template_row_count = sum(len(s.checks) for s in template.sections)
-
-        logger.info(
-            "checklist_generator_initialized",
-            template_name=template.name,
-            template_version=template.version,
-            template_hash=self.template_hash,
-            row_count=self._template_row_count,
-        )
-
-    def generate_from_audit_result(
-        self,
-        result: RepositoryAuditResult,
-        evidence_bundle: EvidenceBundle | None = None,
-        *,
-        config: ChecklistExportConfig | None = None,
-    ) -> AuditChecklist:
-        """Generate checklist from audit result.
-
-        Args:
-            result: Complete audit result from AuditEngine.
-            evidence_bundle: Optional evidence bundle for anchoring.
-            config: Export configuration options.
-
-        Returns:
-            AuditChecklist with strict 1:1 row mapping.
-        """
-        if config is None:
-            config = ChecklistExportConfig()
-
-        evidence_hash = _compute_evidence_hash(evidence_bundle)
-        generated_at = datetime.now(UTC)
-
-        # Build finding lookup: check_id -> CheckFinding
-        finding_lookup: dict[str, CheckFinding] = {}
-        for section_result in result.sections:
-            for section_finding in section_result.findings:
-                finding_lookup[section_finding.check_id] = section_finding
-
-        # Generate row evaluations maintaining template order
-        rows: list[RowEvaluation] = []
-        row_index = 0
-
-        for template_section in self.template.sections:
-            for check in template_section.checks:
-                finding = finding_lookup.get(check.id)
-                row_eval = self._build_row_evaluation(
-                    check=check,
-                    section_id=template_section.id,
-                    row_index=row_index,
-                    finding=finding,
-                    evidence_bundle=evidence_bundle,
-                    evidence_hash=evidence_hash,
-                    generated_at=generated_at,
-                    config=config,
-                )
-                rows.append(row_eval)
-                row_index += 1
-
-        # Validate row count matches template
-        if len(rows) != self._template_row_count:
-            logger.warning(
-                "row_count_mismatch",
-                expected=self._template_row_count,
-                actual=len(rows),
-            )
-
-        checklist = AuditChecklist(
-            checklist_version="1.0.0",
-            generated_at=generated_at,
-            template_name=self.template.name,
-            template_version=self.template.version,
-            template_hash=self.template_hash,
-            template_row_count=self._template_row_count,
-            repository=result.repo_name,
-            repository_ref=result.audit_metadata.get("git_ref"),
-            row_llm_mode=self.row_llm_mode,
-            evidence_hash=evidence_hash,
-            rows=rows,
-            stability_flags=[],
-        )
-
-        logger.info(
-            "checklist_generated",
-            repository=result.repo_name,
-            total_rows=checklist.total_rows,
-            pass_count=checklist.pass_count,
-            partial_count=checklist.partial_count,
-            fail_count=checklist.fail_count,
-            na_count=checklist.na_count,
-            overall_score=f"{checklist.overall_score:.1f}%",
-        )
-
-        return checklist
-
-    def _build_row_evaluation(
-        self,
-        check: AuditCheck,
-        section_id: str,
-        row_index: int,
-        finding: CheckFinding | None,
-        evidence_bundle: EvidenceBundle | None,
-        evidence_hash: str,
-        generated_at: datetime,
-        config: ChecklistExportConfig,
-    ) -> RowEvaluation:
-        """Build RowEvaluation from check and optional finding.
-
-        If no finding exists (check was not executed), creates ERROR row.
-        """
-        # Row identification
-        row_id = f"{check.id}:row_{row_index}"
-
-        # Extract weight from check
-        weight_raw = check.effective_weight
-
-        # Build provenance
-        provenance = RowProvenance(
-            row_llm_mode=self.row_llm_mode,
-            protocol=self.protocol,
-            model=self.model,
-            template_hash=self.template_hash,
-            rubric_version=self.template.version,
-            evidence_hash=evidence_hash,
-            evaluated_at=generated_at,
-            evaluation_duration_ms=finding.execution_time_ms if finding else None,
-            cache_hit=False,
-        )
-
-        if finding is None:
-            # Check was not executed - create ERROR row
-            return RowEvaluation(
-                row_id=row_id,
-                row_index=row_index,
-                check_id=check.id,
-                section_id=section_id,
-                requirement_text=check.description,
-                requirement_category=getattr(check, "requirement_category", None) or section_id,
-                weight_raw=weight_raw,
-                weight_adjusted=weight_raw,
-                weight_adjustment_reason=None,
-                status=RowStatus.ERROR,
-                score_breakdown=ScoreBreakdown.compute(0.0),
-                evidence_refs=[],
-                reason="Check was not executed during audit.",
-                finding="Không có dữ liệu đánh giá. (No evaluation data available.)",
-                severity=None,
-                priority=None,
-                effort=None,
-                recommendation="Re-run audit to include this check.",
-                provenance=provenance,
-                probe_results=None,
-                score_1_5=1,
-                requirement_guidance=None,  # No guidance available for ERROR row
-            )
-
-        # Build from finding
-        status = self._derive_status(finding)
-        evidence_anchors = self._extract_evidence_anchors(finding, evidence_bundle, config)
-
-        # FR-220: Profile-based weight adjustment
-        weight_adjusted, weight_adjustment_reason = self._apply_weight_adjustment(
-            weight_raw=weight_raw,
-            check_id=check.id,
-            category=getattr(check, "requirement_category", None) or section_id,
-        )
-
-        # FR-222: Coverage tracking
-        coverage = self._compute_coverage(finding, evidence_anchors)
-
-        # FR-221: Score gating conditions
-        score_cap, gating_applied, gating_reason = self._evaluate_gating(
-            finding=finding,
-            evidence_anchors=evidence_anchors,
-        )
-
-        score_breakdown = self._build_score_breakdown(
-            finding,
-            score_cap=score_cap,
-            coverage=coverage,
-        )
-
-        # Build reason and finding text
-        reason = self._build_reason(finding, check)
-        finding_text = self._build_finding_text(finding, check)
-
-        # Compute 1-5 score
-        score_1_5 = self._compute_score_1_5(score_breakdown.final_score)
-
-        return RowEvaluation(
-            row_id=row_id,
-            row_index=row_index,
-            check_id=check.id,
-            section_id=section_id,
-            requirement_text=check.description,
-            requirement_category=getattr(check, "requirement_category", None) or section_id,
-            weight_raw=weight_raw,
-            weight_adjusted=weight_adjusted,
-            weight_adjustment_reason=weight_adjustment_reason,
-            status=status,
-            score_breakdown=score_breakdown,
-            gating_applied=gating_applied,
-            gating_reason=gating_reason,
-            evidence_refs=evidence_anchors,
-            reason=reason,
-            finding=finding_text,
-            severity=finding.severity.value if finding.severity else None,
-            priority=finding.priority.value if finding.priority else None,
-            effort=finding.migration_effort.value if finding.migration_effort else None,
-            recommendation=finding.recommendation,
-            provenance=provenance,
-            probe_results=self._extract_probe_results(finding) if finding.probe_scores else None,
-            score_1_5=score_1_5,
-            requirement_guidance=extract_requirement_guidance(check.check_config or {}) or None,
-        )
-
-    def _derive_status(self, finding: CheckFinding) -> RowStatus:
-        """Derive RowStatus from CheckFinding using standard thresholds."""
-        from vds_audit_orchestrator.models.enums import CheckStatus
-
-        # Map check status to row status
-        if finding.status == CheckStatus.NOT_APPLICABLE:
-            return RowStatus.NA
-        if finding.status == CheckStatus.ERROR:
-            return RowStatus.ERROR
-        if finding.status == CheckStatus.PASSED:
-            return RowStatus.PASS
-
-        # For FAILED, PARTIAL, SKIPPED - use score thresholds
-        score = finding.score_percentage
-        return RowStatus.from_score(score)
-
-    def _apply_weight_adjustment(
-        self,
-        weight_raw: float,
-        check_id: str,
-        category: str,
-    ) -> tuple[float, str | None]:
-        """Apply profile-based weight adjustment (FR-220).
-
-        Lookup priority: check_id override > category override > weight_raw fallback.
-
-        Returns:
-            Tuple of (adjusted_weight, adjustment_reason).
-        """
-        profile = self.scoring_profile
-
-        mode = str(getattr(profile, "weight_override_mode", "absolute") or "absolute").strip().lower()
-
-        # Check ID override (most specific)
-        if check_id in profile.weight_overrides:
-            override = profile.weight_overrides[check_id]
-            adjusted = float(weight_raw * override) if mode == "multiplier" else float(override)
-            adjusted = max(0.0, adjusted)
-            if mode == "multiplier":
-                return adjusted, f"profile_multiplier:check_id={check_id}"
-            return adjusted, f"profile_override:check_id={check_id}"
-
-        # Category override
-        if category in profile.weight_overrides:
-            override = profile.weight_overrides[category]
-            adjusted = float(weight_raw * override) if mode == "multiplier" else float(override)
-            adjusted = max(0.0, adjusted)
-            if mode == "multiplier":
-                return adjusted, f"profile_multiplier:category={category}"
-            return adjusted, f"profile_override:category={category}"
-
-        # No override — backward compatible
-        return weight_raw, None
-
-    def _evaluate_gating(
-        self,
-        finding: CheckFinding,
-        evidence_anchors: list[EvidenceAnchor],
-    ) -> tuple[float | None, bool, str | None]:
-        """Evaluate score gating conditions (FR-221).
-
-        Returns:
-            Tuple of (score_cap, gating_applied, gating_reason).
-        """
-        gating = self.scoring_profile.gating
-        confidence = finding.confidence if finding.confidence is not None else 1.0
-
-        # Gate: minimum evidence count
-        if len(evidence_anchors) < gating.min_evidence_count:
-            return (
-                gating.cap_score,
-                True,
-                f"insufficient_evidence:found={len(evidence_anchors)},required={gating.min_evidence_count}",
-            )
-
-        # Gate: minimum confidence threshold
-        if confidence < gating.min_confidence:
-            return (
-                gating.cap_score,
-                True,
-                f"low_confidence:value={confidence:.2f},threshold={gating.min_confidence:.2f}",
-            )
-
-        # All gates pass
-        return None, False, None
-
-    def _compute_coverage(
-        self,
-        finding: CheckFinding,
-        evidence_anchors: list[EvidenceAnchor],
-    ) -> float:
-        """Compute corpus-hit coverage ratio (FR-222).
-
-        Coverage tracks what fraction of expected evidence sources were found.
-        Combined coverage = weighted average (docs * 0.5 + code * 0.5).
-
-        Returns:
-            Combined coverage factor (0.0 to 1.0).
-        """
-        profile = self.scoring_profile
-
-        # Classify evidence anchors by type
-        docs_count = sum(
-            1 for a in evidence_anchors if a.ref_type in ("confluence_url", "doc_path", "url", "jira_url", "jira_key")
-        )
-        code_count = sum(
-            1 for a in evidence_anchors if a.ref_type in ("code_path", "bitbucket_url", "bitbucket_ref", "file-path")
-        )
-
-        expected_docs = max(int(profile.docs_sources_expected), 0)
-        expected_code = max(int(profile.code_sources_expected), 0)
-
-        components: list[float] = []
-        if expected_docs > 0:
-            components.append(min(docs_count / expected_docs, 1.0))
-        if expected_code > 0:
-            components.append(min(code_count / expected_code, 1.0))
-
-        # Default behavior keeps legacy scoring unchanged unless expectations are configured.
-        if not components:
-            return 1.0
-        return sum(components) / len(components)
-
-    def _build_score_breakdown(
-        self,
-        finding: CheckFinding,
-        *,
-        score_cap: float | None = None,
-        coverage: float = 1.0,
-    ) -> ScoreBreakdown:
-        """Build score breakdown from finding."""
-        raw_score = finding.score_percentage
-        confidence = finding.confidence if finding.confidence is not None else 1.0
-
-        return ScoreBreakdown.compute(
-            raw_score=raw_score,
-            score_cap=score_cap,
-            coverage=coverage,
-            confidence=confidence,
-        )
-
-    def _extract_evidence_anchors(
-        self,
-        finding: CheckFinding,
-        evidence_bundle: EvidenceBundle | None,
-        config: ChecklistExportConfig,
-    ) -> list[EvidenceAnchor]:
-        """Extract evidence anchors from finding and evidence bundle."""
-        anchors: list[EvidenceAnchor] = []
-
-        # Extract from finding.evidence list (paths/URLs)
-        for ref in finding.evidence[: config.max_evidence_refs]:
-            anchor = EvidenceAnchor(
-                ref_type=self._infer_ref_type(ref),
-                ref_value=ref,
-                ref_hash=None,
-                excerpt=None,
-                verified=False,
-                verification_reason=normalize_verification_reason(
-                    VERIFICATION_REASON_EXTRACTED_FROM_FINDING_EVIDENCE,
-                    verified=False,
-                ),
-            )
-            anchors.append(anchor)
-
-        # Extract from evidence_ref if present
-        if finding.evidence_ref and finding.evidence_ref not in finding.evidence:
-            anchor = EvidenceAnchor(
-                ref_type=self._infer_ref_type(finding.evidence_ref),
-                ref_value=finding.evidence_ref,
-                ref_hash=None,
-                excerpt=None,
-                verified=False,
-                verification_reason=normalize_verification_reason(
-                    VERIFICATION_REASON_EXTRACTED_FROM_FINDING_EVIDENCE_REF,
-                    verified=False,
-                ),
-            )
-            anchors.append(anchor)
-
-        # Extract from evidence_data if dict with refs
-        if isinstance(finding.evidence_data, dict):
-            for key in ("file_path", "confluence_url", "bitbucket_ref"):
-                if key in finding.evidence_data and len(anchors) < config.max_evidence_refs:
-                    value = finding.evidence_data[key]
-                    if isinstance(value, str):
-                        anchor = EvidenceAnchor(
-                            ref_type=key.replace("_", "-"),
-                            ref_value=value,
-                            ref_hash=None,
-                            excerpt=finding.evidence_data.get("excerpt"),
-                            verified=False,
-                            verification_reason=normalize_verification_reason(
-                                VERIFICATION_REASON_EXTRACTED_FROM_FINDING_EVIDENCE_DATA,
-                                verified=False,
-                                excerpt=str(finding.evidence_data.get("excerpt") or ""),
-                            ),
-                        )
-                        anchors.append(anchor)
-
-        return anchors[: config.max_evidence_refs]
-
-    def _infer_ref_type(self, ref: str) -> str:
-        """Infer evidence reference type from value."""
-        ref_lower = ref.lower()
-        if ref_lower.startswith("http"):
-            if "confluence" in ref_lower:
-                return "confluence_url"
-            if "bitbucket" in ref_lower:
-                return "bitbucket_url"
-            if "jira" in ref_lower:
-                return "jira_url"
-            return "url"
-        if "/" in ref:
-            return "code_path"
-        if ref.startswith("JIRA-") or ref.startswith("VDS-"):
-            return "jira_key"
-        return "doc_path"
-
-    def _build_reason(self, finding: CheckFinding, check: AuditCheck) -> str:
-        """Build Vietnamese reason text from finding."""
-        if finding.message:
-            return finding.message
-
-        status = self._derive_status(finding)
-        if status == RowStatus.PASS:
-            return f"Yêu cầu '{check.name or check.description[:50]}' đã được đáp ứng đầy đủ."
-        if status == RowStatus.PARTIAL:
-            return f"Yêu cầu '{check.name or check.description[:50]}' được đáp ứng một phần. Cần bổ sung thêm."
-        if status == RowStatus.FAIL:
-            return f"Yêu cầu '{check.name or check.description[:50]}' chưa được đáp ứng."
-        if status == RowStatus.NA:
-            return "Không áp dụng cho dự án này."
-        return "Lỗi trong quá trình đánh giá."
-
-    def _build_finding_text(self, finding: CheckFinding, check: AuditCheck) -> str:
-        """Build Vietnamese finding text."""
-        status = self._derive_status(finding)
-
-        if status == RowStatus.PASS:
-            return "Đạt yêu cầu. (Meets requirements.)"
-
-        if finding.recommendation:
-            return finding.recommendation
-
-        if status == RowStatus.PARTIAL:
-            return "Cần cải thiện thêm để đạt yêu cầu hoàn toàn."
-        if status == RowStatus.FAIL:
-            return "Không đạt. Cần thực hiện các hành động khắc phục."
-        if status == RowStatus.NA:
-            return "Không áp dụng."
-
-        return "Cần xem xét thêm."
-
-    def _extract_probe_results(self, finding: CheckFinding) -> list[dict[str, Any]] | None:
-        """Extract probe results for TICK-style decomposition."""
-        if not finding.probe_scores:
-            return None
-
-        return [{"probe_name": name, "score": score} for name, score in finding.probe_scores.items()]
-
-    def _compute_score_1_5(self, score_percent: float) -> int:
-        """Map percentage score to 1-5 scale for Vietnamese checklist."""
-        if score_percent >= 90:
-            return 5
-        if score_percent >= 70:
-            return 4
-        if score_percent >= 50:
-            return 3
-        if score_percent >= 30:
-            return 2
-        return 1
-
-    # ==========================================================================
-    # Export Methods
-    # ==========================================================================
-
-    def export_json(
-        self,
-        checklist: AuditChecklist,
-        path: Path,
-        *,
-        indent: int = 2,
-    ) -> Path:
-        """Export checklist as canonical JSON.
-
-        Args:
-            checklist: The audit checklist to export.
-            path: Output file path.
-            indent: JSON indentation (default 2).
-
-        Returns:
-            Path to written file.
-        """
-        path.parent.mkdir(parents=True, exist_ok=True)
-
-        # Export with datetime serialization
-        data = checklist.model_dump(mode="json")
-        path.write_text(json.dumps(data, indent=indent, ensure_ascii=False, default=str), encoding="utf-8")
-
-        logger.info("checklist_json_exported", path=str(path), row_count=checklist.total_rows)
-        return path
-
-    def export_excel(
-        self,
-        checklist: AuditChecklist,
-        path: Path,
-        *,
-        template_path: Path | None = None,
-        config: ChecklistExportConfig | None = None,
-    ) -> Path:
-        """Export checklist as Excel with Vietnamese columns.
-
-        Args:
-            checklist: The audit checklist to export.
-            path: Output file path.
-            template_path: Optional template to copy and extend (preserves structure).
-            config: Export configuration options.
-
-        Returns:
-            Path to written file.
-        """
-        if config is None:
-            config = ChecklistExportConfig()
-
-        path.parent.mkdir(parents=True, exist_ok=True)
-
-        if template_path and template_path.exists():
-            # Copy template and append result columns
-            wb = load_workbook(template_path)
-            ws = wb.active
-            self._append_result_columns_to_template(ws, checklist, config)
-        else:
-            # Create new workbook with full structure
-            wb = Workbook()
-            ws = wb.active
-            if ws is None:
-                ws = wb.create_sheet("Checklist")
-            else:
-                ws.title = "Checklist"
-            self._write_full_checklist_sheet(ws, checklist, config)
-
-        # Add summary sheet
-        ws_summary = wb.create_sheet("Summary", 0)
-        self._write_summary_sheet(ws_summary, checklist)
-
-        wb.save(path)
-        logger.info("checklist_excel_exported", path=str(path), row_count=checklist.total_rows)
-        return path
-
-    def export_markdown(
-        self,
-        checklist: AuditChecklist,
-        path: Path,
-        *,
-        config: ChecklistExportConfig | None = None,
-    ) -> Path:
-        """Export checklist as human-readable Markdown.
-
-        Args:
-            checklist: The audit checklist to export.
-            path: Output file path.
-            config: Export configuration options.
-
-        Returns:
-            Path to written file.
-        """
-        if config is None:
-            config = ChecklistExportConfig()
-
-        path.parent.mkdir(parents=True, exist_ok=True)
-
-        lines: list[str] = []
-
-        # Header
-        lines.append(f"# Audit Checklist: {checklist.repository}")
-        lines.append("")
-        lines.append(f"**Generated:** {checklist.generated_at.isoformat()}")
-        lines.append(f"**Template:** {checklist.template_name} v{checklist.template_version}")
-        lines.append(f"**Template Hash:** `{checklist.template_hash}`")
-        lines.append(f"**Evidence Hash:** `{checklist.evidence_hash}`")
-        lines.append("")
-
-        # Summary
-        lines.append("## Summary")
-        lines.append("")
-        lines.append(f"- **Overall Score:** {checklist.overall_score:.1f}% ({checklist.overall_score_1_5:.2f}/5)")
-        lines.append(f"- **Total Rows:** {checklist.total_rows}")
-        lines.append(f"- ✅ Pass: {checklist.pass_count}")
-        lines.append(f"- ⚠️ Partial: {checklist.partial_count}")
-        lines.append(f"- ❌ Fail: {checklist.fail_count}")
-        lines.append(f"- ➖ N/A: {checklist.na_count}")
-        lines.append(f"- 🔴 Error: {checklist.error_count}")
-        lines.append("")
-
-        # Top Findings
-        top_findings = checklist.get_top_findings(limit=10)
-        if top_findings:
-            lines.append("## Top Findings")
-            lines.append("")
-            lines.append("| Status | Check ID | Score | Finding |")
-            lines.append("|--------|----------|-------|---------|")
-            for row in top_findings:
-                finding_truncated = row.finding[:80] + "..." if len(row.finding) > 80 else row.finding
-                lines.append(
-                    f"| {row.status.emoji} {row.status.vietnamese} | {row.check_id or 'N/A'} | "
-                    f"{row.score_percent:.0f}% | {finding_truncated} |"
-                )
-            lines.append("")
-
-        # Section Summary
-        section_summary = checklist.get_section_summary()
-        if section_summary:
-            lines.append("## Section Summary")
-            lines.append("")
-            lines.append("| Section | Score | Pass | Partial | Fail | N/A |")
-            lines.append("|---------|-------|------|---------|------|-----|")
-            for section_id, data in sorted(section_summary.items()):
-                lines.append(
-                    f"| {section_id} | {data['score_percentage']:.0f}% | "
-                    f"{data['pass_count']} | {data['partial_count']} | "
-                    f"{data['fail_count']} | {data['na_count']} |"
-                )
-            lines.append("")
-
-        # Full Results Table
-        lines.append("## Detailed Results")
-        lines.append("")
-        lines.append("| # | Status | Check ID | Requirement | Score | Lý do |")
-        lines.append("|---|--------|----------|-------------|-------|-------|")
-        for row in checklist.rows:
-            req_truncated = (
-                row.requirement_text[:50] + "..." if len(row.requirement_text) > 50 else row.requirement_text
-            )
-            reason_truncated = row.reason[:50] + "..." if len(row.reason) > 50 else row.reason
-            lines.append(
-                f"| {row.row_index + 1} | {row.status.emoji} | {row.check_id or '-'} | "
-                f"{req_truncated} | {row.score_percent:.0f}% | {reason_truncated} |"
-            )
-        lines.append("")
-
-        # Provenance
-        lines.append("## Provenance")
-        lines.append("")
-        lines.append(f"- **Row LLM Mode:** {checklist.row_llm_mode}")
-        lines.append(f"- **Template Hash:** `{checklist.template_hash}`")
-        lines.append(f"- **Evidence Hash:** `{checklist.evidence_hash}`")
-        if checklist.stability_flags:
-            lines.append(f"- **Stability Flags:** {', '.join(checklist.stability_flags)}")
-        lines.append("")
-
-        path.write_text("\n".join(lines), encoding="utf-8")
-        logger.info("checklist_markdown_exported", path=str(path), row_count=checklist.total_rows)
-        return path
-
-    def _write_full_checklist_sheet(
-        self,
-        ws: Any,  # Worksheet
-        checklist: AuditChecklist,
-        config: ChecklistExportConfig,
-    ) -> None:
-        """Write full checklist to a new worksheet."""
-        all_columns = canonical_excel_columns(config)
-        validate_base_column_lock(all_columns)
-        projector = ChecklistRowProjectionAdapter()
-
-        # Write header row
-        for col_idx, column in enumerate(all_columns, start=1):
-            cell = ws.cell(row=1, column=col_idx, value=column.header)
-            cell.fill = _HEADER_FILL
-            cell.font = _HEADER_FONT
-            cell.alignment = _HEADER_ALIGN
-            cell.border = _THIN_BORDER
-
-        # Write data rows
-        for row_idx, row in enumerate(checklist.rows, start=2):
-            projected = projector.project_for_excel(row, all_columns)
-            for col_idx, (column, value) in enumerate(zip(all_columns, projected, strict=False), start=1):
-                cell = ws.cell(row=row_idx, column=col_idx, value=value)
-                cell.alignment = _CELL_ALIGN
-                cell.border = _THIN_BORDER
-
-                # Apply status coloring to status column
-                if column.key == "status_vietnamese":
-                    status_fill = _STATUS_FILLS.get(row.status)
-                    if status_fill:
-                        cell.fill = status_fill
-
-        # Set column widths
-        for col_idx, column in enumerate(all_columns, start=1):
-            if column.width is not None and col_idx <= ws.max_column:
-                ws.column_dimensions[get_column_letter(col_idx)].width = column.width
-
-        # Freeze header row
-        ws.freeze_panes = "A2"
-
-        # Add auto-filter
-        ws.auto_filter.ref = f"A1:{get_column_letter(len(all_columns))}{len(checklist.rows) + 1}"
-
-    def _append_result_columns_to_template(
-        self,
-        ws: Any,  # Worksheet
-        checklist: AuditChecklist,
-        config: ChecklistExportConfig,
-    ) -> None:
-        """Append result columns to existing template worksheet."""
-        # Find the last column with data
-        start_col = ws.max_column + 1
-        result_columns = template_append_columns(config)
-        projector = ChecklistRowProjectionAdapter()
-
-        # Write result column headers
-        for col_offset, column in enumerate(result_columns):
-            col_idx = start_col + col_offset
-            cell = ws.cell(row=1, column=col_idx, value=column.header)
-            cell.fill = _HEADER_FILL
-            cell.font = _HEADER_FONT
-            cell.alignment = _HEADER_ALIGN
-            cell.border = _THIN_BORDER
-
-        # Write result data (assuming template rows match checklist rows)
-        for row_idx, row in enumerate(checklist.rows, start=2):
-            projected = projector.project_for_excel(row, result_columns)
-            for col_offset, (column, value) in enumerate(zip(result_columns, projected, strict=False)):
-                col_idx = start_col + col_offset
-                cell = ws.cell(row=row_idx, column=col_idx, value=value)
-                cell.alignment = _CELL_ALIGN
-                cell.border = _THIN_BORDER
-
-                # Apply status coloring
-                if column.key == "status_vietnamese":
-                    status_fill = _STATUS_FILLS.get(row.status)
-                    if status_fill:
-                        cell.fill = status_fill
-
-        # Set column widths for new columns
-        for col_offset, column in enumerate(result_columns):
-            if column.width is not None:
-                col_idx = start_col + col_offset
-                ws.column_dimensions[get_column_letter(col_idx)].width = column.width
-
-    def _write_summary_sheet(self, ws: Any, checklist: AuditChecklist) -> None:
-        """Write summary sheet."""
-        ws["A1"] = "Audit Checklist Summary"
-        ws["A1"].font = Font(bold=True, size=14)
-
-        ws["A3"] = "Repository"
-        ws["B3"] = checklist.repository
-
-        ws["A4"] = "Template"
-        ws["B4"] = f"{checklist.template_name} v{checklist.template_version}"
-
-        ws["A5"] = "Generated At"
-        ws["B5"] = checklist.generated_at.isoformat()
-
-        ws["A6"] = "Overall Score"
-        ws["B6"] = f"{checklist.overall_score:.1f}%"
-
-        ws["A7"] = "Overall Score (1-5)"
-        ws["B7"] = f"{checklist.overall_score_1_5:.2f}"
-
-        ws["A9"] = "Status"
-        ws["B9"] = "Count"
-        ws["A9"].font = Font(bold=True)
-        ws["B9"].font = Font(bold=True)
-
-        status_rows = [
-            ("✅ Pass (ĐẠT)", checklist.pass_count),
-            ("⚠️ Partial (MỘT PHẦN)", checklist.partial_count),
-            ("❌ Fail (KHÔNG ĐẠT)", checklist.fail_count),
-            ("➖ N/A (KHÔNG ÁP DỤNG)", checklist.na_count),
-            ("🔴 Error (LỖI)", checklist.error_count),
-            ("Total", checklist.total_rows),
-        ]
-
-        for idx, (label, count) in enumerate(status_rows, start=10):
-            ws.cell(row=idx, column=1, value=label)
-            ws.cell(row=idx, column=2, value=count)
-
-        ws["A17"] = "Provenance"
-        ws["A17"].font = Font(bold=True)
-        ws["A18"] = "Template Hash"
-        ws["B18"] = checklist.template_hash
-        ws["A19"] = "Evidence Hash"
-        ws["B19"] = checklist.evidence_hash
-        ws["A20"] = "Row LLM Mode"
-        ws["B20"] = checklist.row_llm_mode
-
-        ws.column_dimensions["A"].width = 25
-        ws.column_dimensions["B"].width = 40
-
-
-# =============================================================================
-# Convenience Functions
-# =============================================================================
-
-
-def generate_checklist_from_result(
-    template: AuditTemplate,
-    result: RepositoryAuditResult,
-    evidence_bundle: EvidenceBundle | None = None,
-    *,
-    row_llm_mode: str = "selective",
-    protocol: str | None = None,
-    model: str | None = None,
-) -> AuditChecklist:
-    """Convenience function to generate checklist from audit result.
-
-    Args:
-        template: The audit template.
-        result: The audit result.
-        evidence_bundle: Optional evidence bundle.
-        row_llm_mode: Evaluation mode.
-        protocol: LLM protocol name.
-        model: LLM model name.
-
-    Returns:
-        Generated AuditChecklist.
-    """
-    scoring_profile = _scoring_profile_from_result(result)
-    generator = ChecklistGenerator(
-        template=template,
-        row_llm_mode=row_llm_mode,
-        protocol=protocol,
-        model=model,
-        scoring_profile=scoring_profile,
-    )
-    return generator.generate_from_audit_result(result, evidence_bundle)
-
-
-def _coerce_float(value: Any) -> float | None:
-    try:
-        parsed = float(value)
-    except (TypeError, ValueError):
-        return None
-    if not math.isfinite(parsed):
-        return None
-    return parsed
-
-
-def _scoring_profile_from_result(result: RepositoryAuditResult) -> ScoringProfile | None:
-    """Build checklist scoring profile from ``RepositoryAuditResult.profile_info``."""
-    profile_info = result.profile_info if isinstance(result.profile_info, dict) else {}
-    if not profile_info:
-        return None
-
-    profile = ScoringProfile()
-    has_overrides = False
-
-    weight_overrides = profile_info.get("weight_overrides")
-    if isinstance(weight_overrides, dict):
-        multiplier_keys = ("check_multipliers", "category_multipliers", "section_multipliers")
-        saw_multiplier_shape = False
-        for key in multiplier_keys:
-            bucket = weight_overrides.get(key)
-            if not isinstance(bucket, dict):
-                continue
-            saw_multiplier_shape = True
-            for override_key, override_value_raw in bucket.items():
-                override_value = _coerce_float(override_value_raw)
-                if override_value is None:
-                    continue
-                profile.weight_overrides[str(override_key)] = max(0.0, override_value)
-                has_overrides = True
-        if saw_multiplier_shape:
-            profile.weight_override_mode = "multiplier"
-        else:
-            # Backward-compatibility: allow direct key -> value maps.
-            for override_key, override_value_raw in weight_overrides.items():
-                if isinstance(override_value_raw, dict):
-                    continue
-                override_value = _coerce_float(override_value_raw)
-                if override_value is None:
-                    continue
-                profile.weight_overrides[str(override_key)] = max(0.0, override_value)
-                has_overrides = True
-
-    gating_cfg = profile_info.get("gating")
-    if not isinstance(gating_cfg, dict):
-        gating_cfg = profile_info.get("scoring_gating")
-    if isinstance(gating_cfg, dict):
-        min_evidence = _coerce_float(gating_cfg.get("min_evidence_count"))
-        min_confidence = _coerce_float(gating_cfg.get("min_confidence"))
-        cap_score = _coerce_float(gating_cfg.get("cap_score"))
-        if min_evidence is not None:
-            profile.gating.min_evidence_count = max(0, int(min_evidence))
-        if min_confidence is not None:
-            profile.gating.min_confidence = min(max(min_confidence, 0.0), 1.0)
-        if cap_score is not None:
-            profile.gating.cap_score = min(max(cap_score, 0.0), 100.0)
-
-    docs_expected = _coerce_float(profile_info.get("docs_sources_expected"))
-    code_expected = _coerce_float(profile_info.get("code_sources_expected"))
-    if docs_expected is not None:
-        profile.docs_sources_expected = max(0, int(docs_expected))
-    if code_expected is not None:
-        profile.code_sources_expected = max(0, int(code_expected))
-
-    if not has_overrides and not isinstance(gating_cfg, dict) and docs_expected is None and code_expected is None:
-        return None
-    return profile
-
-
-def write_checklist_artifacts(
-    checklist: AuditChecklist,
-    output_dir: Path,
-    *,
-    template: AuditTemplate | None = None,
-    template_path: Path | None = None,
-    include_markdown: bool = True,
-    config: ChecklistExportConfig | None = None,
-) -> dict[str, Path]:
-    """Write all checklist artifacts to output directory.
-
-    Args:
-        checklist: The checklist to export.
-        output_dir: Directory for output files.
-        template: Template for generator (optional, for Excel export).
-        template_path: Path to template Excel file to copy and extend.
-        include_markdown: Whether to include Markdown export.
-        config: Export configuration options.
-
-    Returns:
-        Dict mapping format name to output path.
-    """
-    output_dir.mkdir(parents=True, exist_ok=True)
-
-    # Create minimal generator for exports
-    if template is None:
-        # Create dummy template for generator - won't be used for generation
-        template = AuditTemplate(
-            name=checklist.template_name,
-            version=checklist.template_version,
-            sections=[],
-        )
-
-    generator = ChecklistGenerator(
-        template=template,
-        template_hash=checklist.template_hash,
-        row_llm_mode=checklist.row_llm_mode,
-    )
-
-    written: dict[str, Path] = {}
-
-    # JSON export
-    json_path = output_dir / "audit-checklist.json"
-    generator.export_json(checklist, json_path)
-    written["json"] = json_path
-
-    # Excel export
-    xlsx_path = output_dir / "audit-checklist.xlsx"
-    generator.export_excel(checklist, xlsx_path, template_path=template_path, config=config)
-    written["xlsx"] = xlsx_path
-
-    # Projection sidecar metadata (TSK-341)
-    cfg = config or ChecklistExportConfig()
-    full_profile = canonical_excel_columns(cfg)
-    append_profile = template_append_columns(cfg)
-    sidecar_payload = {
-        "version": "1.0.0",
-        "projection_profile_version": PROJECTION_PROFILE_VERSION,
-        "generated_at": datetime.now(UTC).isoformat(),
-        "template_hash": checklist.template_hash,
-        "evidence_hash": checklist.evidence_hash,
-        "template_row_count": checklist.template_row_count,
-        "checklist_row_count": checklist.total_rows,
-        "base_locked_columns": [{"header": c.header, "key": c.key} for c in base_locked_columns()],
-        "canonical_excel_columns": [{"header": c.header, "key": c.key} for c in full_profile],
-        "template_append_columns": [{"header": c.header, "key": c.key} for c in append_profile],
-        "confluence_checklist_columns": [{"header": c.header, "key": c.key} for c in confluence_checklist_columns()],
-    }
-    sidecar_path = output_dir / "audit-checklist.meta.json"
-    sidecar_path.write_text(json.dumps(sidecar_payload, indent=2, ensure_ascii=False), encoding="utf-8")
-    written["meta"] = sidecar_path
-
-    # Markdown export (optional)
-    if include_markdown:
-        md_path = output_dir / "audit-checklist.md"
-        generator.export_markdown(checklist, md_path, config=config)
-        written["md"] = md_path
-
-    logger.info(
-        "checklist_artifacts_written",
-        output_dir=str(output_dir),
-        formats=list(written.keys()),
-    )
-
-    return written