@ngocsangairvds/vsaf 3.2.14 → 3.2.15

package/tools/vds-scripts/audit_orchestrator/tests/test_engine/test_confluence_checklist_projection_consistency.py

@@ -1,1696 +0,0 @@
-"""Regression tests for Confluence checklist projection consistency."""
-
-from __future__ import annotations
-
-import json
-
-import pytest
-from bs4 import BeautifulSoup
-from openpyxl import load_workbook
-from vds_audit_orchestrator.engine.checklist_projection import PROJECTION_PROFILE_VERSION
-from vds_audit_orchestrator.engine.confluence_checklist_contract import (
-    _build_checklist_meta_payload,
-    _sanitize_private_urls_in_payload,
-    _write_retrieval_trace_sidecar,
-    export_confluence_checklist_excel,
-)
-from vds_audit_orchestrator.engine.row_evaluator import RowEvaluator
-from vds_audit_orchestrator.engine.row_evaluator_types import RowEvaluationResult
-from vds_audit_orchestrator.models.checklist import (
-    AuditChecklist,
-    EvidenceAnchor,
-    RowProvenance,
-    RowStatus,
-    ScoreBreakdown,
-)
-from vds_audit_orchestrator.publishers.checklist_renderer import FullChecklistRenderer
-
-
-def test_confluence_contract_excel_uses_shared_rule_main_projection(tmp_path) -> None:
-    checklist = AuditChecklist.model_validate(
-        {
-            "checklist_version": "1.0.0",
-            "generated_at": "2026-02-04T10:00:00",
-            "template_name": "VDS Checklist",
-            "template_version": "1.0",
-            "template_hash": "abc123def456",
-            "template_row_count": 1,
-            "repository": "test-repo",
-            "row_llm_mode": "selective",
-            "evidence_hash": "xyz789abc012",
-            "rows": [
-                {
-                    "row_id": "SEC-001:row_0",
-                    "row_index": 0,
-                    "check_id": "SEC-001",
-                    "section_id": "SectionFallback",
-                    "requirement_category": "RuleA||MainA",
-                    "requirement_text": "Threat model required",
-                    "weight_raw": 10.0,
-                    "weight_adjusted": 10.0,
-                    "status": "FAIL",
-                    "score_breakdown": {"raw_score": 10.0, "final_score": 10.0},
-                    "evidence_refs": [{"ref_type": "code_path", "ref_value": "docs/THREAT_MODEL.md"}],
-                    "reason": "No threat model documentation found in repository",
-                    "finding": "Missing THREAT_MODEL.md or equivalent documentation",
-                    "provenance": {
-                        "row_llm_mode": "deterministic",
-                        "evaluated_at": "2026-02-04T10:00:00",
-                        "template_hash": "abc123",
-                        "evidence_hash": "xyz789",
-                    },
-                }
-            ],
-        }
-    )
-
-    output_path = tmp_path / "confluence-checklist.xlsx"
-    export_confluence_checklist_excel(checklist, output_path=output_path)
-
-    ws = load_workbook(output_path)["Checklist"]
-    assert ws["A2"].value == "RuleA"
-    assert ws["B2"].value == "MainA"
-    assert ws["C2"].value == "Threat model required"
-
-
-def test_row_projection_consistency_between_contract_excel_and_rendered_html(tmp_path) -> None:
-    checklist = AuditChecklist.model_validate(
-        {
-            "checklist_version": "1.0.0",
-            "generated_at": "2026-02-04T10:00:00",
-            "template_name": "VDS Checklist",
-            "template_version": "1.0",
-            "template_hash": "abc123def456",
-            "template_row_count": 1,
-            "repository": "test-repo",
-            "row_llm_mode": "selective",
-            "evidence_hash": "xyz789abc012",
-            "rows": [
-                {
-                    "row_id": "SEC-001:row_0",
-                    "row_index": 0,
-                    "check_id": "SEC-001",
-                    "section_id": "SectionFallback",
-                    "requirement_category": "QuyTacA||TieuChiChinhA",
-                    "requirement_text": "Threat model required",
-                    "weight_raw": 10.0,
-                    "weight_adjusted": 10.0,
-                    "status": "FAIL",
-                    "score_breakdown": {"raw_score": 10.0, "final_score": 10.0},
-                    "reason": "No threat model documentation found in repository",
-                    "finding": "Missing THREAT_MODEL.md or equivalent documentation",
-                    "provenance": {
-                        "row_llm_mode": "deterministic",
-                        "evaluated_at": "2026-02-04T10:00:00",
-                        "template_hash": "abc123",
-                        "evidence_hash": "xyz789",
-                    },
-                }
-            ],
-        }
-    )
-
-    output_path = tmp_path / "confluence-checklist.xlsx"
-    export_confluence_checklist_excel(checklist, output_path=output_path)
-    ws = load_workbook(output_path)["Checklist"]
-
-    html = FullChecklistRenderer().render(checklist, collapsed=False)
-    tables = BeautifulSoup(html, "html.parser").find_all("table")
-    assert len(tables) >= 2
-    # Phase 42: first table is strict core (Yêu cầu/Điểm/Trọng số),
-    # second table contains reasoning/evidence details.
-    core_first_row = tables[0].find_all("tr")[1]
-    core_cells = [cell.get_text(strip=True) for cell in core_first_row.find_all("td")]
-    detail_first_row = tables[1].find_all("tr")[1]
-    detail_cells = [cell.get_text(strip=True) for cell in detail_first_row.find_all("td")]
-
-    assert ws["C2"].value == core_cells[0]  # Tiêu chí con (requirement_text)
-    assert ws["C2"].value == detail_cells[0]  # Yêu cầu in details section
-
-
-def test_confluence_meta_includes_projection_profile_version_and_extended_columns(tmp_path) -> None:
-    checklist = AuditChecklist.model_validate(
-        {
-            "checklist_version": "1.0.0",
-            "generated_at": "2026-02-04T10:00:00",
-            "template_name": "VDS Checklist",
-            "template_version": "1.0",
-            "template_hash": "abc123def456",
-            "template_row_count": 1,
-            "repository": "test-repo",
-            "row_llm_mode": "selective",
-            "evidence_hash": "xyz789abc012",
-            "rows": [],
-        }
-    )
-    payload = _build_checklist_meta_payload(
-        checklist=checklist,
-        report_dir=tmp_path,
-        checklist_page_id="88716673",
-        confluence_meta={"title": "Checklist", "version": 12},
-        delta_payload={"targeted_run": False, "changed_row_count": 0, "merge_guardrail": {}},
-        retrieval_trace_path=tmp_path / "audit-checklist.retrieval-trace.json",
-    )
-
-    assert payload["projection_profile_version"] == PROJECTION_PROFILE_VERSION
-    extended_keys = [column["key"] for column in payload["columns"]["canonical_extended_columns"]]
-    assert payload["paths"]["retrieval_trace_json"].endswith("audit-checklist.retrieval-trace.json")
-    assert payload["preflight"]["requirement_mapping"] is None
-    assert payload["preflight"]["security_evidence"] is None
-    assert isinstance(payload["summary"], str)
-    assert isinstance(payload["synthesis"], dict)
-    assert isinstance(payload["evidence_quality"], dict)
-    assert isinstance(payload["reconciliation_source"], dict)
-    assert isinstance(payload["summary_meta_parity"], dict)
-    assert payload["summary_meta_parity_detected"] is False
-    assert payload["parity_mismatch"]["detected"] is False
-    assert extended_keys[:10] == [
-        "status_vietnamese",
-        "score_percent",
-        "score_1_5",
-        "reason",
-        "finding",
-        "evidence_refs_str",
-        "severity",
-        "priority",
-        "effort",
-        "recommendation",
-    ]
-
-
-def test_confluence_meta_includes_verification_coverage_summary(tmp_path) -> None:
-    checklist = AuditChecklist.model_validate(
-        {
-            "checklist_version": "1.0.0",
-            "generated_at": "2026-02-25T10:00:00",
-            "template_name": "VDS Checklist",
-            "template_version": "1.0",
-            "template_hash": "abc123def456",
-            "template_row_count": 2,
-            "repository": "test-repo",
-            "row_llm_mode": "selective",
-            "evidence_hash": "xyz789abc012",
-            "rows": [
-                {
-                    "row_id": "CL-001:row_0",
-                    "row_index": 0,
-                    "check_id": "CL-001",
-                    "section_id": "SEC",
-                    "requirement_text": "Row one",
-                    "weight_raw": 10.0,
-                    "weight_adjusted": 10.0,
-                    "status": "FAIL",
-                    "score_breakdown": {"raw_score": 20.0, "final_score": 20.0},
-                    "evidence_refs": [
-                        {
-                            "ref_type": "code_path",
-                            "ref_value": "Dockerfile",
-                            "excerpt": "FROM eclipse-temurin:21-jdk",
-                            "verified": True,
-                        },
-                        {
-                            "ref_type": "code_path",
-                            "ref_value": "Dockerfile",
-                            "excerpt": "USER app",
-                            "verified": False,
-                            "verification_reason": "excerpt_verification_disabled",
-                        },
-                    ],
-                    "reason": "Reason one",
-                    "finding": "Finding one",
-                    "provenance": {
-                        "row_llm_mode": "deterministic",
-                        "evaluated_at": "2026-02-25T10:00:00",
-                        "template_hash": "abc123",
-                        "evidence_hash": "xyz789",
-                    },
-                },
-                {
-                    "row_id": "CL-002:row_1",
-                    "row_index": 1,
-                    "check_id": "CL-002",
-                    "section_id": "SEC",
-                    "requirement_text": "Row two",
-                    "weight_raw": 10.0,
-                    "weight_adjusted": 10.0,
-                    "status": "PARTIAL",
-                    "score_breakdown": {"raw_score": 60.0, "final_score": 60.0},
-                    "evidence_refs": [
-                        {
-                            "ref_type": "confluence_url",
-                            "ref_value": "https://confluence.local/page",
-                            "excerpt": "",
-                            "verified": False,
-                        }
-                    ],
-                    "reason": "Reason two",
-                    "finding": "Finding two",
-                    "provenance": {
-                        "row_llm_mode": "deterministic",
-                        "evaluated_at": "2026-02-25T10:00:00",
-                        "template_hash": "abc123",
-                        "evidence_hash": "xyz789",
-                    },
-                },
-            ],
-        }
-    )
-
-    payload = _build_checklist_meta_payload(
-        checklist=checklist,
-        report_dir=tmp_path,
-        checklist_page_id="88716673",
-        confluence_meta={"title": "Checklist", "version": 13},
-        delta_payload={"targeted_run": False, "changed_row_count": 0, "merge_guardrail": {}},
-        retrieval_trace_path=tmp_path / "audit-checklist.retrieval-trace.json",
-    )
-
-    verification = payload["verification"]
-    assert verification["row_count"] == 2
-    assert verification["rows_with_any_refs"] == 2
-    assert verification["rows_with_verified_refs"] == 1
-    assert verification["rows_with_unverified_refs"] == 2
-    assert verification["verified_true_count"] == 1
-    assert verification["verified_false_count"] == 2
-    assert verification["verified_ratio"] == 1 / 3
-    assert verification["verification_reason_breakdown"] == {
-        "excerpt_verification_disabled": 1,
-        "no_excerpt_to_verify": 1,
-    }
-
-
-def test_retrieval_trace_sidecar_includes_verification_coverage_runtime_and_row_diagnostics(tmp_path) -> None:
-    row_results = [
-        RowEvaluationResult(
-            row_id="CL-001:row_0",
-            check_id="CL-001",
-            status=RowStatus.PARTIAL,
-            score=60.0,
-            score_breakdown=ScoreBreakdown.compute(raw_score=60.0),
-            reason="Row one",
-            finding="Finding one",
-            evidence_anchors=[
-                EvidenceAnchor(
-                    ref_type="code_path",
-                    ref_value="src/service.py",
-                    excerpt="def run(): pass",
-                    verified=True,
-                ),
-                EvidenceAnchor(
-                    ref_type="doc_path",
-                    ref_value="docs/runbook.md",
-                    excerpt="",
-                    verified=False,
-                ),
-            ],
-            provenance=RowProvenance(row_llm_mode="per-row", template_hash="tpl", evidence_hash="evd"),
-            retrieval_trace={"mode": "hybrid"},
-        ),
-        RowEvaluationResult(
-            row_id="CL-002:row_1",
-            check_id="CL-002",
-            status=RowStatus.FAIL,
-            score=10.0,
-            score_breakdown=ScoreBreakdown.compute(raw_score=10.0),
-            reason="Row two",
-            finding="Finding two",
-            evidence_anchors=[
-                EvidenceAnchor(
-                    ref_type="code_path",
-                    ref_value="Dockerfile",
-                    excerpt="USER app",
-                    verified=False,
-                    verification_reason="excerpt_verification_disabled",
-                ),
-            ],
-            provenance=RowProvenance(row_llm_mode="per-row", template_hash="tpl", evidence_hash="evd"),
-            retrieval_trace={},
-        ),
-    ]
-
-    output_path = tmp_path / "audit-checklist.retrieval-trace.json"
-    _write_retrieval_trace_sidecar(output_path, row_results=row_results)
-    payload = json.loads(output_path.read_text(encoding="utf-8"))
-
-    verification = payload["verification"]
-    assert verification["row_count"] == 2
-    assert verification["rows_with_any_refs"] == 2
-    assert verification["rows_with_verified_refs"] == 1
-    assert verification["rows_with_unverified_refs"] == 2
-    assert verification["verified_true_count"] == 1
-    assert verification["verified_false_count"] == 2
-    assert verification["verified_ratio"] == 1 / 3
-    assert verification["verification_reason_breakdown"] == {
-        "no_excerpt_to_verify": 1,
-        "excerpt_verification_disabled": 1,
-    }
-
-    first_row_verification = payload["rows"][0]["verification_coverage"]
-    assert first_row_verification["row_ref_count"] == 2
-    assert first_row_verification["verified_true_count"] == 1
-    assert first_row_verification["verified_false_count"] == 1
-    assert first_row_verification["verification_reason_breakdown"] == {"no_excerpt_to_verify": 1}
-    assert payload["rows"][0]["retrieval_trace"]["verification_coverage"]["verified_true_count"] == 1
-
-
-def test_retrieval_trace_sidecar_prefers_exported_evidence_refs_for_verification(tmp_path) -> None:
-    exported_anchors = [
-        EvidenceAnchor(
-            ref_type="code_path",
-            ref_value="src/service_a.py",
-            excerpt="class ServiceA:",
-            verified=True,
-            verification_reason="excerpt_verified_in_context",
-        ),
-        EvidenceAnchor(
-            ref_type="code_path",
-            ref_value="src/service_b.py",
-            excerpt="class ServiceB:",
-            verified=True,
-            verification_reason="excerpt_verified_in_context",
-        ),
-    ]
-    raw_internal_anchors = [
-        *exported_anchors,
-        EvidenceAnchor(
-            ref_type="knowledge_ref",
-            ref_value="knowledge:legacy-fallback",
-            excerpt="",
-            verified=False,
-            verification_reason="fallback_ref_inherited",
-        ),
-    ]
-    row_results = [
-        {
-            "row_id": "CL-002:row_1",
-            "check_id": "CL-002",
-            "status": "FAIL",
-            "score": 23.75,
-            "reason": "Decisive code evidence confirms a violation.",
-            "finding": "Concrete implementation dependency detected.",
-            "evidence_refs": exported_anchors,
-            "evidence_anchors": raw_internal_anchors,
-            "retrieval_trace": {
-                "verification_coverage_export": {
-                    "row_ref_count": 2,
-                    "has_any_refs": True,
-                    "has_verified_refs": True,
-                    "has_unverified_refs": False,
-                    "verified_true_count": 2,
-                    "verified_false_count": 0,
-                    "verified_ratio": 1.0,
-                    "verification_reason_breakdown": {
-                        "excerpt_verified_in_context": 2,
-                    },
-                }
-            },
-            "provenance": RowProvenance(row_llm_mode="per-row", template_hash="tpl", evidence_hash="evd"),
-        }
-    ]
-
-    output_path = tmp_path / "audit-checklist.retrieval-trace.json"
-    _write_retrieval_trace_sidecar(output_path, row_results=row_results)
-    payload = json.loads(output_path.read_text(encoding="utf-8"))
-
-    verification = payload["verification"]
-    assert verification["row_count"] == 1
-    assert verification["rows_with_unverified_refs"] == 0
-    assert verification["verified_true_count"] == 2
-    assert verification["verified_false_count"] == 0
-    assert verification["verified_ratio"] == 1.0
-
-    first_row_verification = payload["rows"][0]["verification_coverage"]
-    assert first_row_verification["row_ref_count"] == 2
-    assert first_row_verification["verified_true_count"] == 2
-    assert first_row_verification["verified_false_count"] == 0
-    assert first_row_verification["verification_reason_breakdown"] == {
-        "excerpt_verified_in_context": 2,
-    }
-
-
-def test_retrieval_trace_sidecar_tool_summary_falls_back_to_timeout_progress_snapshot(tmp_path) -> None:
-    row_results = [
-        RowEvaluationResult(
-            row_id="CL-999:row_0",
-            check_id="CL-999",
-            status=RowStatus.ERROR,
-            score=0.0,
-            score_breakdown=ScoreBreakdown.compute(raw_score=0.0),
-            reason="Timeout during evaluation",
-            finding="Timed out",
-            evidence_anchors=[],
-            provenance=RowProvenance(row_llm_mode="per-row", template_hash="tpl", evidence_hash="evd"),
-            retrieval_trace={
-                "timeout_progress_snapshot": {
-                    "steps_executed": 5,
-                    "steps_unique_tools": 4,
-                    "termination_reason": "stagnation",
-                    "budget_remaining": 3,
-                    "elapsed_seconds": 1.234,
-                    "evidence_refs_count": 6,
-                    "docs_search_count": 1,
-                    "docs_read_count": 2,
-                    "code_search_count": 1,
-                    "code_read_count": 1,
-                    "record_evidence_refs_count": 0,
-                    "row_context_count": 1,
-                }
-            },
-        )
-    ]
-
-    output_path = tmp_path / "audit-checklist.retrieval-trace.json"
-    _write_retrieval_trace_sidecar(output_path, row_results=row_results)
-    payload = json.loads(output_path.read_text(encoding="utf-8"))
-
-    summary = payload["rows"][0]["tool_call_summary"]
-    assert summary == {
-        "total_steps": 5,
-        "unique_tools": 4,
-        "termination_reason": "stagnation",
-        "budget_remaining": 3,
-        "elapsed_seconds": 1.234,
-        "evidence_refs_count": 6,
-        "docs_search_count": 1,
-        "docs_read_count": 2,
-        "code_search_count": 1,
-        "code_read_count": 1,
-        "record_evidence_refs_count": 0,
-        "record_evidence_refs_required": True,
-        "record_evidence_refs_contract_met": False,
-        "record_evidence_refs_fallback_capture": False,
-        "record_evidence_refs_capture_failure_reason": "record_evidence_refs_not_called",
-        "route_escalation_required": False,
-        "route_escalation_applied": False,
-        "route_escalation_reason": False,
-        "route_escalation_step_index": False,
-        "row_context_count": 1,
-        "top_k_code_read_contract_applies": False,
-        "top_k_target": 0,
-        "top_k_read_count": 0,
-        "top_k_read_met": False,
-        "top_k_read_shortfall_reason": False,
-        "top_k_effective": 0,
-        "top_k_fallback_applied": False,
-        "top_k_bounded_soft_pass": False,
-        "db_family_requirement": False,
-        "db_family_candidate_count": 0,
-        "db_family_pass_1_candidates": 0,
-        "db_family_pass_2_candidates": 0,
-        "db_family_config_database_hits": 0,
-        "db_family_repository_hits": 0,
-        "db_family_service_impl_hits": 0,
-        "db_family_selected_read_hits": 0,
-        "db_family_selected_read_coverage_met": False,
-        "db_family_selected_read_shortfall_reason": False,
-        "db_search_no_candidates_reason": False,
-        "db_family_retrieval_insufficient": False,
-        "db_family_coverage_gap_reason": False,
-        "term_origin_map": False,
-        "term_origin_map_term_count": 0,
-    }
-
-
-def test_retrieval_trace_sidecar_projects_phase124_timeout_diagnostics(tmp_path) -> None:
-    row_results = [
-        RowEvaluationResult(
-            row_id="CL-004:row_3",
-            check_id="CL-004",
-            status=RowStatus.FAIL,
-            score=0.0,
-            score_breakdown=ScoreBreakdown.compute(raw_score=0.0),
-            reason="Timeout during evaluation",
-            finding="Timed out after grounded progress",
-            evidence_anchors=[],
-            provenance=RowProvenance(row_llm_mode="per-row", template_hash="tpl", evidence_hash="evd"),
-            retrieval_trace={
-                "timeout_kind": "timeout_with_grounding",
-                "timeout_progress_snapshot": {
-                    "route_id": "code_search_read_verify_synthesize",
-                    "route_mode": "code_only",
-                    "route_reason": "project_scope_required=true",
-                    "project_artifact_readiness": {
-                        "readiness_status": "partial",
-                        "authoritative_artifact_ready": False,
-                        "missing_artifact_types": ["dependency_graph"],
-                    },
-                    "project_artifact_provenance_summary": [
-                        {"artifact_type": "dependency_graph", "source": "knowledge_store"}
-                    ],
-                    "grounding_validation": {
-                        "complete": False,
-                        "timeout_incomplete": True,
-                    },
-                    "evidence_gap_diagnostics": {
-                        "applied": True,
-                        "classification": "confirmed_gap",
-                        "gap_type": "authoritative_project_scope_artifact_missing",
-                    },
-                    "requirement_interpretation": {
-                        "intent": "No circular dependency across modules/services.",
-                        "control_objective": "1. Decoupling",
-                        "project_scope_required": True,
-                    },
-                },
-            },
-        )
-    ]
-
-    output_path = tmp_path / "audit-checklist.retrieval-trace.json"
-    _write_retrieval_trace_sidecar(output_path, row_results=row_results)
-    payload = json.loads(output_path.read_text(encoding="utf-8"))
-
-    row = payload["rows"][0]
-    assert row["route_mode"] == "code_only"
-    assert row["route_id"] == "code_search_read_verify_synthesize"
-    assert row["project_artifact_readiness"] == {
-        "readiness_status": "partial",
-        "authoritative_artifact_ready": False,
-        "missing_artifact_types": ["dependency_graph"],
-    }
-    assert row["project_artifact_provenance_summary"] == [
-        {"artifact_type": "dependency_graph", "source": "knowledge_store"}
-    ]
-    assert row["grounding_validation"]["timeout_incomplete"] is True
-    assert row["evidence_gap_diagnostics"]["gap_type"] == "authoritative_project_scope_artifact_missing"
-
-
-def test_retrieval_trace_sidecar_includes_app_config_discovery_summary(tmp_path) -> None:
-    row_results = [
-        RowEvaluationResult(
-            row_id="CL-005:row_4",
-            check_id="CL-005",
-            status=RowStatus.PARTIAL,
-            score=61.0,
-            score_breakdown=ScoreBreakdown.compute(raw_score=61.0),
-            reason="App-config evidence is only partially decisive.",
-            finding="Datasource and schema candidates were found, but environment resolution remains incomplete.",
-            evidence_anchors=[],
-            provenance=RowProvenance(row_llm_mode="per-row", template_hash="tpl", evidence_hash="evd"),
-            retrieval_trace={
-                "requirement_interpretation": {
-                    "intent": "Verify separate schema, datasource, and pool settings from app-config.",
-                    "control_objective": "CL-005",
-                    "app_config_discovery": {
-                        "target_repo": "merchant-report",
-                        "target_environment": "production",
-                        "environment_detected": "prod",
-                        "discovery_status": "partial",
-                        "config_sources": [
-                            {"source_type": "app_repo_config"},
-                            {"source_type": "helm_values"},
-                        ],
-                        "precedence_chain": [{"step_rank": 1}],
-                        "findings": [
-                            {"finding_type": "datasource", "evidence_strength": "decisive"},
-                            {"finding_type": "schema", "evidence_strength": "partial"},
-                        ],
-                        "unresolved_gaps": [
-                            {"gap_type": "environment_resolution", "severity": "blocking"},
-                        ],
-                        "confidence": 0.85,
-                        "decisive": True,
-                    },
-                },
-                "app_config_discovery_summary": {
-                    "target_repo": "merchant-report",
-                    "target_environment": "production",
-                    "environment_detected": "prod",
-                    "discovery_status": "partial",
-                    "confidence": 0.85,
-                    "decisive": True,
-                    "config_source_count": 2,
-                    "precedence_step_count": 1,
-                    "finding_count": 2,
-                    "decisive_finding_count": 1,
-                    "unresolved_gap_count": 1,
-                    "blocking_gap_count": 1,
-                    "config_source_types": ["app_repo_config", "helm_values"],
-                    "finding_types": ["datasource", "schema"],
-                    "gap_types": ["environment_resolution"],
-                },
-            },
-        )
-    ]
-
-    output_path = tmp_path / "audit-checklist.retrieval-trace.json"
-    _write_retrieval_trace_sidecar(output_path, row_results=row_results)
-    payload = json.loads(output_path.read_text(encoding="utf-8"))
-
-    row = payload["rows"][0]
-    assert row["app_config_discovery_summary"] == {
-        "target_repo": "merchant-report",
-        "target_environment": "production",
-        "environment_detected": "prod",
-        "discovery_status": "partial",
-        "confidence": 0.85,
-        "decisive": True,
-        "config_source_count": 2,
-        "precedence_step_count": 1,
-        "finding_count": 2,
-        "decisive_finding_count": 1,
-        "unresolved_gap_count": 1,
-        "blocking_gap_count": 1,
-        "config_source_types": ["app_repo_config", "helm_values"],
-        "finding_types": ["datasource", "schema"],
-        "gap_types": ["environment_resolution"],
-    }
-    assert row["retrieval_trace"]["app_config_discovery_summary"]["discovery_status"] == "partial"
-
-
-def test_retrieval_trace_sidecar_aligns_app_config_summary_with_final_cited_config_env(tmp_path) -> None:
-    row_results = [
-        {
-            "row_id": "CL-015:row_14",
-            "check_id": "CL-015",
-            "status": "PARTIAL",
-            "score": 40.0,
-            "retry_count": 0,
-            "retrieval_trace": {
-                "route_mode": "code_only",
-                "route_id": "code_search_read_verify_synthesize",
-                "app_config_discovery_summary": {
-                    "target_repo": "cdcn-policy-management-service",
-                    "target_environment": "alpha",
-                    "environment_detected": "alpha",
-                    "discovery_status": "resolved",
-                    "confidence": 0.9,
-                    "decisive": True,
-                    "config_source_count": 3,
-                    "precedence_step_count": 3,
-                    "finding_count": 0,
-                    "decisive_finding_count": 1,
-                    "unresolved_gap_count": 0,
-                    "blocking_gap_count": 0,
-                    "config_source_types": ["config"],
-                    "finding_types": ["config_source_discovered_env_specific_match"],
-                    "gap_types": [],
-                },
-                "final_cited_refs": ["staging/application.yml"],
-            },
-            "evidence_anchors": [],
-        }
-    ]
-
-    output_path = tmp_path / "audit-checklist.retrieval-trace.json"
-    _write_retrieval_trace_sidecar(output_path, row_results=row_results)  # type: ignore[arg-type]
-    payload = json.loads(output_path.read_text(encoding="utf-8"))
-
-    row = payload["rows"][0]
-    assert row["final_cited_refs"] == ["staging/application.yml"]
-    assert row["app_config_discovery_summary"]["target_environment"] == "staging"
-    assert row["app_config_discovery_summary"]["environment_detected"] == "staging"
-
-
-def test_retrieval_trace_sidecar_tool_summary_emits_db_family_and_term_origin_telemetry(tmp_path) -> None:
-    row_results = [
-        RowEvaluationResult(
-            row_id="CL-004:row_3",
-            check_id="CL-004",
-            status=RowStatus.ERROR,
-            score=0.0,
-            score_breakdown=ScoreBreakdown.compute(raw_score=0.0),
-            reason="grounding failure",
-            finding="grounding failure",
-            evidence_anchors=[],
-            provenance=RowProvenance(row_llm_mode="per-row", template_hash="tpl", evidence_hash="evd"),
-            retrieval_trace={
-                "tool_first_loop": {
-                    "steps_executed": 6,
-                    "code_search_count": 2,
-                    "code_read_count": 1,
-                    "docs_intent_utilization": {
-                        "route_escalation_required": True,
-                        "route_escalation_applied": True,
-                        "route_escalation_reason": "docs_only_route_code_fallback",
-                        "route_escalation_step_index": 3,
-                    },
-                    "db_family_requirement": True,
-                    "db_family_candidate_count": 3,
-                    "db_family_pass_1_candidates": 5,
-                    "db_family_pass_2_candidates": 3,
-                    "db_family_config_database_hits": 1,
-                    "db_family_repository_hits": 1,
-                    "db_family_service_impl_hits": 1,
-                    "db_family_selected_read_hits": 2,
-                    "db_search_no_candidates_reason": "db_search_no_candidates",
-                    "db_family_retrieval_insufficient": True,
-                    "db_family_coverage_gap_reason": "none",
-                    "term_origin_map": {
-                        "datasource": "db_query_expansion",
-                        "kết nối": "requirement_term_vi",
-                    },
-                }
-            },
-        )
-    ]
-
-    output_path = tmp_path / "audit-checklist.retrieval-trace.json"
-    _write_retrieval_trace_sidecar(output_path, row_results=row_results)
-    payload = json.loads(output_path.read_text(encoding="utf-8"))
-
-    summary = payload["rows"][0]["tool_call_summary"]
-    assert summary["db_family_requirement"] is True
-    assert summary["db_family_candidate_count"] == 3
-    assert summary["db_family_pass_1_candidates"] == 5
-    assert summary["db_family_pass_2_candidates"] == 3
-    assert summary["db_family_config_database_hits"] == 1
-    assert summary["db_family_repository_hits"] == 1
-    assert summary["db_family_service_impl_hits"] == 1
-    assert summary["db_family_selected_read_hits"] == 2
-    assert summary["db_family_selected_read_coverage_met"] is True
-    assert summary["db_family_selected_read_shortfall_reason"] is False
-    assert summary["db_search_no_candidates_reason"] == "db_search_no_candidates"
-    assert summary["db_family_retrieval_insufficient"] is True
-    assert summary["route_escalation_required"] is True
-    assert summary["route_escalation_applied"] is True
-    assert summary["route_escalation_reason"] == "docs_only_route_code_fallback"
-    assert summary["route_escalation_step_index"] == 3
-    assert summary["db_family_coverage_gap_reason"] == "none"
-    assert summary["term_origin_map_term_count"] == 2
-    assert isinstance(summary["term_origin_map"], dict)
-
-
-def test_retrieval_trace_sidecar_tool_summary_preserves_record_evidence_fallback_capture(tmp_path) -> None:
-    row_results = [
-        RowEvaluationResult(
-            row_id="CL-001:row_0",
-            check_id="CL-001",
-            status=RowStatus.FAIL,
-            score=24.75,
-            score_breakdown=ScoreBreakdown.compute(raw_score=24.75),
-            reason="fallback capture",
-            finding="fallback capture",
-            evidence_anchors=[],
-            provenance=RowProvenance(row_llm_mode="per-row", template_hash="tpl", evidence_hash="evd"),
-            retrieval_trace={
-                "tool_first_loop": {
-                    "steps_executed": 5,
-                    "docs_read_count": 2,
-                    "code_read_count": 3,
-                    "record_evidence_refs_count": 0,
-                    "record_evidence_refs_required": True,
-                    "record_evidence_refs_contract_met": True,
-                    "record_evidence_refs_fallback_capture": True,
-                    "record_evidence_refs_capture_failure_reason": "record_evidence_refs_hydrated_from_trace",
-                }
-            },
-        )
-    ]
-
-    output_path = tmp_path / "audit-checklist.retrieval-trace.json"
-    _write_retrieval_trace_sidecar(output_path, row_results=row_results)
-    payload = json.loads(output_path.read_text(encoding="utf-8"))
-
-    summary = payload["rows"][0]["tool_call_summary"]
-    assert summary["record_evidence_refs_contract_met"] is True
-    assert summary["record_evidence_refs_fallback_capture"] is True
-    assert summary["record_evidence_refs_capture_failure_reason"] == "record_evidence_refs_hydrated_from_trace"
-
-
-def test_retrieval_trace_sidecar_tool_summary_infers_fallback_capture_from_failure_reason(tmp_path) -> None:
-    row_results = [
-        RowEvaluationResult(
-            row_id="CL-001:row_0",
-            check_id="CL-001",
-            status=RowStatus.FAIL,
-            score=24.75,
-            score_breakdown=ScoreBreakdown.compute(raw_score=24.75),
-            reason="fallback capture",
-            finding="fallback capture",
-            evidence_anchors=[],
-            provenance=RowProvenance(row_llm_mode="per-row", template_hash="tpl", evidence_hash="evd"),
-            retrieval_trace={
-                "tool_first_loop": {
-                    "steps_executed": 5,
-                    "docs_read_count": 2,
-                    "code_read_count": 3,
-                    "record_evidence_refs_count": 0,
-                    "record_evidence_refs_required": True,
-                    "record_evidence_refs_contract_met": True,
-                    "record_evidence_refs_capture_failure_reason": "record_evidence_refs_hydrated_from_trace",
-                }
-            },
-        )
-    ]
-
-    output_path = tmp_path / "audit-checklist.retrieval-trace.json"
-    _write_retrieval_trace_sidecar(output_path, row_results=row_results)
-    payload = json.loads(output_path.read_text(encoding="utf-8"))
-
-    summary = payload["rows"][0]["tool_call_summary"]
-    assert summary["record_evidence_refs_contract_met"] is True
-    assert summary["record_evidence_refs_fallback_capture"] is True
-    assert summary["record_evidence_refs_capture_failure_reason"] == "record_evidence_refs_hydrated_from_trace"
-
-
-def test_retrieval_trace_sidecar_accepts_dict_rows_for_targeted_merge_refresh(tmp_path) -> None:
-    row_results = [
-        {
-            "row_id": "R1",
-            "check_id": "CL-001",
-            "status": "FAIL",
-            "score": 24.75,
-            "retry_count": 1,
-            "retry_metadata": {
-                "corrective_retry_attempted": True,
-                "corrective_retry_outcome": "retry_rejected_no_improvement",
-                "corrective_retry_trigger_reason": "unverified_ref_ratio_threshold",
-                "corrective_retry_guardrail_applied": True,
-            },
-            "retrieval_trace": {
-                "tool_first_loop": {
-                    "steps_executed": 5,
-                    "record_evidence_refs_count": 0,
-                    "record_evidence_refs_required": True,
-                    "record_evidence_refs_contract_met": True,
-                    "record_evidence_refs_capture_failure_reason": "record_evidence_refs_hydrated_from_trace",
-                }
-            },
-            "evidence_anchors": [],
-        }
-    ]
-
-    output_path = tmp_path / "audit-checklist.retrieval-trace.json"
-    _write_retrieval_trace_sidecar(output_path, row_results=row_results)  # type: ignore[arg-type]
-    payload = json.loads(output_path.read_text(encoding="utf-8"))
-
-    row = payload["rows"][0]
-    assert row["row_id"] == "R1"
-    assert row["status"] == "FAIL"
-    assert row["score"] == 24.75
-    assert row["retry_count"] == 1
-    assert row["retry_attempted"] is True
-    assert row["retry_outcome"] == "retry_rejected_no_improvement"
-    assert row["retry_trigger_reason"] == "unverified_ref_ratio_threshold"
-    assert row["retry_guardrail_applied"] is True
-    assert row["tool_call_summary"]["record_evidence_refs_fallback_capture"] is True
-
-
-def test_retrieval_trace_sidecar_projects_top_level_route_and_retention_fields(tmp_path) -> None:
-    row_results = [
-        {
-            "row_id": "R1",
-            "check_id": "CL-013",
-            "status": "FAIL",
-            "score": 16.5,
-            "retry_count": 1,
-            "retrieval_trace": {
-                "route_mode": "hybrid_code_first",
-                "route_id": "hybrid_code_first_search_read_verify_synthesize",
-                "route_transition_reasons": ["code_first_requirement", "code_search_narrowing"],
-                "selection_blocked_reason": "missing_infra_artifact_candidate",
-                "exploratory_ref_count": 10,
-                "final_cited_ref_count": 2,
-                "final_cited_refs": ["src/service_a.py", "docs/guide.md"],
-                "citation_retention_rate": 0.2,
-                "tool_first_loop": {
-                    "docs_search_count": 1,
-                    "docs_read_count": 2,
-                    "code_search_count": 1,
-                    "code_read_count": 3,
-                    "route_escalation_reason": "docs_only_route_code_fallback",
-                },
-            },
-            "evidence_anchors": [],
-        }
-    ]
-
-    output_path = tmp_path / "audit-checklist.retrieval-trace.json"
-    _write_retrieval_trace_sidecar(output_path, row_results=row_results)  # type: ignore[arg-type]
-    payload = json.loads(output_path.read_text(encoding="utf-8"))
-
-    row = payload["rows"][0]
-    assert row["route_mode"] == "hybrid_code_first"
-    assert row["route_id"] == "hybrid_code_first_search_read_verify_synthesize"
-    assert row["route_transition_reasons"] == ["code_first_requirement", "code_search_narrowing"]
-    assert row["selection_blocked_reason"] == "missing_infra_artifact_candidate"
-    assert row["docs_search_count"] == 1
-    assert row["docs_read_count"] == 2
-    assert row["code_search_count"] == 1
-    assert row["code_read_count"] == 3
-    assert row["exploratory_ref_count"] == 10
-    assert row["final_cited_ref_count"] == 2
-    assert row["final_cited_refs"] == ["src/service_a.py", "docs/guide.md"]
-    assert row["citation_retention_rate"] == pytest.approx(0.2, abs=1e-9)
-    assert row["route_escalation_reason"] == "docs_only_route_code_fallback"
-
-
-def test_retrieval_trace_sidecar_projects_route_and_retention_from_nested_trace_only(tmp_path) -> None:
-    row_results = [
-        {
-            "row_id": "R1",
-            "check_id": "CL-004",
-            "status": "PARTIAL",
-            "score": 76.5,
-            "retry_count": 0,
-            "retrieval_trace": {
-                "tool_first_loop": {
-                    "route_mode": "hybrid_code_first",
-                    "route_id": "hybrid_code_first_search_read_verify_synthesize",
-                    "route_transition_reasons": ["code_first_requirement"],
-                    "selection_blocked_reason": "missing_infra_artifact_candidate",
-                    "docs_search_count": 1,
-                    "docs_read_count": 2,
-                    "code_search_count": 1,
-                    "code_read_count": 1,
-                },
-                "evidence_ref_sets": {
-                    "exploratory_ref_count": 10,
-                    "final_cited_ref_count": 2,
-                    "final_cited_refs": ["src/service_a.py", "docs/guide.md"],
-                },
-            },
-            "evidence_anchors": [],
-        }
-    ]
-
-    output_path = tmp_path / "audit-checklist.retrieval-trace.json"
-    _write_retrieval_trace_sidecar(output_path, row_results=row_results)  # type: ignore[arg-type]
-    payload = json.loads(output_path.read_text(encoding="utf-8"))
-
-    row = payload["rows"][0]
-    assert row["route_mode"] == "hybrid_code_first"
-    assert row["route_id"] == "hybrid_code_first_search_read_verify_synthesize"
-    assert row["route_transition_reasons"] == ["code_first_requirement"]
-    assert row["selection_blocked_reason"] == "missing_infra_artifact_candidate"
-    assert row["docs_search_count"] == 1
-    assert row["docs_read_count"] == 2
-    assert row["code_search_count"] == 1
-    assert row["code_read_count"] == 1
-    assert row["exploratory_ref_count"] == 10
-    assert row["final_cited_ref_count"] == 2
-    assert row["final_cited_refs"] == ["src/service_a.py", "docs/guide.md"]
-
-
-def test_retrieval_trace_sidecar_projects_surfaces_prior_knowledge_and_recommended_skill(tmp_path) -> None:
-    row_results = [
-        {
-            "row_id": "CL-002:row_1",
-            "check_id": "CL-002",
-            "status": "PARTIAL",
-            "score": 40.0,
-            "retry_count": 0,
-            "retrieval_trace": {
-                "tool_first_loop": {
-                    "route_mode": "code_only",
-                    "route_id": "code_search_read_verify_synthesize",
-                    "code_search_count": 1,
-                    "code_read_count": 4,
-                    "prior_knowledge_refs": [
-                        {
-                            "ref_type": "prior_knowledge",
-                            "ref_value": "knowledge:public-interface-scan",
-                            "excerpt": "[Prior knowledge][par-merchant-report] boundary candidate scan",
-                            "knowledge_type": "public_interface_boundary_project_scan",
-                            "knowledge_modality": "code_linked_knowledge",
-                            "linked_ref_values": [
-                                "src/main/java/com/example/port/PublicApi.java",
-                                "src/main/java/com/example/adapter/PublicApiAdapter.java",
-                            ],
-                        }
-                    ],
-                },
-                "skill_policy_retry": {
-                    "required": True,
-                    "strict_require_effective_skill": True,
-                    "observed_skill_calls": 1,
-                    "observed_skill_execution_calls": 1,
-                    "observed_skill_effective_calls": 1,
-                    "recommended_skills": ["public-interface-boundary-skill"],
-                },
-                "skill_tool_usage": [
-                    {
-                        "tool": "run_skill_script",
-                        "skill": "public-interface-boundary-skill",
-                        "script": "scripts/scan_project.py",
-                        "effective": True,
-                    }
-                ],
-                "evidence_ref_sets": {
-                    "final_cited_ref_count": 2,
-                    "final_cited_refs": [
-                        "src/main/java/com/example/port/PublicApi.java",
-                        "src/main/java/com/example/adapter/PublicApiAdapter.java",
-                    ],
-                },
-            },
-            "evidence_anchors": [],
-        }
-    ]
-
-    output_path = tmp_path / "audit-checklist.retrieval-trace.json"
-    _write_retrieval_trace_sidecar(output_path, row_results=row_results)  # type: ignore[arg-type]
-    payload = json.loads(output_path.read_text(encoding="utf-8"))
-
-    row = payload["rows"][0]
-    assert row["recommended_skills"] == ["public-interface-boundary-skill"]
-    assert row["observed_skill_calls"] == 1
-    assert row["observed_skill_execution_calls"] == 1
-    assert row["observed_skill_effective_calls"] == 1
-    assert row["skill_tool_usage"] == [
-        {
-            "tool": "run_skill_script",
-            "skill": "public-interface-boundary-skill",
-            "script": "scripts/scan_project.py",
-            "effective": True,
-        }
-    ]
-    assert row["prior_knowledge_refs"] == [
-        {
-            "ref_type": "prior_knowledge",
-            "ref_value": "knowledge:public-interface-scan",
-            "excerpt": "[Prior knowledge][par-merchant-report] boundary candidate scan",
-            "knowledge_type": "public_interface_boundary_project_scan",
-            "knowledge_modality": "code_linked_knowledge",
-            "linked_ref_values": [
-                "src/main/java/com/example/port/PublicApi.java",
-                "src/main/java/com/example/adapter/PublicApiAdapter.java",
-            ],
-        }
-    ]
-    assert row["final_cited_refs"] == [
-        "src/main/java/com/example/port/PublicApi.java",
-        "src/main/java/com/example/adapter/PublicApiAdapter.java",
-    ]
-
-
-def test_retrieval_trace_sidecar_projects_requirement_analysis_diagnostics(tmp_path) -> None:
-    row_results = [
-        {
-            "row_id": "R1",
-            "check_id": "CL-036",
-            "status": "FAIL",
-            "score": 12.0,
-            "retry_count": 0,
-            "retrieval_trace": {
-                "tool_first_loop": {
-                    "code_ranking_diagnostics": {
-                        "requirement_analysis": {
-                            "analysis_mode": "code_first",
-                            "analysis_reason_codes": ["code_first_requirement"],
-                            "required_anchor_modalities": ["code"],
-                            "generic_anchor_exemption": False,
-                            "minimum_substantive_code_anchors": 1,
-                            "finalization_policy": "code_substantive_required",
-                        }
-                    }
-                }
-            },
-            "evidence_anchors": [],
-        }
-    ]
-
-    output_path = tmp_path / "audit-checklist.retrieval-trace.json"
-    _write_retrieval_trace_sidecar(output_path, row_results=row_results)  # type: ignore[arg-type]
-    payload = json.loads(output_path.read_text(encoding="utf-8"))
-
-    row = payload["rows"][0]
-    assert row["analysis_mode"] == "code_first"
-    assert row["analysis_reason_codes"] == ["code_first_requirement"]
-    assert row["required_anchor_modalities"] == ["code"]
-    assert row["generic_anchor_exemption"] is False
-    assert row["minimum_substantive_code_anchors"] == 1
-    assert row["finalization_policy"] == "code_substantive_required"
-
-
-def test_retrieval_trace_sidecar_derives_requirement_analysis_from_interpretation(tmp_path) -> None:
-    row_results = [
-        {
-            "row_id": "R2",
-            "check_id": "CL-003",
-            "status": "FAIL",
-            "score": 20.75,
-            "retry_count": 0,
-            "retrieval_trace": {
-                "route_mode": "hybrid_code_first",
-                "requirement_interpretation": {
-                    "intent": "3. No Circular Dependency Khong co cycle trong dependency graph giua modules/services.",
-                    "control_objective": "1. Decoupling",
-                    "evidence_targets": ["docs", "code"],
-                    "code_targets": [
-                        "pom.xml",
-                        "src/main/java/acme/AppConfig.java",
-                    ],
-                    "code_markers": [],
-                    "docs_markers": [],
-                    "process_markers": [],
-                },
-                "evidence_ref_sets": {
-                    "final_cited_refs": [
-                        "src/main/java/acme/AppConfig.java",
-                        "pom.xml",
-                    ],
-                    "exploratory_refs": [
-                        "src/main/java/acme/AppConfig.java",
-                        "pom.xml",
-                    ],
-                },
-            },
-            "evidence_anchors": [],
-        }
-    ]
-
-    output_path = tmp_path / "audit-checklist.retrieval-trace.json"
-    _write_retrieval_trace_sidecar(output_path, row_results=row_results)  # type: ignore[arg-type]
-    payload = json.loads(output_path.read_text(encoding="utf-8"))
-
-    row = payload["rows"][0]
-    assert row["analysis_mode"] == "hybrid_balanced"
-    assert "generic_metadata_exemption_blocked_by_substantive_code" in row["analysis_reason_codes"]
-    assert row["required_anchor_modalities"] == ["code", "docs"]
-    assert row["generic_anchor_exemption"] is False
-    assert row["minimum_substantive_code_anchors"] == 1
-    assert row["finalization_policy"] == "mixed_modalities_preserve_strong_code"
-
-
-def test_retrieval_trace_sidecar_backfills_requirement_analysis_from_route_mode_only(
-    tmp_path,
-) -> None:
-    row_results = [
-        {
-            "row_id": "R3",
-            "check_id": "CL-999",
-            "status": "FAIL",
-            "score": 5.0,
-            "retry_count": 0,
-            "retrieval_trace": {
-                "route_mode": "docs_only",
-                "requirement_interpretation": {},
-            },
-            "evidence_anchors": [],
-        }
-    ]
-
-    output_path = tmp_path / "audit-checklist.retrieval-trace.json"
-    _write_retrieval_trace_sidecar(output_path, row_results=row_results)  # type: ignore[arg-type]
-    payload = json.loads(output_path.read_text(encoding="utf-8"))
-
-    row = payload["rows"][0]
-    assert row["analysis_mode"] == "docs_first"
-    assert row["analysis_reason_codes"] == ["route_metadata_fallback", "route_mode_inference"]
-    assert row["required_anchor_modalities"] == ["docs"]
-    assert row["generic_anchor_exemption"] is False
-    assert row["minimum_substantive_code_anchors"] == 0
-    assert row["finalization_policy"] == "docs_primary"
-
-
-def test_retrieval_trace_sidecar_tool_summary_emits_top_k_timeout_fallback_diagnostics(tmp_path) -> None:
-    row_results = [
-        RowEvaluationResult(
-            row_id="CL-004:row_3",
-            check_id="CL-004",
-            status=RowStatus.ERROR,
-            score=0.0,
-            score_breakdown=ScoreBreakdown.compute(raw_score=0.0),
-            reason="grounding failure",
-            finding="grounding failure",
-            evidence_anchors=[],
-            provenance=RowProvenance(row_llm_mode="per-row", template_hash="tpl", evidence_hash="evd"),
-            retrieval_trace={
-                "tool_first_loop": {
-                    "steps_executed": 4,
-                    "top_k_code_read_contract_applies": True,
-                    "top_k_target": 3,
-                    "top_k_read_count": 1,
-                    "top_k_read_met": False,
-                    "top_k_read_shortfall_reason": "timeout_or_step_bound",
-                    "code_ranking_diagnostics": {
-                        "top_k_code_read_contract": {
-                            "applies": True,
-                            "target_k": 3,
-                            "top_k_read_count": 1,
-                            "top_k_read_met": False,
-                            "top_k_read_shortfall": 2,
-                            "top_k_read_shortfall_reason": "timeout_or_step_bound",
-                        }
-                    },
-                }
-            },
-        )
-    ]
-
-    output_path = tmp_path / "audit-checklist.retrieval-trace.json"
-    _write_retrieval_trace_sidecar(output_path, row_results=row_results)
-    payload = json.loads(output_path.read_text(encoding="utf-8"))
-
-    summary = payload["rows"][0]["tool_call_summary"]
-    assert summary["top_k_code_read_contract_applies"] is True
-    assert summary["top_k_target"] == 3
-    assert summary["top_k_read_count"] == 1
-    assert summary["top_k_read_met"] is False
-    assert summary["top_k_read_shortfall_reason"] == "timeout_or_step_bound"
-    assert summary["top_k_effective"] == 1
-    assert summary["top_k_fallback_applied"] is True
-    assert summary["top_k_bounded_soft_pass"] is True
-
-
-def test_retrieval_trace_sidecar_projects_route_from_trace_steps_when_loop_route_fields_missing(tmp_path) -> None:
-    row_results = [
-        RowEvaluationResult(
-            row_id="CL-001:row_0",
-            check_id="CL-001",
-            status=RowStatus.FAIL,
-            score=29.75,
-            score_breakdown=ScoreBreakdown.compute(raw_score=2.975),
-            reason="architecture drift detected",
-            finding="framework dependency leak",
-            evidence_anchors=[],
-            provenance=RowProvenance(row_llm_mode="per-row", template_hash="tpl", evidence_hash="evd"),
-            retrieval_trace={
-                "tool_first_loop": {
-                    "docs_search_count": 2,
-                    "docs_read_count": 5,
-                    "code_search_count": 1,
-                    "code_read_count": 3,
-                    "trace_steps": [
-                        {
-                            "step": 1,
-                            "tool": "get_row_context",
-                            "route_id": "hybrid_code_first_search_read_verify_synthesize",
-                            "route_reason": "targets=docs; dual_evidence_targets",
-                        }
-                    ],
-                },
-                "evidence_ref_sets": {
-                    "exploratory_ref_count": 23,
-                    "final_cited_ref_count": 2,
-                    "citation_retention_rate": 2.0 / 23.0,
-                },
-            },
-        )
-    ]
-
-    output_path = tmp_path / "audit-checklist.retrieval-trace.json"
-    _write_retrieval_trace_sidecar(output_path, row_results=row_results)
-    payload = json.loads(output_path.read_text(encoding="utf-8"))
-
-    row = payload["rows"][0]
-    assert row["route_id"] == "hybrid_code_first_search_read_verify_synthesize"
-    assert row["route_mode"] == "hybrid_code_first"
-    assert row["route_reason"] == "targets=docs; dual_evidence_targets"
-    assert row["docs_search_count"] == 2
-    assert row["docs_read_count"] == 5
-    assert row["code_search_count"] == 1
-    assert row["code_read_count"] == 3
-    assert row["exploratory_ref_count"] == 23
-    assert row["final_cited_ref_count"] == 2
-    assert row["citation_retention_rate"] == pytest.approx(2.0 / 23.0, abs=1e-9)
-
-
-def test_retrieval_trace_sidecar_projects_requirement_analysis_fields(tmp_path) -> None:
-    row_results = [
-        RowEvaluationResult(
-            row_id="CL-003:row_2",
-            check_id="CL-003",
-            status=RowStatus.FAIL,
-            score=24.0,
-            score_breakdown=ScoreBreakdown.compute(raw_score=2.4),
-            reason="generic anchor survived",
-            finding="dependency graph evidence is still too generic",
-            evidence_anchors=[],
-            provenance=RowProvenance(row_llm_mode="per-row", template_hash="tpl", evidence_hash="evd"),
-            retrieval_trace={
-                "tool_first_loop": {
-                    "route_id": "hybrid_code_first_search_read_verify_synthesize",
-                    "route_mode": "hybrid_code_first",
-                    "docs_search_count": 1,
-                    "docs_read_count": 1,
-                    "code_search_count": 1,
-                    "code_read_count": 2,
-                    "requirement_analysis": {
-                        "analysis_mode": "code_first",
-                        "analysis_reason_codes": ["decoupling_cycle_row", "code_first_requirement"],
-                        "required_anchor_modalities": ["code"],
-                        "generic_anchor_exemption": False,
-                        "minimum_substantive_code_anchors": 1,
-                        "finalization_policy": "code_substantive_required",
-                    },
-                }
-            },
-        )
-    ]
-
-    output_path = tmp_path / "audit-checklist.retrieval-trace.json"
-    _write_retrieval_trace_sidecar(output_path, row_results=row_results)
-    payload = json.loads(output_path.read_text(encoding="utf-8"))
-
-    row = payload["rows"][0]
-    assert row["analysis_mode"] == "code_first"
-    assert row["analysis_reason_codes"] == ["decoupling_cycle_row", "code_first_requirement"]
-    assert row["required_anchor_modalities"] == ["code"]
-    assert row["generic_anchor_exemption"] is False
-    assert row["minimum_substantive_code_anchors"] == 1
-    assert row["finalization_policy"] == "code_substantive_required"
-
-
-def test_retrieval_trace_sidecar_projects_requirement_analysis_from_code_ranking_diagnostics(tmp_path) -> None:
-    row_results = [
-        RowEvaluationResult(
-            row_id="CL-003:row_2",
-            check_id="CL-003",
-            status=RowStatus.FAIL,
-            score=12.0,
-            score_breakdown=ScoreBreakdown.compute(raw_score=1.2),
-            reason="generic anchor survived",
-            finding="dependency graph evidence is still too generic",
-            evidence_anchors=[],
-            provenance=RowProvenance(row_llm_mode="per-row", template_hash="tpl", evidence_hash="evd"),
-            retrieval_trace={
-                "tool_first_loop": {
-                    "route_id": "hybrid_code_first_search_read_verify_synthesize",
-                    "route_mode": "hybrid_code_first",
-                    "docs_search_count": 1,
-                    "docs_read_count": 1,
-                    "code_search_count": 1,
-                    "code_read_count": 2,
-                    "code_ranking_diagnostics": {
-                        "requirement_analysis": {
-                            "analysis_mode": "code_first",
-                            "analysis_reason_codes": [
-                                "decoupling_cycle_row",
-                                "code_first_requirement",
-                                "decoupling_cycle_row",
-                            ],
-                            "required_anchor_modalities": ["code", "docs", "invalid", "code"],
-                            "generic_anchor_exemption": False,
-                            "minimum_substantive_code_anchors": "2",
-                            "finalization_policy": "code_substantive_required",
-                        }
-                    },
-                }
-            },
-        )
-    ]
-
-    output_path = tmp_path / "audit-checklist.retrieval-trace.json"
-    _write_retrieval_trace_sidecar(output_path, row_results=row_results)
-    payload = json.loads(output_path.read_text(encoding="utf-8"))
-
-    row = payload["rows"][0]
-    assert row["analysis_mode"] == "code_first"
-    assert row["analysis_reason_codes"] == ["decoupling_cycle_row", "code_first_requirement"]
-    assert row["required_anchor_modalities"] == ["code", "docs"]
-    assert row["generic_anchor_exemption"] is False
-    assert row["minimum_substantive_code_anchors"] == 2
-    assert row["finalization_policy"] == "code_substantive_required"
-
-
-def test_retrieval_trace_sidecar_backfills_requirement_analysis_from_route_reason_and_interpretation(tmp_path) -> None:
-    row_results = [
-        RowEvaluationResult(
-            row_id="CL-036:row_35",
-            check_id="CL-036",
-            status=RowStatus.FAIL,
-            score=42.0,
-            score_breakdown=ScoreBreakdown.compute(raw_score=4.2),
-            reason="substantive code anchor required",
-            finding="fallback inference should project requirement-analysis diagnostics",
-            evidence_anchors=[],
-            provenance=RowProvenance(row_llm_mode="per-row", template_hash="tpl", evidence_hash="evd"),
-            retrieval_trace={
-                "requirement_interpretation": {
-                    "intent": "Validate decoupling through source-level implementation evidence.",
-                    "control_objective": "Architecture",
-                    "evidence_targets": ["code"],
-                    "code_targets": ["src/main/java/com/acme/domain/OrderService.java"],
-                    "docs_markers": [],
-                    "code_markers": ["decoupling"],
-                    "process_markers": [],
-                },
-                "tool_first_loop": {
-                    "route_mode": "hybrid_code_first",
-                    "route_reason": (
-                        "targets=code; control_objective=architecture; risk_focus=quality;"
-                        " confidence=0.86; analysis_mode=code_first; finalization_policy=code_substantive_required"
-                    ),
-                    "code_search_count": 2,
-                    "code_read_count": 1,
-                    "docs_intent_utilization": {"docs_target": False, "code_target": True},
-                },
-            },
-        )
-    ]
-
-    output_path = tmp_path / "audit-checklist.retrieval-trace.json"
-    _write_retrieval_trace_sidecar(output_path, row_results=row_results)
-    payload = json.loads(output_path.read_text(encoding="utf-8"))
-
-    row = payload["rows"][0]
-    assert row["analysis_mode"] == "code_first"
-    assert row["finalization_policy"] == "code_substantive_required"
-    assert row["required_anchor_modalities"] == ["code"]
-    assert row["minimum_substantive_code_anchors"] == 1
-    assert row["generic_anchor_exemption"] is False
-    assert "route_reason_analysis_mode_hint" in row["analysis_reason_codes"]
-
-
-def test_retrieval_trace_sidecar_backfills_requirement_analysis_from_route_metadata_without_interpretation(
-    tmp_path,
-) -> None:
-    row_results = [
-        RowEvaluationResult(
-            row_id="CL-010:row_9",
-            check_id="CL-010",
-            status=RowStatus.FAIL,
-            score=33.0,
-            score_breakdown=ScoreBreakdown.compute(raw_score=3.3),
-            reason="mixed-modality requirement",
-            finding="route metadata fallback should keep diagnostics machine-readable",
-            evidence_anchors=[],
-            provenance=RowProvenance(row_llm_mode="per-row", template_hash="tpl", evidence_hash="evd"),
-            retrieval_trace={
-                "tool_first_loop": {
-                    "route_mode": "hybrid_code_first",
-                    "route_reason": (
-                        "targets=code,docs; control_objective=security; risk_focus=quality;"
-                        " confidence=0.73; analysis_mode=hybrid_balanced;"
-                        " finalization_policy=mixed_modalities_preserve_strong_code"
-                    ),
-                    "code_search_count": 1,
-                    "code_read_count": 1,
-                    "docs_search_count": 1,
-                    "docs_read_count": 1,
-                    "docs_intent_utilization": {"docs_target": True, "code_target": True},
-                },
-            },
-        )
-    ]
-
-    output_path = tmp_path / "audit-checklist.retrieval-trace.json"
-    _write_retrieval_trace_sidecar(output_path, row_results=row_results)
-    payload = json.loads(output_path.read_text(encoding="utf-8"))
-
-    row = payload["rows"][0]
-    assert row["analysis_mode"] == "hybrid_balanced"
-    assert row["finalization_policy"] == "mixed_modalities_preserve_strong_code"
-    assert row["required_anchor_modalities"] == ["code", "docs"]
-    assert row["minimum_substantive_code_anchors"] == 1
-    assert row["generic_anchor_exemption"] is False
-    assert "route_reason_analysis_mode_hint" in row["analysis_reason_codes"]
-
-
-def test_retrieval_trace_sidecar_projects_mixed_requirement_analysis_from_promoted_trace(tmp_path) -> None:
-    raw_trace = {
-        "requirement_analysis": {
-            "analysis_mode": "code_first",
-            "analysis_reason_codes": ["code_first_requirement"],
-            "required_anchor_modalities": ["code"],
-            "generic_anchor_exemption": False,
-            "minimum_substantive_code_anchors": 0,
-            "finalization_policy": "code_substantive_required",
-        },
-        "tool_first_loop": {
-            "route_id": "hybrid_code_first_search_read_verify_synthesize",
-            "route_mode": "hybrid_code_first",
-            "docs_search_count": 1,
-            "docs_read_count": 1,
-            "code_search_count": 1,
-            "code_read_count": 2,
-            "code_ranking_diagnostics": {
-                "requirement_analysis": {
-                    "analysis_mode": "hybrid_balanced",
-                    "analysis_reason_codes": ["mixed_modalities_required", "code_marker_signal"],
-                    "required_anchor_modalities": ["code", "docs"],
-                    "generic_anchor_exemption": False,
-                    "minimum_substantive_code_anchors": 1,
-                    "finalization_policy": "mixed_modalities_preserve_strong_code",
-                }
-            },
-        },
-    }
-    promoted_trace = RowEvaluator._promote_requirement_analysis_diagnostics(raw_trace)
-
-    row_results = [
-        RowEvaluationResult(
-            row_id="CL-010:row_9",
-            check_id="CL-010",
-            status=RowStatus.FAIL,
-            score=35.0,
-            score_breakdown=ScoreBreakdown.compute(raw_score=3.5),
-            reason="mixed row requires both docs and code anchors",
-            finding="docs/code modality evidence dropped after narrowing",
-            evidence_anchors=[],
-            provenance=RowProvenance(row_llm_mode="per-row", template_hash="tpl", evidence_hash="evd"),
-            retrieval_trace=promoted_trace,
-        )
-    ]
-
-    output_path = tmp_path / "audit-checklist.retrieval-trace.json"
-    _write_retrieval_trace_sidecar(output_path, row_results=row_results)
-    payload = json.loads(output_path.read_text(encoding="utf-8"))
-
-    row = payload["rows"][0]
-    assert row["analysis_mode"] == "hybrid_balanced"
-    assert row["analysis_reason_codes"] == ["mixed_modalities_required", "code_marker_signal"]
-    assert row["required_anchor_modalities"] == ["code", "docs"]
-    assert row["minimum_substantive_code_anchors"] == 1
-    assert row["finalization_policy"] == "mixed_modalities_preserve_strong_code"
-
-
-def test_retrieval_trace_sidecar_prefers_richer_requirement_analysis_without_pre_promotion(tmp_path) -> None:
-    row_results = [
-        RowEvaluationResult(
-            row_id="CL-010:row_9",
-            check_id="CL-010",
-            status=RowStatus.FAIL,
-            score=35.0,
-            score_breakdown=ScoreBreakdown.compute(raw_score=3.5),
-            reason="mixed row requires both docs and code anchors",
-            finding="docs/code modality evidence dropped after narrowing",
-            evidence_anchors=[],
-            provenance=RowProvenance(row_llm_mode="per-row", template_hash="tpl", evidence_hash="evd"),
-            retrieval_trace={
-                "analysis_mode": "code_first",
-                "analysis_reason_codes": ["code_first_requirement"],
-                "required_anchor_modalities": ["code"],
-                "generic_anchor_exemption": False,
-                "minimum_substantive_code_anchors": 0,
-                "finalization_policy": "code_substantive_required",
-                "tool_first_loop": {
-                    "route_id": "hybrid_code_first_search_read_verify_synthesize",
-                    "route_mode": "hybrid_code_first",
-                    "docs_search_count": 1,
-                    "docs_read_count": 1,
-                    "code_search_count": 1,
-                    "code_read_count": 2,
-                    "code_ranking_diagnostics": {
-                        "requirement_analysis": {
-                            "analysis_mode": "hybrid_balanced",
-                            "analysis_reason_codes": ["mixed_modalities_required", "code_marker_signal"],
-                            "required_anchor_modalities": ["code", "docs"],
-                            "generic_anchor_exemption": False,
-                            "minimum_substantive_code_anchors": 1,
-                            "finalization_policy": "mixed_modalities_preserve_strong_code",
-                        }
-                    },
-                },
-            },
-        )
-    ]
-
-    output_path = tmp_path / "audit-checklist.retrieval-trace.json"
-    _write_retrieval_trace_sidecar(output_path, row_results=row_results)
-    payload = json.loads(output_path.read_text(encoding="utf-8"))
-
-    row = payload["rows"][0]
-    assert row["analysis_mode"] == "hybrid_balanced"
-    assert row["analysis_reason_codes"] == ["mixed_modalities_required", "code_marker_signal"]
-    assert row["required_anchor_modalities"] == ["code", "docs"]
-    assert row["minimum_substantive_code_anchors"] == 1
-    assert row["finalization_policy"] == "mixed_modalities_preserve_strong_code"
-
-
-def test_retrieval_trace_sidecar_clamps_citation_retention_to_denominator(tmp_path) -> None:
-    row_results = [
-        RowEvaluationResult(
-            row_id="CL-033:row_32",
-            check_id="CL-033",
-            status=RowStatus.FAIL,
-            score=0.0,
-            score_breakdown=ScoreBreakdown.compute(raw_score=0.0),
-            reason="infra artifact missing",
-            finding="docker-compose missing",
-            evidence_anchors=[],
-            provenance=RowProvenance(row_llm_mode="per-row", template_hash="tpl", evidence_hash="evd"),
-            retrieval_trace={
-                "exploratory_ref_count": 1,
-                "final_cited_ref_count": 2,
-                "citation_retention_rate": 2.0,
-            },
-        )
-    ]
-
-    output_path = tmp_path / "audit-checklist.retrieval-trace.json"
-    _write_retrieval_trace_sidecar(output_path, row_results=row_results)
-    payload = json.loads(output_path.read_text(encoding="utf-8"))
-
-    row = payload["rows"][0]
-    assert row["exploratory_ref_count"] == 1
-    assert row["final_cited_ref_count"] == 1
-    assert row["citation_retention_rate"] == pytest.approx(1.0, abs=1e-9)
-
-
-def test_sanitize_private_urls_in_payload_redacts_internal_hosts() -> None:
-    payload = {
-        "source_url": "http://10.254.136.35:8090/pages/viewpage.action?pageId=88722450",
-        "excerpt": "Ref http://10.254.136.35:8090/display/TMP/List+US+phase+7 and https://example.com/docs",
-        "plain_ip": "Service endpoint 10.10.100.31 and public host 8.8.8.8",
-        "nested": [
-            {"url": "http://192.168.1.10:8080/api"},
-            {"url": "https://public.example.com/path"},
-        ],
-    }
-
-    sanitized = _sanitize_private_urls_in_payload(payload)
-    assert sanitized["source_url"] == "https://confluence.local/pages/viewpage.action?pageId=88722450"
-    assert "10.254.136.35" not in sanitized["excerpt"]
-    assert "internal-host-redacted:8090" in sanitized["excerpt"]
-    assert "https://example.com/docs" in sanitized["excerpt"]
-    assert "10.10.100.31" not in sanitized["plain_ip"]
-    assert "internal-ip-redacted" in sanitized["plain_ip"]
-    assert "8.8.8.8" in sanitized["plain_ip"]
-    assert sanitized["nested"][0]["url"] == "https://internal-host-redacted:8080/api"
-    assert sanitized["nested"][1]["url"] == "https://public.example.com/path"
-
-
-def test_retrieval_trace_sidecar_sanitizes_private_urls_in_trace(tmp_path) -> None:
-    row_results = [
-        RowEvaluationResult(
-            row_id="CL-555:row_0",
-            check_id="CL-555",
-            status=RowStatus.PASS,
-            score=90.0,
-            score_breakdown=ScoreBreakdown.compute(raw_score=90.0),
-            reason="ok",
-            finding="ok",
-            evidence_anchors=[],
-            provenance=RowProvenance(row_llm_mode="per-row", template_hash="tpl", evidence_hash="evd"),
-            retrieval_trace={
-                "tool_first_loop": {
-                    "trace_steps": [
-                        {
-                            "step": 1,
-                            "tool": "read_doc_chunk",
-                            "output": {
-                                "title": "http://10.254.136.35:8090/pages/viewpage.action?pageId=88722450",
-                                "source_url": "http://10.254.136.35:8090/display/TMP/5.2.+KBKT",
-                                "excerpt": "Nodes: 10.10.151.188 and 8.8.8.8",
-                            },
-                        }
-                    ]
-                }
-            },
-        )
-    ]
-
-    output_path = tmp_path / "audit-checklist.retrieval-trace.json"
-    _write_retrieval_trace_sidecar(output_path, row_results=row_results)
-    serialized = output_path.read_text(encoding="utf-8")
-
-    assert "10.254.136.35" not in serialized
-    assert "10.10.151.188" not in serialized
-    assert "confluence.local/pages/viewpage.action?pageId=88722450" in serialized
-    assert "internal-host-redacted:8090/display/TMP/5.2.+KBKT" in serialized
-    assert "internal-ip-redacted" in serialized
-    assert "8.8.8.8" in serialized